annotated-completing-read (acr) is a thin wrapper around the standard emacs
completing-read facility, with a more ergonomic (lisp) interface. It shares a
lot with consult--read, but it’s more lightweight, is part of a public
API. And of course, and works well with vertico (and other minibuffer completion
interfaces), marginalia, and embark (and related tooling).
The annotated-completing-read function has intuitive, easy to read semantics:
keyword arguments for all optional arguments, selection options are a mapping
(hashmap or alist) of options-to-annotations. There are some (bonus) helpers for
selecting a directory from a list of likely options and providing a list of
“dwim” options that includes recent kill-ring items, thing-at-point (and other
likely candidates). Finally, annotated-completing-read manages tracking
history of command selections, so that the order that options are presented to
mold to you over time.
Requires Emacs 29.1+. Run once to clone and register the package:
(package-vc-install
'(annotated-completing-read
:url "https://github.com/tychoish/annotated-completing-read.el"))Requires Emacs 30+. Installs on first load if not already present:
(use-package annotated-completing-read
:vc (:url "https://github.com/tychoish/annotated-completing-read.el"))git clone https://github.com/tychoish/annotated-completing-read.el ~/path/to/annotated-completing-read(use-package annotated-completing-read
:load-path "~/path/to/annotated-completing-read")git clone https://github.com/tychoish/annotated-completing-read.el ~/path/to/annotated-completing-read(add-to-list 'load-path "~/path/to/annotated-completing-read")
(require 'annotated-completing-read)Controls how face properties are applied to annotation strings.
‘default’ — apply ‘completions-annotations’ to annotations that carry no face text property. This is the default. ‘override’ — always apply ‘completions-annotations’, overriding any existing face. ‘strip’ — remove all face text properties from annotations. Any other symbol — treat it as a face name and apply it to annotations that carry no face text property.
Hash table mapping command symbols to per-command minibuffer history lists. Keys are symbols — typically ‘this-command’ at call time — and values are the standard Emacs history lists accumulated by ‘completing-read’.
(fn TABLE &key (PROMPT "=> ") REQUIRE-MATCH CATEGORY HISTORY GROUP-NAME GROUP-DISPLAY INITIAL-INPUT SORT-FN DEFAULT OR-NIL MULTIPLE MIN MAX)
Read a candidate from completion TABLE. TABLE maps candidates to annotations or target values. Alignment is automatic.
TABLE can be a hash table or an alist. A list-form alist uses the format: ((CANDIDATE ANNOTATION) …). A dotted alist uses the format: ((CANDIDATE . ANNOTATION) …). A triple-form alist uses the format: ((CANDIDATE ANNOTATION . TARGET) …). An annotation can be nil.
PROMPT is the minibuffer prompt. It defaults to “=> “. A trailing space is appended if it is missing.
REQUIRE-MATCH forces the user to select an existing candidate. If nil, the minibuffer accepts arbitrary input.
CATEGORY is a symbol for the completion category. External packages like embark or marginalia use it to determine behavior. Common values include ‘file’, ‘buffer’, ‘command’, and ‘symbol’.
HISTORY is a symbol representing the history list. It defaults to ‘this-command’. Use a shared symbol to share history between commands.
GROUP-NAME determines candidate grouping. It can be a function or a static string.
GROUP-DISPLAY formats the candidate text for display. It is a function that takes a candidate string. This option requires GROUP-NAME.
INITIAL-INPUT is an optional string to pre-fill in the minibuffer.
SORT-FN is a function to sort candidates before display.
DEFAULT is the fallback return value. It is returned on empty input or quit.
OR-NIL silences quit and empty input by returning nil. This option takes effect only when DEFAULT is nil.
A table entry can supply an optional TARGET. This TARGET is returned instead of the candidate string. It also affects selection via DEFAULT. It allows packages like embark to act on the target directly.
MULTIPLE allows selecting multiple candidates. It returns an ordered list of selections. Press M-x annotated-completing-read–multi-continue to accept a pick and continue. Press M-x annotated-completing-read–multi-finish-now to finish immediately. Pressing RET accepts the current input and finishes. DEFAULT and OR-NIL apply to the entire session.
MIN is the minimum number of required selections. MAX is the maximum number of allowed selections. Reaching MAX finishes the session automatically. These options require MULTIPLE.
(fn &optional &key CANDIDATES PROMPT REQUIRE-MATCH MULTIPLE MIN MAX)
Select a directory using annotated completion. CANDIDATES is an optional list of directory paths. If nil, candidates are gathered from the current context. PROMPT is the minibuffer prompt. It defaults to “directory: “. Other arguments match ‘annotated-completing-read’. Annotations show directory relationships or entry counts.
(fn &optional &key PROMPT SEED INITIAL-INPUT HISTORY)
Select a candidate from the current editing context. PROMPT is the minibuffer prompt. SEED specifies explicit candidate strings. INITIAL-INPUT is the initial minibuffer text. HISTORY specifies the history list. This function returns an empty string if no candidate is chosen.
Copyright (C) tychoish. GPL-3.0 or later. See the source file header for the full license text.