Function: org-cite-make-insert-processor

org-cite-make-insert-processor is a byte-compiled function defined in oc.el.gz.

Signature

(org-cite-make-insert-processor SELECT-KEY SELECT-STYLE)

Documentation

Build a function appropriate as an insert processor.

SELECT-KEY is a function called with one argument. When it is nil, the function should return a citation key as a string, or nil. Otherwise, the function should return a list of such keys, or nil. The keys should not have any leading "@" character.

SELECT-STYLE is a function called with one argument, the citation object being edited or constructed so far. It should return a style string, or nil.

The return value is a function of two arguments: CONTEXT and ARG. CONTEXT is either a citation reference, a citation object, or nil. ARG is a prefix argument.

The generated function inserts or edits a citation at point. More specifically,

  On a citation reference:

    - on the prefix or right before the "@" character, insert
      a new reference before the current one,
    - on the suffix, insert it after the reference,
    - otherwise, update the cite key, preserving both affixes.

    When ARG is non-nil, remove the reference, possibly removing
    the whole citation if it contains a single reference.

  On a citation object:

    - on the style part, offer to update it,
    - on the global prefix, add a new reference before the first
      one,
    - on the global suffix, add a new reference after the last
      one.

  Elsewhere, insert a citation at point. When ARG is non-nil,
  offer to complete style in addition to references.

Source Code

;; Defined in /usr/src/emacs/lisp/org/oc.el.gz
(defun org-cite-make-insert-processor (select-key select-style)
  "Build a function appropriate as an insert processor.

SELECT-KEY is a function called with one argument.  When it is
nil, the function should return a citation key as a string, or
nil.  Otherwise, the function should return a list of such keys,
or nil.  The keys should not have any leading \"@\" character.

SELECT-STYLE is a function called with one argument, the citation
object being edited or constructed so far.  It should return
a style string, or nil.

The return value is a function of two arguments: CONTEXT and ARG.
CONTEXT is either a citation reference, a citation object, or
nil.  ARG is a prefix argument.

The generated function inserts or edits a citation at point.
More specifically,

  On a citation reference:

    - on the prefix or right before the \"@\" character, insert
      a new reference before the current one,
    - on the suffix, insert it after the reference,
    - otherwise, update the cite key, preserving both affixes.

    When ARG is non-nil, remove the reference, possibly removing
    the whole citation if it contains a single reference.

  On a citation object:

    - on the style part, offer to update it,
    - on the global prefix, add a new reference before the first
      one,
    - on the global suffix, add a new reference after the last
      one.

  Elsewhere, insert a citation at point.  When ARG is non-nil,
  offer to complete style in addition to references."
  (unless (and (functionp select-key) (functionp select-style))
    (error "Wrong argument type(s)"))
  (lambda (context arg)
    (pcase (org-element-type context)
      ;; When on a citation, check point is not on the blanks after it.
      ;; Otherwise, consider we're after it.
      ((and 'citation
            (guard
             (let ((boundaries (org-cite-boundaries context)))
               (and (< (point) (cdr boundaries))
                    (> (point) (car boundaries))))))
       ;; When ARG is non-nil, delete the whole citation.  Otherwise,
       ;; action depends on the point.
       (if arg
           (org-cite-delete-citation context)
         (let* ((begin (org-element-begin context))
                (style-end (1- (org-with-point-at begin (search-forward ":")))))
           (if (>= style-end (point))
               ;; On style part, edit the style.
               (let ((style-start (+ 5 begin))
                     (style (funcall select-style context)))
                 (unless style (user-error "Aborted"))
                 (org-with-point-at style-start
                   (delete-region style-start style-end)
                   (when (org-string-nw-p style) (insert "/" style))))
             ;; On an affix, insert a new reference before or after
             ;; point.
             (let* ((references (org-cite-get-references context))
                    (key (concat "@" (funcall select-key nil))))
               (if (< (point) (org-element-contents-begin context))
                   (org-cite--insert-string-before key (car references))
                 (org-cite--insert-string-after key (org-last references))))))))
      ;; On a citation reference.  If ARG is not nil, remove the
      ;; reference.  Otherwise, action depends on the point.
      ((and 'citation-reference (guard arg)) (org-cite-delete-citation context))
      ('citation-reference
       (pcase-let* ((`(,start . ,end) (org-cite-key-boundaries context))
                    (key (concat "@"
                                 (or (funcall select-key nil)
                                     (user-error "Aborted")))))
         ;; Right before the "@" character, do not replace the reference
         ;; at point, but insert a new one before it.  It makes adding
         ;; a new reference at the beginning easier in the following
         ;; case: [cite:@key].
         (cond
          ((>= start (point)) (org-cite--insert-string-before key context))
          ((<= end (point)) (org-cite--insert-string-after key context))
          (t
           (org-with-point-at start
             (delete-region start end)
             (insert key))))))
      (_
       (let ((keys (funcall select-key t)))
         (unless keys (user-error "Aborted"))
         (insert
          (format "[cite%s:%s]"
                  (if arg
                      (let ((style (funcall select-style
                                            (org-cite--keys-to-citation keys))))
                        (if (org-string-nw-p style)
                            (concat "/" style)
                          ""))
                    "")
                  (mapconcat (lambda (k) (concat "@" k)) keys "; "))))))))