completing-read

completing-read is a built-in function in `C source code'.

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

Read a string in the minibuffer, with completion.
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' and `all-completions' for more details
on completion, COLLECTION, and PREDICATE.

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.
- 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.

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.

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'.