(lemacs.info)Completion


Next: Repetition Prev: Minibuffer Edit Up: Minibuffer

Completion
==========

   When appropriate, the minibuffer provides a "completion" facility.
You type the beginning of an argument and one of the completion keys,
and Emacs visibly fills in the rest, depending on what you have already
typed.

   When completion is available, certain keys--TAB, RET, and SPC--are
redefined to complete an abbreviation present in the minibuffer into a
longer string that it stands for, by matching it against a set of
"completion alternatives" provided by the command reading the argument.
`?' is defined to display a list of possible completions of what you
have inserted.

   For example, when the minibuffer is being used by `Meta-x' to read
the name of a command, it is given a list of all available Emacs command
names to complete against.  The completion keys match the text in the
minibuffer against all the command names, find any additional
characters of the name that are implied by the ones already present in
the minibuffer, and add those characters to the ones you have given.

   Case is normally significant in completion because it is significant
in most of the names that you can complete (buffer names, file names,
and command names).  Thus, `fo' will not complete to `Foo'.  When you
are completing a name in which case does not matter, case may be ignored
for completion's sake if specified by program.

   When a completion list is displayed, the completions will highlight
as you move the mouse over them.  Clicking the middle mouse button on
any highlighted completion will "select" it just as if you had typed it
in and hit RET.

A Completion Example
--------------------

   Consider the following example.  If you type `Meta-x au TAB', TAB
looks for alternatives (in this case, command names) that start with
`au'.  There are only two commands: `auto-fill-mode' and
`auto-save-mode'.  They are the same as far as `auto-', so the `au' in
the minibuffer changes to `auto-'.

   If you type TAB again immediately, there are multiple possibilities
for the very next character--it could be `s' or `f'--so no more
characters are added; but a list of all possible completions is
displayed in another window.

   If you go on to type `f TAB', this TAB sees `auto-f'.  The only
command name starting this way is `auto-fill-mode', so completion
inserts the rest of that command.  You now have `auto-fill-mode' in the
minibuffer after typing just `au TAB f TAB'.  Note that TAB has this
effect because in the minibuffer it is bound to the function
`minibuffer-complete' when completion is supposed to be done.

Completion Commands
-------------------

   Here is a list of all the completion commands defined in the
minibuffer when completion is available.

`TAB'
     Complete the text in the minibuffer as much as possible
     (`minibuffer-complete').

`SPC'
     Complete the text in the minibuffer but don't add or fill out more
     than one word (`minibuffer-complete-word').

`RET'
     Submit the text in the minibuffer as the argument, possibly
     completing first as described below
     (`minibuffer-complete-and-exit').

`?'
     Print a list of all possible completions of the text in the
     minibuffer (`minibuffer-list-completions').

`button2'
     Select the highlighted text under the mouse as a minibuffer
     response.  When the minibuffer is being used to prompt the user
     for a completion, any valid completions which are visible on the
     screen will be highlighted when the mouse moves over them.
     Clicking button2 will select the highlighted completion and exit
     the minibuffer.  (`minibuf-select-highlighted-completion').

   SPC completes in a way that is similar to TAB, but it never goes
beyond the next hyphen or space.  If you have `auto-f' in the
minibuffer and type SPC, it finds that the completion is
`auto-fill-mode', but it stops completing after `fill-'.  The result is
`auto-fill-'. Another SPC at this point completes all the way to
`auto-fill-mode'.  SPC in the minibuffer runs the function
`minibuffer-complete-word' when completion is available.

   There are three different ways that RET can work in completing
minibuffers, depending on how the argument will be used.

   * "Strict" completion is used when it is meaningless to give any
     argument except one of the known alternatives.  For example, when
     `C-x k' reads the name of a buffer to kill, it is meaningless to
     give anything but the name of an existing buffer.  In strict
     completion, RET refuses to exit if the text in the minibuffer does
     not complete to an exact match.

   * "Cautious" completion is similar to strict completion, except that
     RET exits only if the text was an exact match already, not needing
     completion.  If the text is not an exact match, RET does not exit,
     but it does complete the text.  If it completes to an exact match,
     a second RET will exit.

     Cautious completion is used for reading file names for files that
     must already exist.

   * "Permissive" completion is used when any string is meaningful, and
     the list of completion alternatives is just a guide.  For example,
     when `C-x C-f' reads the name of a file to visit, any file name is
     allowed, in case you want to create a file.  In permissive
     completion, RET takes the text in the minibuffer exactly as given,
     without completing it.

   The completion commands display a list of all possible completions
in a window whenever there is more than one possibility for the very
next character.  Typing `?' explicitly requests such a list.  The list
of completions counts as help text, so `C-M-v' typed in the minibuffer
scrolls the list.

   When completion is done on file names, certain file names are usually
ignored.  The variable `completion-ignored-extensions' contains a list
of strings; a file whose name ends in any of those strings is ignored
as a possible completion.  The standard value of this variable has
several elements including `".o"', `".elc"', `".dvi"' and `"~"'.  The
effect is that, for example, `foo' completes to `foo.c' even though
`foo.o' exists as well.  If the only possible completions are files
that end in "ignored" strings, they are not ignored.

   If a completion command finds the next character is undetermined, it
automatically displays a list of all possible completions.  If the
variable `completion-auto-help' is set to `nil', this does not happen,
and you must type `?' to display the possible completions.

   If the variable `minibuffer-confirm-incomplete' is set to `t', then
in contexts where `completing-read' allows answers that are not valid
completions, an extra RET must be typed to confirm the response.  This
is helpful for catching typos.


automatically generated by info2www