Function: consult--read

consult--read is a byte-compiled function defined in consult.el.

Signature

(consult--read TABLE &rest OPTIONS &key PROMPT PREDICATE REQUIRE-MATCH HISTORY DEFAULT COMMAND KEYMAP CATEGORY INITIAL NARROW INITIAL-NARROW ANNOTATE ADD-HISTORY STATE PREVIEW-KEY SORT LOOKUP GROUP INHERIT-INPUT-METHOD ASYNC-WRAP)

Documentation

Enhanced completing read function to select from TABLE.

The function is a thin wrapper around completing-read. Keyword arguments are used instead of positional arguments for code clarity. On top of completing-read it additionally supports computing the candidate list asynchronously, candidate preview and narrowing. You should use completing-read instead of consult--read if you don't use asynchronous candidate computation or candidate preview.

Keyword OPTIONS:

PROMPT is the string which is shown as prompt in the minibuffer. PREDICATE is a filter function called for each candidate, returns nil or t. REQUIRE-MATCH equals t means that an exact match is required. HISTORY is the symbol of the history variable. DEFAULT is the default selected value. ADD-HISTORY is a list of items to add to the history. CATEGORY is the completion category symbol. COMMAND is used for customization, defaulting to this-command. SORT should be set to nil if the candidates are already sorted. This will disable sorting in the completion UI. LOOKUP is a lookup function passed the selected candidate string, the list of candidates, the current input string and the current narrowing value. ANNOTATE is a function passed a candidate string. The function should either return an annotation string or a list of three strings (candidate prefix postfix). INITIAL is the initial input string. STATE is the state function, see consult--with-preview. GROUP is a completion metadata group-function as documented in the Elisp manual. PREVIEW-KEY are the preview keys. Can be nil, any, a single key or a list of keys. NARROW is an alist of narrowing prefix strings and description. INITIAL-NARROW is an initial narrow key. KEYMAP is a command-specific keymap. INHERIT-INPUT-METHOD, if non-nil the minibuffer inherits the input method. ASYNC-WRAP wraps asynchronous functions and defaults to consult--async-wrap.

Source Code

;; Defined in ~/.emacs.d/elpa/consult-20260805.1130/consult.el
(cl-defun consult--read ( table &rest options &key
                          prompt predicate require-match history default command
                          keymap category initial narrow initial-narrow annotate
                          add-history state preview-key sort lookup group
                          inherit-input-method async-wrap)
  "Enhanced completing read function to select from TABLE.

The function is a thin wrapper around `completing-read'.  Keyword
arguments are used instead of positional arguments for code
clarity.  On top of `completing-read' it additionally supports
computing the candidate list asynchronously, candidate preview
and narrowing.  You should use `completing-read' instead of
`consult--read' if you don't use asynchronous candidate
computation or candidate preview.

Keyword OPTIONS:

PROMPT is the string which is shown as prompt in the minibuffer.
PREDICATE is a filter function called for each candidate, returns
nil or t.
REQUIRE-MATCH equals t means that an exact match is required.
HISTORY is the symbol of the history variable.
DEFAULT is the default selected value.
ADD-HISTORY is a list of items to add to the history.
CATEGORY is the completion category symbol.
COMMAND is used for customization, defaulting to `this-command.'
SORT should be set to nil if the candidates are already sorted.
This will disable sorting in the completion UI.
LOOKUP is a lookup function passed the selected candidate string,
the list of candidates, the current input string and the current
narrowing value.
ANNOTATE is a function passed a candidate string.  The function
should either return an annotation string or a list of three
strings (candidate prefix postfix).
INITIAL is the initial input string.
STATE is the state function, see `consult--with-preview'.
GROUP is a completion metadata `group-function' as documented in
the Elisp manual.
PREVIEW-KEY are the preview keys.  Can be nil, `any', a single
key or a list of keys.
NARROW is an alist of narrowing prefix strings and description.
INITIAL-NARROW is an initial narrow key.
KEYMAP is a command-specific keymap.
INHERIT-INPUT-METHOD, if non-nil the minibuffer inherits the
input method.
ASYNC-WRAP wraps asynchronous functions and defaults to
`consult--async-wrap'."
  (ignore prompt predicate require-match history default keymap category
          initial narrow initial-narrow add-history annotate state command
          preview-key sort lookup group inherit-input-method async-wrap)
  (apply #'consult--read-1 table
         (consult--customize-args
          options
          :prompt "Select: "
          :preview-key consult-preview-key
          :sort t
          :async-wrap #'consult--async-wrap
          :lookup (lambda (selected &rest _) selected))))