Function: consult--multi

consult--multi is a natively compiled function defined in consult.el.

Signature

(consult--multi SOURCES &rest OPTIONS)

Documentation

Select from candidates taken from a list of SOURCES.

OPTIONS is the plist of options passed to consult--read. The following options are supported: :require-match, :history, :keymap, :initial,
:initial-narrow, :add-history, :sort and :inherit-input-method. The other
options of consult--read are used by the consult--multi implementation and should not be overwritten, except in in special scenarios.

The function returns the selected candidate in the form (cons candidate source-plist). The plist has the key :match with a value nil if the candidate does not exist, t if the candidate exists and new if the candidate has been created.

The sources of the source list can either be symbols of source variables or source values. Sources which are nil are ignored. Source values must be plists with the following fields.

Either the :items or the :async source field is required:
* :items - List of strings to select from or function returning list of
  strings. The function is only called for visible sources, such that
  candidates are only computed on demand. The strings can carry
  metadata in text properties, which is then available to the :annotate,
  :action and :state functions. The list can also consist of pairs,
  with the string in the car used for display and the cdr the actual
  candidate.
* :async - Alternative to :items for asynchronous sources. The curried
  function receives an asynchronous sink and an action as argument as
  documented by consult--async-pipeline.

Optional source fields:
* :name - Name of the source as a string, used for narrowing,
  group titles and annotations.
* :narrow - Narrowing character, (char . string) pair or list of pairs.
* :category - Completion category symbol.
* :enabled - Function which must return t if the source is enabled.
* :hidden - When t candidates of this source are hidden by default.
* :face - Face used for highlighting the candidates.
* :annotate - Annotation function called for each candidate, returns string.
* :history - Name of history variable to add selected candidate.
* :default - Must be t if the first item of the source is the default value.
* :action - Function called with the selected candidate.
* :new - Function called with new candidate name, only if :require-match is nil.
* :state - State constructor for the source, must return the
  state function. The state function is informed about state
  changes of the UI and can be used to implement preview.
* Other custom source fields can be added depending on the use
  case. Note that the source is returned by consult--multi
  together with the selected candidate.

Source Code

;; Defined in /nix/store/6higv2v1wk916v4ynnybyrdkfy2gq44d-emacs-packages-deps/share/emacs/site-lisp/elpa/consult-20261004.957/consult.el
(defun consult--multi (sources &rest options)
  "Select from candidates taken from a list of SOURCES.

OPTIONS is the plist of options passed to `consult--read'.  The following
options are supported: :require-match, :history, :keymap, :initial,
:initial-narrow, :add-history, :sort and :inherit-input-method.  The other
options of `consult--read' are used by the `consult--multi' implementation
and should not be overwritten, except in in special scenarios.

The function returns the selected candidate in the form (cons candidate
source-plist).  The plist has the key :match with a value nil if the
candidate does not exist, t if the candidate exists and `new' if the
candidate has been created.

The sources of the source list can either be symbols of source variables
or source values.  Sources which are nil are ignored.  Source values
must be plists with the following fields.

Either the :items or the :async source field is required:
* :items - List of strings to select from or function returning list of
  strings.  The function is only called for visible sources, such that
  candidates are only computed on demand.  The strings can carry
  metadata in text properties, which is then available to the :annotate,
  :action and :state functions.  The list can also consist of pairs,
  with the string in the `car' used for display and the `cdr' the actual
  candidate.
* :async - Alternative to :items for asynchronous sources.  The curried
  function receives an asynchronous sink and an action as argument as
  documented by `consult--async-pipeline'.

Optional source fields:
* :name - Name of the source as a string, used for narrowing,
  group titles and annotations.
* :narrow - Narrowing character, (char . string) pair or list of pairs.
* :category - Completion category symbol.
* :enabled - Function which must return t if the source is enabled.
* :hidden - When t candidates of this source are hidden by default.
* :face - Face used for highlighting the candidates.
* :annotate - Annotation function called for each candidate, returns string.
* :history - Name of history variable to add selected candidate.
* :default - Must be t if the first item of the source is the default value.
* :action - Function called with the selected candidate.
* :new - Function called with new candidate name, only if :require-match is nil.
* :state - State constructor for the source, must return the
  state function.  The state function is informed about state
  changes of the UI and can be used to implement preview.
* Other custom source fields can be added depending on the use
  case.  Note that the source is returned by `consult--multi'
  together with the selected candidate."
  (let* ((sources (consult--multi-enabled-sources sources))
         (async (cl-loop for src across sources thereis (plist-get src :async)))
         (selected
          (apply #'consult--read
                 (if async (consult--multi-async sources) (consult--multi-static sources))
                 (append
                  options
                  (list
                   :category    'multi-category
                   :async-wrap  (and async #'consult--async-wrap)
                   :predicate   (and async (apply-partially #'consult--multi-async-predicate sources))
                   :annotate    (apply-partially #'consult--multi-annotate sources)
                   :group       (apply-partially #'consult--multi-group sources)
                   :lookup      (apply-partially #'consult--multi-lookup sources)
                   :preview-key (consult--multi-preview-key sources)
                   :narrow      (consult--multi-narrow sources)
                   :state       (consult--multi-state sources))))))
    (when-let* ((history (plist-get (cdr selected) :history))
                (elem (car selected)))
      (add-to-history history (if (bufferp elem) (buffer-name elem) elem)))
    (if (plist-member (cdr selected) :match)
        (when-let* ((fun (plist-get (cdr selected) :new)))
          (funcall fun (car selected))
          (plist-put (cdr selected) :match 'new))
      (when-let* ((fun (plist-get (cdr selected) :action)))
        (funcall fun (car selected)))
      (setq selected `(,(car selected) :match t ,@(cdr selected))))
    selected))