Icicles - Background on Input Completion

Previous: Icicles - Inserting Text from CursorIciclesIciclesIndexNext: Icicles - Cycling Completions

Background on Vanilla Emacs Input Completion

This page reviews standard Emacs behavior regarding input completion. It does not describe any Icicles completion features, but it does define some of the vocabulary used on other Icicles pages. See also vanilla completion.

When you are prompted in the minibuffer to enter something, you are sometimes presented with a default value. This might be automatically inserted after the prompt, initially. If not, you can retrieve the default value yourself, using ‘M-n’ (Emacs 21 or later).

Often, there is more than one reasonable default value that might make sense. Depending on what you’re being asked to enter, these candidate default values might be command names, buffer names, existing file names, variable names, and so on.

For most Emacs functions that prompt you for input, the person who wrote the function decided on the reasonable set of default values, and passed these to an input-completing function such as `completing-read’ or `read-file-name’, which prompts you and reads your input. The programmer also decided whether you will be required to pick one of the default values or you will be free to enter something else. The programmer might also have told the input-completing function to require that your input pass some special test (predicate).

Be aware that standard Emacs terminology does not refer to such a set of default values as “default values”; they are called “completions”. By “default value”, standard Emacs terminology means only the values that you can access via ‘M-n’. Icicles refers to all such potential inputs indifferently as “default values”, “completions”, “completion candidates”, and “candidates”. Whenever completion is not requiring you to pick one of the available candidates, they are effectively only default choices.

So, how do you get access to the default values that the programmer has made available to you, in order to choose one? You hit certain keys to complete the current contents of the minibuffer (excluding the prompt). This current, partial input is considered as a prefix of one of the default values, and it is completed in the minibuffer to the entire default value (completion).

Keys ‘TAB’, ‘RET’ (Return), and ‘SPC’ (Space) perform different degrees of this “prefix completion” in standard Emacs. If you type a prefix of one of the available default values, you can complete the value this way in the minibuffer, and then enter (commit) it, using ‘RET’.

(Starting with Emacs 23, what Icicles calls “prefix completion” is controlled by vanilla Emacs option ‘completion-styles’, and the matching it uses is not limited to the ‘basic’ style, that is, to expanding a literal prefix of one of the completion candidates. If you prefer, you can think of “prefix completion” as ‘TAB’ completion (but you can change which key effects it).

But if your partial input matches the prefix of more than one default value, completion pops up the list of all matching completions for you to choose from (in buffer ‘*Completions*’). You choose a candidate by clicking it with ‘mouse-2’ or placing the cursor on it and hitting ‘RET’.

Because this is the way you access the default values supplied to an input-completing function, I call those values “prefix-completion candidates”. If there is no partial input yet (the minibuffer is empty), then the entire list of default values supplied to the input-completing function appears in the pop-up ‘*Completions*’ buffer. See the EmacsManual (‘C-h r’) for more on this general completion mechanism.

Calls to ‘completing-read’ and ‘read-file-name’ are not the only places where input completion is used. When you use ‘M-x’ (command ‘execute-extended-command’) completion is also available.

Previous: Icicles - Inserting Text from CursorIciclesIciclesIndexNext: Icicles - Cycling Completions