Function: consult--multi

consult--multi is a byte-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 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 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 ~/.emacs.d/elpa/consult-20260805.1130/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 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 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))
         (collection (consult--multi-collection sources))
         (selected
          (apply #'consult--read
                 collection
                 (append
                  options
                  (list
                   :category    'multi-category
                   :predicate   (apply-partially #'consult--multi-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)))
      (add-to-history history (car selected)))
    (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))