Emacs Lisp minibuffer and completion

The minibuffer is the small window at the bottom of a frame where Emacs asks for input. In Lisp it is a set of functions that prompt and return what the user typed, most of them with completion. This page lists the read functions, the shape of completion tables and of completion at point, and the variables that change how the minibuffer behaves.

Reading input

Function	Returns
`read-string PROMPT &optional INITIAL HISTORY DEFAULT INHERIT-INPUT-METHOD`	a string; the simple choice. An empty input gives `""`, or DEFAULT when it is given.
`read-from-minibuffer PROMPT &optional INITIAL KEYMAP READ HIST DEFAULT INHERIT-INPUT-METHOD`	the basic function. A non-`nil` READ makes it return a Lisp object read from the text. KEYMAP replaces `minibuffer-local-map`.
`read-number`	a number
`read-regexp`	a regular expression, with history of earlier ones
`read-file-name`, `read-directory-name`	a file or directory name, with file-name completion
`read-buffer`	a buffer name, with completion
`read-command`, `read-variable`	a command or a variable symbol
`read-passwd PROMPT &optional CONFIRM DEFAULT`	a string typed without echo; CONFIRM asks twice
`read-key`, `read-char`	one key or character, with the prompt in the echo area; `read-key` also applies key translation, so a function key gives its event
`read-char-choice PROMPT CHARS`	one of the characters in the list CHARS
`read-multiple-choice PROMPT CHOICES`	one entry of a list of `(CHAR NAME DESCRIPTION)`; a help key shows the descriptions. From Emacs 29 it can use long-form answers and takes a SHOW-HELP argument; from Emacs 31 it reads through the minibuffer.
`y-or-n-p`, `yes-or-no-p`	a boolean. `y-or-n-p` takes one key press; `yes-or-no-p` asks the user to type `yes` or `no`.
`completing-read`	a string chosen with completion (next section)
`completing-read-multiple`	a list of strings, entered with commas between them (the separator is in `crm-separator`)

(let ((name (read-string "Name: " nil nil user-login-name))
      (n (read-number "How many? " 1)))
  (message "%s x %d" name n))

The user option use-short-answers (Emacs 28), when non-nil, makes yes-or-no-p behave like y-or-n-p. The function format-prompt (Emacs 28) builds a prompt from a text and a default, in the style Name (default me): , and read-answer asks a question with a list of named answers.

(read-string (format-prompt "Project name" "demo") nil nil "demo")

Interactive code letters

The (interactive "…") codes call these functions for you: s and M use read-string, n and N read-number, S reads a symbol, x and X read a Lisp expression, f, F, G and D read a file or directory name, b and B a buffer name, a, C and v a function, command or variable name, c a character, k and K a key sequence, and z and Z a coding system. The full table is on Commands and modes.

completing-read

(completing-read PROMPT COLLECTION &optional PREDICATE REQUIRE-MATCH INITIAL HISTORY DEFAULT INHERIT-INPUT-METHOD)

Argument	Meaning
COLLECTION	the completion table (see below)
PREDICATE	a function that filters candidates; it gets a string, or a cons or a symbol, depending on the table
REQUIRE-MATCH	`nil`: any input may be accepted. `t`: the input must complete to a candidate. `confirm`: any input, but the user is asked to confirm one that is not a candidate. `confirm-after-completion`: the same, only after a completion command. A function: it is called with the input and returns true if it is acceptable.
INITIAL	text that starts in the minibuffer, a string or a cons `(STRING . POSITION)`
HISTORY	a history variable, or a cons of it and a starting position; the default is `minibuffer-history`
DEFAULT	the value returned for an empty input; a list gives its first element
INHERIT-INPUT-METHOD	non-`nil` uses the current input method of the buffer

(completing-read "Colour: " '("red" "green" "blue") nil t nil nil "red")

Completion tables

A completion table (the collection) can be any of these:

Kind	Candidates
list of strings	the strings
list of symbols	the symbol names
alist	the car of each element, a string or a symbol
obarray	the interned symbols
hash table	the keys, strings or symbols
function	a function that takes `(STRING PREDICATE ACTION)` and does the work itself

A function table is called with an ACTION: nil means try-completion, t means all-completions, lambda means test-completion, (boundaries . SUFFIX) asks for the completion boundaries, and metadata asks for the metadata. Ready-made wrappers build such functions:

Function	Use
`complete-with-action`	answer the ACTION from a static table; the usual last line of a function table
`completion-table-dynamic FUN`	call FUN with the current input to get the list; use for tables that depend on the input
`completion-table-with-cache FUN`	the same, but remembers the last argument and result, useful when FUN starts a process
`completion-table-with-metadata TABLE METADATA`	a table like TABLE with an alist as its metadata (Emacs 31)
`completion-table-case-fold`, `completion-table-in-turn`, `completion-table-merge`, `completion-table-subvert`	other combinators

(defun my-table (string pred action)
  (if (eq action 'metadata)
      '(metadata (category . my-thing))
    (complete-with-action action '("alpha" "beta" "gamma") string pred)))

(completing-read "Pick: " #'my-table)

The basic functions

Function	Returns
`try-completion STRING COLLECTION &optional PREDICATE`	`t` for an exact and unique match, `nil` for no match, otherwise the longest common prefix as a string
`all-completions STRING COLLECTION &optional PREDICATE`	a list of the candidates that start with STRING
`test-completion STRING COLLECTION &optional PREDICATE`	true when STRING is exactly a candidate
`completion-boundaries`	the start and end of the part being completed (important for file names)
`completion-metadata`	the metadata of a table at the given input

The variable completion-ignore-case makes the matching ignore case.

Metadata and categories

The metadata is a list (metadata (KEY . VALUE) …). The user interface reads it to decide how to show and sort the candidates.

Key	Value
`category`	a symbol for the kind of thing completed: `file`, `buffer`, `command`, `symbol`, `unicode-name` and others. Users and packages set styles and options by category in `completion-category-defaults` and `completion-category-overrides`.
`annotation-function`	a function from a candidate to a string shown after it
`affixation-function`	a function from a list of candidates to a list of `(CANDIDATE PREFIX SUFFIX)`
`group-function`	a function that gives each candidate a heading, or transforms its display
`display-sort-function`, `cycle-sort-function`	sort the candidates for display and for cycling

Completion styles

A style decides which candidates match the typed text. The user option completion-styles holds a list of style symbols that are tried in order; each must have an entry in completion-styles-alist. Styles per category are set in completion-category-overrides.

Style	Matches
`basic`	the text as a prefix, and also text after point as a substring
`partial-completion`	words separated by punctuation as separate prefixes: `em-l-m` matches `emacs-lisp-mode`
`emacs22`	a prefix only, up to point
`substring`	the text anywhere in the candidate
`flex`	the characters in order, not necessarily next to each other
`initials`	the initials of words: `lch` matches `lazy-completion-helper`

Completion at point

Completion in an ordinary buffer is done by completion-at-point, bound to C-M-i in most modes. It calls the functions of the abnormal hook completion-at-point-functions (capf) in turn, until one returns a result. A capf takes no arguments, looks at point, and returns nil when it does not apply, or a list:

(START END COLLECTION . PROPERTIES)

START and END delimit the text before point that is to be replaced, and COLLECTION is a completion table. The properties are keyword and value pairs, such as :predicate, :annotation-function, :exit-function (called with the chosen string and a status after insertion), :exclusive (no lets the next function try when nothing matches) and :company-docsig, :company-kind, :affixation-function.

(defun my-capf ()
  (let ((bounds (bounds-of-thing-at-point 'symbol)))
    (when bounds
      (list (car bounds) (cdr bounds)
            '("alpha" "beta" "gamma")
            :exclusive 'no))))

(add-hook 'completion-at-point-functions #'my-capf nil t)

History

Each read keeps a history list, a variable of strings with the newest first. The default is minibuffer-history; other lists exist for commands, files, regexps, and so on. add-to-history HISTORY-VAR NEWELT &optional MAXELT KEEP-ALL adds an element and trims the list; the length limit is history-length (or the history-length property of the variable), and history-delete-duplicates removes repeats. savehist-mode saves histories between sessions.

Hooks, keymaps and recursion

Name	Use
`minibuffer-setup-hook`	run when a minibuffer is entered
`minibuffer-with-setup-hook FUNCTION &rest BODY`	macro: run BODY with FUNCTION added to the setup hook for the next minibuffer only. A form `(:append FUNCTION)` appends it.
`minibuffer-exit-hook`	run when it is left
`minibuffer-local-map`	keymap of ordinary reads
`minibuffer-local-ns-map`	the same, where space exits
`minibuffer-local-completion-map`	keymap when completion is allowed
`minibuffer-local-must-match-map`	keymap when a match is required
`minibuffer-local-filename-completion-map`	file names, where space is not completion
`enable-recursive-minibuffers`	non-`nil` lets a command use the minibuffer while another one is active; `minibuffer-depth` gives the level
`minibuffer-message`	function: show a temporary message at the end of the input

(minibuffer-with-setup-hook #'my-prepare
  (read-string "Text: "))

Not described

Known, not yet covered

Reference: the full list of metadata keys, the interactive commands of the minibuffer (minibuffer-complete, minibuffer-completion-help), and the user options completion-cycle-threshold, completions-format and read-extended-command-predicate.
Reference: the default value of completion-styles differs between versions and is not stated here. The completion-pcm and completion-regexp-list internals are not described.
Reference: the file-name specific reads and tables are used by Files; only the names are listed.

.EL File Format – Minibuffer