Function: consult--with-preview

consult--with-preview is a macro defined in consult.el.

Signature

(consult--with-preview PREVIEW-KEY STATE TRANSFORM CANDIDATE SAVE-INPUT &rest BODY)

Documentation

Add preview support to BODY.

STATE is the state function. TRANSFORM is the transformation function. CANDIDATE is the function returning the current candidate. PREVIEW-KEY are the keys which triggers the preview. SAVE-INPUT can be a history variable symbol to save the input.

The state function takes two arguments, an action argument and the selected candidate. The candidate argument can be nil if no candidate is selected or if the selection was aborted. The function is called in sequence with the following arguments:

  1. 'setup nil After entering the mb (minibuffer-setup-hook).
⎧ 2. 'preview CAND/nil Preview candidate CAND or reset if CAND is nil.
⎪ 'preview CAND/nil
⎪ 'preview CAND/nil
⎪ ...
⎩ 3. 'preview nil Reset preview.
  4. 'exit nil Before exiting the mb (minibuffer-exit-hook).
  5. 'return CAND/nil After leaving the mb, CAND has been selected.

The state function is always executed with the original window selected, see consult--original-window. The state function is called once in the beginning of the minibuffer setup with the setup argument. This is useful in order to perform certain setup operations which require that the minibuffer is initialized. During completion candidates are previewed. Then the function is called with the preview argument and a candidate CAND or nil if no candidate is selected. Furthermore if nil is passed for CAND, then the preview must be undone and the original state must be restored. The call with the exit argument happens once at the end of the completion process, just before exiting the minibuffer. The minibuffer is still alive at that point. Both setup and exit are only useful for setup and cleanup operations. They don't receive a candidate as argument. After leaving the minibuffer, the selected candidate or nil is passed to the state function with the action argument return. At this point the state function can perform the actual action on the candidate. The state function with the return argument is the continuation of consult--read. Via unwind-protect it is guaranteed, that if the setup action of a state function is invoked, the state function will also be called with exit and return.

Source Code

;; Defined in ~/.emacs.d/elpa/consult-20260805.1130/consult.el
(defmacro consult--with-preview (preview-key state transform candidate save-input &rest body)
  "Add preview support to BODY.

STATE is the state function.
TRANSFORM is the transformation function.
CANDIDATE is the function returning the current candidate.
PREVIEW-KEY are the keys which triggers the preview.
SAVE-INPUT can be a history variable symbol to save the input.

The state function takes two arguments, an action argument and the
selected candidate.  The candidate argument can be nil if no candidate is
selected or if the selection was aborted.  The function is called in
sequence with the following arguments:

  1. \\='setup nil         After entering the mb (minibuffer-setup-hook).
⎧ 2. \\='preview CAND/nil  Preview candidate CAND or reset if CAND is nil.
⎪    \\='preview CAND/nil
⎪    \\='preview CAND/nil
⎪    ...
⎩ 3. \\='preview nil       Reset preview.
  4. \\='exit nil          Before exiting the mb (minibuffer-exit-hook).
  5. \\='return CAND/nil   After leaving the mb, CAND has been selected.

The state function is always executed with the original window selected,
see `consult--original-window'.  The state function is called once in
the beginning of the minibuffer setup with the `setup' argument.  This is
useful in order to perform certain setup operations which require that
the minibuffer is initialized.  During completion candidates are
previewed.  Then the function is called with the `preview' argument and a
candidate CAND or nil if no candidate is selected.  Furthermore if nil is
passed for CAND, then the preview must be undone and the original state
must be restored.  The call with the `exit' argument happens once at the
end of the completion process, just before exiting the minibuffer.  The
minibuffer is still alive at that point.  Both `setup' and `exit' are
only useful for setup and cleanup operations.  They don't receive a
candidate as argument.  After leaving the minibuffer, the selected
candidate or nil is passed to the state function with the action
argument `return'.  At this point the state function can perform the
actual action on the candidate.  The state function with the `return'
argument is the continuation of `consult--read'.  Via `unwind-protect' it
is guaranteed, that if the `setup' action of a state function is
invoked, the state function will also be called with `exit' and
`return'."
  (declare (indent 5) (debug t))
  `(consult--with-preview-f ,preview-key ,state ,transform ,candidate ,save-input (lambda () ,@body)))