Function: completing-read

completing-read is a function defined in minibuf.c.

Signature

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

Documentation

Read a string in the minibuffer, with completion.

While in the minibuffer, you can use TAB (minibuffer-complete) and SPC (minibuffer-complete-word) to complete your input. You can also use C-x <up> (minibuffer-complete-history) to complete using history items in the input history HIST, and you can use C-x <down> (minibuffer-complete-defaults) to complete using the default items in DEFAULT-VALUE.

PROMPT is a string to prompt with; normally it ends in a colon and a space. COLLECTION can be a list of strings, an alist, an obarray or a hash table. COLLECTION can also be a function to do the completion itself. PREDICATE limits completion to a subset of COLLECTION. See try-completion, all-completions, test-completion, and completion-boundaries, for more details on completion, COLLECTION, and PREDICATE. See also Info node (elisp)Basic Completion for the details about completion, and Info node (elisp)Programmed Completion for expectations from COLLECTION when it's a function.

REQUIRE-MATCH can take the following values:
- t means that the user is not allowed to exit unless the input is (or
  completes to) an element of COLLECTION or is null.
- nil means that the user can exit with any input.
- confirm means that the user can exit with any input, but she needs
  to confirm her choice if the input is not an element of COLLECTION.
- confirm-after-completion means that the user can exit with any
  input, but she needs to confirm her choice if she called
  minibuffer-complete right before minibuffer-complete-and-exit
  and the input is not an element of COLLECTION.
- a function, which will be called with the input as the
  argument. If the function returns a non-nil value, the
  minibuffer is exited with that argument as the value.
- anything else behaves like t except that typing RET does not exit if it
  does non-null completion.

If the input is null, completing-read returns DEF, or the first element of the list of default values, or an empty string if DEF is nil, regardless of the value of REQUIRE-MATCH.

If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
  with point positioned at the end. If it is (STRING . POSITION), the
  initial input is STRING, but point is placed at _zero-indexed_
  position POSITION in STRING. (*Note* that this is different from
  read-from-minibuffer and related functions, which use one-indexing
  for POSITION.) This feature is deprecated--it is best to pass nil
  for INITIAL-INPUT and supply the default value DEF instead. The
  user can yank the default value into the minibuffer easily using
  M-n (next-history-element).

HIST, if non-nil, specifies a history list and optionally the initial
  position in the list. It can be a symbol, which is the history list
  variable to use, or it can be a cons cell (HISTVAR . HISTPOS). In
  that case, HISTVAR is the history list variable to use, and HISTPOS
  is the initial position (the position in the list used by the
  minibuffer history commands). For consistency, you should also
  specify that element of the history as the value of INITIAL-INPUT.
  (This is the only case in which you should use INITIAL-INPUT instead
  of DEF.) Positions are counted starting from 1 at the beginning of
  the list. The variable history-length controls the maximum length
  of a history list. If HIST is t, history is not recorded.

DEF, if non-nil, is the default value or the list of default values.

If INHERIT-INPUT-METHOD is non-nil, the minibuffer inherits the
  current input method and the setting of enable-multibyte-characters.

Completion ignores case if the ambient value of
  completion-ignore-case is non-nil.

See also completing-read-function.

View in manual

Probably introduced at or before Emacs version 1.6.

Aliases

org-completing-read-no-i (obsolete since 9.0) org-icompleting-read (obsolete since 9.0)

Source Code

// Defined in /usr/src/emacs/src/minibuf.c
{
  return CALLN (Ffuncall,
		Fsymbol_value (Qcompleting_read_function),
		prompt, collection, predicate, require_match, initial_input,
		hist, def, inherit_input_method);
}