X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/a457417ee5ba797ab1c91d35ee957bb7a7f8d4b6..fd5a8ae8a3750faaae9bee1deb303d8f8d2800c4:/doc/lispref/minibuf.texi diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index f85ca96db9..9b09a304bd 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1,7 +1,8 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/minibuf @node Minibuffers, Command Loop, Read and Print, Top @@ -22,13 +23,13 @@ argument. * Intro to Minibuffers:: Basic information about minibuffers. * Text from Minibuffer:: How to read a straight text string. * Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. +* Minibuffer History:: Recording previous minibuffer inputs + so the user can reuse them. * Initial Input:: Specifying initial contents for the minibuffer. * Completion:: How to invoke and customize completion. * Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. +* Multiple Queries:: Asking a series of similar questions. +* Reading a Password:: Reading a password from the terminal. * Minibuffer Commands:: Commands used as key bindings in minibuffers. * Minibuffer Contents:: How such commands access the minibuffer text. * Minibuffer Windows:: Operating on the special minibuffer windows. @@ -56,17 +57,15 @@ read-only so you won't accidentally delete or change it. It is also marked as a field (@pxref{Fields}), so that certain motion functions, including @code{beginning-of-line}, @code{forward-word}, @code{forward-sentence}, and @code{forward-paragraph}, stop at the -boundary between the prompt and the actual text. (In older Emacs -versions, the prompt was displayed using a special mechanism and was not -part of the buffer contents.) +boundary between the prompt and the actual text. The minibuffer's window is normally a single line; it grows -automatically if necessary if the contents require more space. You can -explicitly resize it temporarily with the window sizing commands; it -reverts to its normal size when the minibuffer is exited. You can -resize it permanently by using the window sizing commands in the frame's -other window, when the minibuffer is not active. If the frame contains -just a minibuffer, you can change the minibuffer's size by changing the +automatically if the contents require more space. You can explicitly +resize it temporarily with the window sizing commands; it reverts to +its normal size when the minibuffer is exited. You can resize it +permanently by using the window sizing commands in the frame's other +window, when the minibuffer is not active. If the frame contains just +a minibuffer, you can change the minibuffer's size by changing the frame's size. Use of the minibuffer reads input events, and that alters the values @@ -74,16 +73,17 @@ of variables such as @code{this-command} and @code{last-command} (@pxref{Command Loop Info}). Your program should bind them around the code that uses the minibuffer, if you do not want that to change them. - If a command uses a minibuffer while there is an active minibuffer, -this is called a @dfn{recursive minibuffer}. The first minibuffer is -named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by -incrementing the number at the end of the name. (The names begin with a -space so that they won't show up in normal buffer lists.) Of several -recursive minibuffers, the innermost (or most recently entered) is the -active minibuffer. We usually call this ``the'' minibuffer. You can -permit or forbid recursive minibuffers by setting the variable -@code{enable-recursive-minibuffers} or by putting properties of that -name on command symbols (@pxref{Recursive Mini}). + Under some circumstances, a command can use a minibuffer even if +there is an active minibuffer; such minibuffers are called a +@dfn{recursive minibuffer}. The first minibuffer is named +@w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by +incrementing the number at the end of the name. (The names begin with +a space so that they won't show up in normal buffer lists.) Of +several recursive minibuffers, the innermost (or most recently +entered) is the active minibuffer. We usually call this ``the'' +minibuffer. You can permit or forbid recursive minibuffers by setting +the variable @code{enable-recursive-minibuffers}, or by putting +properties of that name on command symbols (@xref{Recursive Mini}.) Like other buffers, a minibuffer uses a local keymap (@pxref{Keymaps}) to specify special key bindings. The function that @@ -99,11 +99,13 @@ was supplied when Emacs was started. @node Text from Minibuffer @section Reading Text Strings with the Minibuffer - Most often, the minibuffer is used to read text as a string. It can -also be used to read a Lisp object in textual form. The most basic -primitive for minibuffer input is @code{read-from-minibuffer}; it can do -either one. There are also specialized commands for reading -commands, variables, file names, etc. (@pxref{Completion}). + The most basic primitive for minibuffer input is +@code{read-from-minibuffer}, which can be used to read either a string +or a Lisp object in textual form. The function @code{read-regexp} is +used for reading regular expressions (@pxref{Regular Expressions}), +which are a special kind of string. There are also specialized +functions for reading commands, variables, file names, etc.@: +(@pxref{Completion}). In most cases, you should not call minibuffer input functions in the middle of a Lisp function. Instead, do all minibuffer input as part of @@ -111,7 +113,7 @@ reading the arguments for a command, in the @code{interactive} specification. @xref{Defining Commands}. @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method -This function is the most general way to get input through the +This function is the most general way to get input from the minibuffer. By default, it accepts arbitrary text and returns it as a string; however, if @var{read} is non-@code{nil}, then it uses @code{read} to convert the text into a Lisp object (@pxref{Input @@ -133,14 +135,14 @@ through the history commands. It should be a string, a list of strings, or @code{nil}. The string or strings become the minibuffer's ``future history,'' available to the user with @kbd{M-n}. -If @var{read} is non-@code{nil}, then @var{default} is also used as -the input to @code{read}, if the user enters empty input. (If -@var{read} is non-@code{nil} and @var{default} is @code{nil}, empty -input results in an @code{end-of-file} error.) However, in the usual -case (where @var{read} is @code{nil}), @code{read-from-minibuffer} -ignores @var{default} when the user enters empty input and returns an -empty string, @code{""}. In this respect, it differs from all the -other minibuffer input functions in this chapter. +If @var{read} is non-@code{nil}, then @var{default} is also used +as the input to @code{read}, if the user enters empty input. +If @var{default} is a list of strings, the first string is used as the input. +If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error. +However, in the usual case (where @var{read} is @code{nil}), +@code{read-from-minibuffer} ignores @var{default} when the user enters +empty input and returns an empty string, @code{""}. In this respect, +it differs from all the other minibuffer input functions in this chapter. If @var{keymap} is non-@code{nil}, that keymap is the local keymap to use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the @@ -201,6 +203,38 @@ This function works by calling the @end smallexample @end defun +@defun read-regexp prompt &optional default-value +This function reads a regular expression as a string from the +minibuffer and returns it. The argument @var{prompt} is used as in +@code{read-from-minibuffer}. The keymap used is +@code{minibuffer-local-map}, and @code{regexp-history} is used as the +history list (@pxref{Minibuffer History, regexp-history}). + +The optional argument @var{default-value} specifies a default value to +return if the user enters null input; it should be a string, or +@code{nil} which is equivalent to an empty string. + +In addition, @code{read-regexp} collects a few useful candidates for +input and passes them to @code{read-from-minibuffer}, to make them +available to the user as the ``future minibuffer history list'' +(@pxref{Minibuffer History, future list,, emacs, The GNU Emacs +Manual}). These candidates are: + +@itemize @minus +@item +The word or symbol at point. +@item +The last regexp used in an incremental search. +@item +The last string used in an incremental search. +@item +The last string or pattern used in query-replace commands. +@end itemize + +This function works by calling the @code{read-from-minibuffer} +function, after computing the list of defaults as described above. +@end defun + @defvar minibuffer-allow-text-properties If this variable is @code{nil}, then @code{read-from-minibuffer} strips all text properties from the minibuffer input before returning it. @@ -475,19 +509,19 @@ This lets Lisp programs explicitly manage input history by using set to a non-@code{nil} value. @end defvar -@defvar history-length +@defopt history-length The value of this variable specifies the maximum length for all history lists that don't specify their own maximum lengths. If the -value is @code{t}, that means there no maximum (don't delete old +value is @code{t}, that means there is no maximum (don't delete old elements). The value of @code{history-length} property of the history list variable's symbol, if set, overrides this variable for that particular history list. -@end defvar +@end defopt -@defvar history-delete-duplicates +@defopt history-delete-duplicates If the value of this variable is @code{t}, that means when adding a new history element, all previous identical elements are deleted. -@end defvar +@end defopt Here are some of the standard minibuffer history list variables: @@ -593,51 +627,44 @@ for reading certain kinds of names with completion. @menu * Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) * Minibuffer Completion:: Invoking the minibuffer with completion. * Completion Commands:: Minibuffer commands that do completion. * High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.) -* Reading File Names:: Using completion to read file names. + (reading buffer name, file name, etc.). +* Reading File Names:: Using completion to read file names and + shell commands. +* Completion Styles:: Specifying rules for performing completion. * Programmed Completion:: Writing your own completion-function. @end menu @node Basic Completion @subsection Basic Completion Functions - The completion functions @code{try-completion}, -@code{all-completions} and @code{test-completion} have nothing in -themselves to do with minibuffers. We describe them in this chapter -so as to keep them near the higher-level completion features that do -use the minibuffer. - - If you store a completion alist in a variable, you should mark the -variable as ``risky'' with a non-@code{nil} -@code{risky-local-variable} property. + The following completion functions have nothing in themselves to do +with minibuffers. We describe them here to keep them near the +higher-level completion features that do use the minibuffer. @defun try-completion string collection &optional predicate This function returns the longest common substring of all possible completions of @var{string} in @var{collection}. The value of -@var{collection} must be a list of strings or symbols, an alist, an -obarray, a hash table, or a function that implements a virtual set of -strings (see below). +@var{collection} must be a list of strings, an alist whose keys are +strings or symbols, an obarray, a hash table, or a completion function +(@pxref{Programmed Completion}). Completion compares @var{string} against each of the permissible -completions specified by @var{collection}; if the beginning of the -permissible completion equals @var{string}, it matches. If no permissible -completions match, @code{try-completion} returns @code{nil}. If only -one permissible completion matches, and the match is exact, then -@code{try-completion} returns @code{t}. Otherwise, the value is the -longest initial sequence common to all the permissible completions that -match. +completions specified by @var{collection}. If no permissible +completions match, @code{try-completion} returns @code{nil}. If there +is just one matching completion, and the match is exact, it returns +@code{t}. Otherwise, it returns the longest initial sequence common +to all possible matching completions. If @var{collection} is an alist (@pxref{Association Lists}), the permissible completions are the elements of the alist that are either -strings, symbols, or conses whose @sc{car} is a string or symbol. +strings, or conses whose @sc{car} is a string or symbol. Symbols are converted to strings using @code{symbol-name}. Other elements of the alist are ignored. (Remember that in Emacs Lisp, the elements of alists do not @emph{have} to be conses.) In particular, a -list of strings or symbols is allowed, even though we usually do not +list of strings is allowed, even though we usually do not think of such lists as alists. @cindex obarray in completion @@ -653,13 +680,13 @@ Also, you cannot intern a given symbol in more than one obarray. If @var{collection} is a hash table, then the keys that are strings are the possible completions. Other keys are ignored. -You can also use a symbol that is a function as @var{collection}. Then -the function is solely responsible for performing completion; +You can also use a function as @var{collection}. +Then the function is solely responsible for performing completion; @code{try-completion} returns whatever this function returns. The function is called with three arguments: @var{string}, @var{predicate} -and @code{nil}. (The reason for the third argument is so that the same +and @code{nil} (the reason for the third argument is so that the same function can be used in @code{all-completions} and do the appropriate -thing in either case.) @xref{Programmed Completion}. +thing in either case). @xref{Programmed Completion}. If the argument @var{predicate} is non-@code{nil}, then it must be a function of one argument, unless @var{collection} is a hash table, in @@ -734,10 +761,11 @@ This function returns a list of all possible completions of @var{string}. The arguments to this function (aside from @var{nospace}) are the same as those of @code{try-completion}. Also, this function uses @code{completion-regexp-list} in the same way that -@code{try-completion} does. The optional argument @var{nospace} only -matters if @var{string} is the empty string. In that case, if -@var{nospace} is non-@code{nil}, completions that start with a space -are ignored. +@code{try-completion} does. + +The optional argument @var{nospace} is obsolete. If it is +non-@code{nil}, completions that start with a space are ignored unless +@var{string} starts with a space. If @var{collection} is a function, it is called with three arguments: @var{string}, @var{predicate} and @code{t}; then @code{all-completions} @@ -787,9 +815,36 @@ the values @var{string}, @var{predicate} and @code{lambda}; whatever it returns, @code{test-completion} returns in turn. @end defun +@defun completion-boundaries string collection predicate suffix +This function returns the boundaries of the field on which @var{collection} +will operate, assuming that @var{string} holds the text before point +and @var{suffix} holds the text after point. + +Normally completion operates on the whole string, so for all normal +collections, this will always return @code{(0 . (length +@var{suffix}))}. But more complex completion such as completion on +files is done one field at a time. For example, completion of +@code{"/usr/sh"} will include @code{"/usr/share/"} but not +@code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists. +Also @code{all-completions} on @code{"/usr/sh"} will not include +@code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is +@code{"/usr/sh"} and @var{suffix} is @code{"e/doc"}, +@code{completion-boundaries} will return @code{(5 . 1)} which tells us +that the @var{collection} will only return completion information that +pertains to the area after @code{"/usr/"} and before @code{"/doc"}. +@end defun + +If you store a completion alist in a variable, you should mark the +variable as ``risky'' with a non-@code{nil} +@code{risky-local-variable} property. @xref{File Local Variables}. + @defvar completion-ignore-case If the value of this variable is non-@code{nil}, Emacs does not -consider case significant in completion. +consider case significant in completion. Note, however, that this +variable is overridden by @code{read-file-name-completion-ignore-case} +within @code{read-file-name} (@pxref{Reading File Names}), and by +@code{read-buffer-completion-ignore-case} within @code{read-buffer} +(@pxref{High-Level Completion}). @end defvar @defvar completion-regexp-list @@ -815,6 +870,23 @@ Here is an example of use: @end smallexample @end defmac +The function @code{completion-in-region} provides a convenient way to +perform completion on an arbitrary stretch of text in an Emacs buffer: + +@defun completion-in-region start end collection &optional predicate +This function completes the text in the current buffer between the +positions @var{start} and @var{end}, using @var{collection}. The +argument @var{collection} has the same meaning as in +@code{try-completion} (@pxref{Basic Completion}). + +This function inserts the completion text directly into the current +buffer. Unlike @code{completing-read} (@pxref{Minibuffer +Completion}), it does not activate the minibuffer. + +For this function to work, point must be somewhere between @var{start} +and @var{end}. +@end defun + @node Minibuffer Completion @subsection Completion and the Minibuffer @cindex minibuffer completion @@ -829,19 +901,40 @@ providing completion. It activates the minibuffer with prompt @var{prompt}, which must be a string. The actual completion is done by passing @var{collection} and -@var{predicate} to the function @code{try-completion}. This happens -in certain commands bound in the local keymaps used for completion. -Some of these commands also call @code{test-completion}. Thus, if -@var{predicate} is non-@code{nil}, it should be compatible with -@var{collection} and @code{completion-ignore-case}. @xref{Definition -of test-completion}. - -If @var{require-match} is @code{nil}, the exit commands work regardless -of the input in the minibuffer. If @var{require-match} is @code{t}, the -usual minibuffer exit commands won't exit unless the input completes to -an element of @var{collection}. If @var{require-match} is neither -@code{nil} nor @code{t}, then the exit commands won't exit unless the -input already in the buffer matches an element of @var{collection}. +@var{predicate} to the function @code{try-completion} (@pxref{Basic +Completion}). This happens in certain commands bound in the local +keymaps used for completion. Some of these commands also call +@code{test-completion}. Thus, if @var{predicate} is non-@code{nil}, +it should be compatible with @var{collection} and +@code{completion-ignore-case}. @xref{Definition of test-completion}. + +The value of the optional argument @var{require-match} determines how +the user may exit the minibuffer: + +@itemize @bullet +@item +If @code{nil}, the usual minibuffer exit commands work regardless of +the input in the minibuffer. + +@item +If @code{t}, the usual minibuffer exit commands won't exit unless the +input completes to an element of @var{collection}. + +@item +If @code{confirm}, the user can exit with any input, but is asked for +confirmation if the input is not an element of @var{collection}. + +@item +If @code{confirm-after-completion}, the user can exit with any input, +but is asked for confirmation if the preceding command was a +completion command (i.e., one of the commands in +@code{minibuffer-confirm-exit-commands}) and the resulting input is +not an element of @var{collection}. @xref{Completion Commands}. + +@item +Any other value of @var{require-match} behaves like @code{t}, except +that the exit commands won't exit if it performs completion. +@end itemize However, empty input is always permitted, regardless of the value of @var{require-match}; in that case, @code{completing-read} returns the @@ -910,12 +1003,7 @@ They are described in the following section. @subsection Minibuffer Commands that Do Completion This section describes the keymaps, commands and user options used -in the minibuffer to do completion. The description refers to the -situation when Partial Completion mode is disabled (as it is by -default). When enabled, this minor mode uses its own alternatives to -some of the commands described below. @xref{Completion Options,,, -emacs, The GNU Emacs Manual}, for a short description of Partial -Completion mode. +in the minibuffer to do completion. @defvar minibuffer-completion-table The value of this variable is the collection used for completion in @@ -931,10 +1019,25 @@ minibuffer completion functions. @end defvar @defvar minibuffer-completion-confirm -When the value of this variable is non-@code{nil}, Emacs asks for -confirmation of a completion before exiting the minibuffer. -@code{completing-read} binds this variable, and the function -@code{minibuffer-complete-and-exit} checks the value before exiting. +This variable determines whether Emacs asks for confirmation before +exiting the minibuffer; @code{completing-read} binds this variable, +and the function @code{minibuffer-complete-and-exit} checks the value +before exiting. If the value is @code{nil}, confirmation is not +required. If the value is @code{confirm}, the user may exit with an +input that is not a valid completion alternative, but Emacs asks for +confirmation. If the value is @code{confirm-after-completion}, the +user may exit with an input that is not a valid completion +alternative, but Emacs asks for confirmation if the user submitted the +input right after any of the completion commands in +@code{minibuffer-confirm-exit-commands}. +@end defvar + +@defvar minibuffer-confirm-exit-commands +This variable holds a list of commands that cause Emacs to ask for +confirmation before exiting the minibuffer, if the @var{require-match} +argument to @code{completing-read} is @code{confirm-after-completion}. +The confirmation is requested if the user attempts to exit the +minibuffer immediately after calling any command in this list. @end defvar @deffn Command minibuffer-complete-word @@ -1058,14 +1161,14 @@ except that it does not bind @key{SPC}. This keymap is used by the function @code{read-file-name}. @end defvar -@defvar minibuffer-local-must-match-filename-map +@defvar minibuffer-local-filename-must-match-map This is like @code{minibuffer-local-must-match-map} except that it does not bind @key{SPC}. This keymap is used by the function @code{read-file-name}. @end defvar @node High-Level Completion -@subsection High-Level Completion Functions +@subsection High-Level Completion Functions This section describes the higher-level convenient functions for reading certain sorts of names with completion. @@ -1075,7 +1178,7 @@ Lisp function. When possible, do all minibuffer input as part of reading the arguments for a command, in the @code{interactive} specification. @xref{Defining Commands}. -@defun read-buffer prompt &optional default existing +@defun read-buffer prompt &optional default require-match This function reads the name of a buffer and returns it as a string. The argument @var{default} is the default name to use, the value to return if the user exits with an empty minibuffer. If non-@code{nil}, @@ -1089,17 +1192,12 @@ space. If @var{default} is non-@code{nil}, the function inserts it in @var{prompt} before the colon to follow the convention for reading from the minibuffer with a default value (@pxref{Programming Tips}). -If @var{existing} is non-@code{nil}, then the name specified must be -that of an existing buffer. The usual commands to exit the minibuffer -do not exit if the text is not valid, and @key{RET} does completion to -attempt to find a valid name. If @var{existing} is neither @code{nil} -nor @code{t}, confirmation is required after completion. (However, -@var{default} is not checked for validity; it is returned, whatever it -is, if the user exits with the minibuffer empty.) +The optional argument @var{require-match} has the same meaning as in +@code{completing-read}. @xref{Minibuffer Completion}. In the following example, the user enters @samp{minibuffer.t}, and -then types @key{RET}. The argument @var{existing} is @code{t}, and the -only buffer name starting with the given input is +then types @key{RET}. The argument @var{require-match} is @code{t}, +and the only buffer name starting with the given input is @samp{minibuffer.texi}, so that name is the value. @example @@ -1123,12 +1221,18 @@ Buffer name (default foo): @point{} @end example @end defun -@defvar read-buffer-function -This variable specifies how to read buffer names. For example, if you -set this variable to @code{iswitchb-read-buffer}, all Emacs commands -that call @code{read-buffer} to read a buffer name will actually use the -@code{iswitchb} package to read it. -@end defvar +@defopt read-buffer-function +This variable specifies how to read buffer names. The function is +called with the arguments passed to @code{read-buffer}. For example, +if you set this variable to @code{iswitchb-read-buffer}, all Emacs +commands that call @code{read-buffer} to read a buffer name will +actually use the @code{iswitchb} package to read it. +@end defopt + +@defopt read-buffer-completion-ignore-case +If this variable is non-@code{nil}, @code{read-buffer} ignores case +when performing completion. +@end defopt @defun read-command prompt &optional default This function reads the name of a command and returns it as a Lisp @@ -1229,6 +1333,28 @@ but uses the predicate @code{user-variable-p} instead of @end example @end defun +@deffn Command read-color &optional prompt convert allow-empty display +This function reads a string that is a color specification, either the +color's name or an RGB hex value such as @code{#RRRGGGBBB}. It +prompts with @var{prompt} (default: @code{"Color (name or #R+G+B+):"}) +and provides completion for color names, but not for hex RGB values. +In addition to names of standard colors, completion candidates include +the foreground and background colors at point. + +Valid RGB values are described in @ref{Color Names}. + +The function's return value is the color name typed by the user in the +minibuffer. However, when called interactively or if the optional +argument @var{convert} is non-@code{nil}, it converts the name into +the color's RGB value and returns that value as a string. If an +invalid color name was specified, this function signals an error, +except that empty color names are allowed when @code{allow-empty} is +non-@code{nil} and the user enters null input. + +Interactively, or when @var{display} is non-@code{nil}, the return +value is also displayed in the echo area. +@end deffn + See also the functions @code{read-coding-system} and @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}, and @code{read-input-method-name}, in @ref{Input Methods}. @@ -1238,27 +1364,35 @@ and @code{read-input-method-name}, in @ref{Input Methods}. @cindex read file names @cindex prompt for file name - Here is another high-level completion function, designed for reading a -file name. It provides special features including automatic insertion -of the default directory. - -@defun read-file-name prompt &optional directory default existing initial predicate -This function reads a file name in the minibuffer, prompting with -@var{prompt} and providing completion. - -If @var{existing} is non-@code{nil}, then the user must specify the name -of an existing file; @key{RET} performs completion to make the name -valid if possible, and then refuses to exit if it is not valid. If the -value of @var{existing} is neither @code{nil} nor @code{t}, then -@key{RET} also requires confirmation after completion. If -@var{existing} is @code{nil}, then the name of a nonexistent file is -acceptable. + The high-level completion functions @code{read-file-name}, +@code{read-directory-name}, and @code{read-shell-command} are designed +to read file names, directory names, and shell commands respectively. +They provide special features, including automatic insertion of the +default directory. + +@defun read-file-name prompt &optional directory default require-match initial predicate +This function reads a file name, prompting with @var{prompt} and +providing completion. + +As an exception, this function reads a file name using a graphical +file dialog instead of the minibuffer, if (i) it is invoked via a +mouse command, and (ii) the selected frame is on a graphical display +supporting such dialogs, and (iii) the variable @code{use-dialog-box} +is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU +Emacs Manual}), and (iv) the @var{directory} argument, described +below, does not specify a remote file (@pxref{Remote Files,, Remote +Files, emacs, The GNU Emacs Manual}). The exact behavior when using a +graphical file dialog is platform-dependent. Here, we simply document +the behavior when using the minibuffer. + +The optional argument @var{require-match} has the same meaning as in +@code{completing-read}. @xref{Minibuffer Completion}. @code{read-file-name} uses @code{minibuffer-local-filename-completion-map} as the keymap if -@var{existing} is @code{nil}, and uses -@code{minibuffer-local-must-match-filename-map} if @var{existing} is -non-@code{nil}. @xref{Completion Commands}. +@var{require-match} is @code{nil}, and uses +@code{minibuffer-local-filename-must-match-map} if @var{require-match} +is non-@code{nil}. @xref{Completion Commands}. The argument @var{directory} specifies the directory to use for completion of relative file names. It should be an absolute directory @@ -1266,7 +1400,6 @@ name. If @code{insert-default-directory} is non-@code{nil}, @var{directory} is also inserted in the minibuffer as initial input. It defaults to the current buffer's value of @code{default-directory}. -@c Emacs 19 feature If you specify @var{initial}, that is an initial file name to insert in the buffer (after @var{directory}, if that is inserted). In this case, point goes at the beginning of @var{initial}. The default for @@ -1281,7 +1414,7 @@ contents that @code{read-file-name} inserted initially. The initial minibuffer contents are always non-empty if @code{insert-default-directory} is non-@code{nil}, as it is by default. @var{default} is not checked for validity, regardless of the -value of @var{existing}. However, if @var{existing} is +value of @var{require-match}. However, if @var{require-match} is non-@code{nil}, the initial minibuffer contents should be a valid file (or directory) name. Otherwise @code{read-file-name} attempts completion if the user exits without any editing, and does not return @@ -1301,9 +1434,9 @@ types @key{RET} without any editing, @code{read-file-name} simply returns the pre-inserted contents of the minibuffer. If the user types @key{RET} in an empty minibuffer, this function -returns an empty string, regardless of the value of @var{existing}. -This is, for instance, how the user can make the current buffer visit -no file using @code{M-x set-visited-file-name}. +returns an empty string, regardless of the value of +@var{require-match}. This is, for instance, how the user can make the +current buffer visit no file using @code{M-x set-visited-file-name}. If @var{predicate} is non-@code{nil}, it specifies a function of one argument that decides which file names are acceptable completion @@ -1355,12 +1488,12 @@ called, it calls this function with the supplied arguments instead of doing its usual work. @end defvar -@defvar read-file-name-completion-ignore-case +@defopt read-file-name-completion-ignore-case If this variable is non-@code{nil}, @code{read-file-name} ignores case when performing completion. -@end defvar +@end defopt -@defun read-directory-name prompt &optional directory default existing initial +@defun read-directory-name prompt &optional directory default require-match initial This function is like @code{read-file-name} but allows only directory names as completion possibilities. @@ -1423,20 +1556,97 @@ The file is @point{} @end example @end defopt +@defun read-shell-command prompt &optional initial-contents hist &rest args +This function reads a shell command from the minibuffer, prompting +with @var{prompt} and providing intelligent completion. It completes +the first word of the command using candidates that are appropriate +for command names, and the rest of the command words as file names. + +This function uses @code{minibuffer-local-shell-command-map} as the +keymap for minibuffer input. The @var{hist} argument specifies the +history list to use; if is omitted or @code{nil}, it defaults to +@code{shell-command-history} (@pxref{Minibuffer History, +shell-command-history}). The optional argument @var{initial-contents} +specifies the initial content of the minibuffer (@pxref{Initial +Input}). The rest of @var{args}, if present, are used as the +@var{default} and @var{inherit-input-method} arguments in +@code{read-from-minibuffer} (@pxref{Text from Minibuffer}). +@end defun + +@defvar minibuffer-local-shell-command-map +This keymap is used by @code{read-shell-command} for completing +command and file names that are part of a shell command. +@end defvar + +@node Completion Styles +@subsection Completion Styles +@cindex completion styles + + A @dfn{completion style} is a set of rules for generating +completions. The user option @code{completion-styles} stores a list +of completion styles, which are represented by symbols. + +@defopt completion-styles +This is a list of completion style symbols to use for performing +completion. Each completion style in this list must be defined in +@code{completion-styles-alist}. +@end defopt + +@defvar completion-styles-alist +This variable stores a list of available completion styles. Each +element in the list must have the form @samp{(@var{name} +@var{try-completion} @var{all-completions})}. Here, @var{name} is the +name of the completion style (a symbol), which may be used in +@code{completion-styles-alist} to refer to this style. + +@var{try-completion} is the function that does the completion, and +@var{all-completions} is the function that lists the completions. +These functions should accept four arguments: @var{string}, +@var{collection}, @var{predicate}, and @var{point}. The @var{string}, +@var{collection}, and @var{predicate} arguments have the same meanings +as in @code{try-completion} (@pxref{Basic Completion}), and the +@var{point} argument is the position of point within @var{string}. +Each function should return a non-@code{nil} value if it performed its +job, and @code{nil} if it did not (e.g., if there is no way to +complete @var{string} according to the completion style). + +When the user calls a completion command, such as +@code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks +for the first style listed in @code{completion-styles} and calls its +@var{try-completion} function. If this function returns @code{nil}, +Emacs moves to the next completion style listed in +@code{completion-styles} and calls its @var{try-completion} function, +and so on until one of the @var{try-completion} functions successfully +performs completion and returns a non-@code{nil} value. A similar +procedure is used for listing completions, via the +@var{all-completions} functions. +@end defvar + + By default, @code{completion-styles-alist} contains five pre-defined +completion styles: @code{basic}, a basic completion style; +@code{partial-completion}, which does partial completion (completing +each word in the input separately); @code{emacs22}, which performs +completion according to the rules used in Emacs 22; @code{emacs21}, +which performs completion according to the rules used in Emacs 21; and +@code{initials}, which completes acronyms and initialisms. + @node Programmed Completion @subsection Programmed Completion @cindex programmed completion - Sometimes it is not possible to create an alist or an obarray -containing all the intended possible completions. In such a case, you -can supply your own function to compute the completion of a given string. -This is called @dfn{programmed completion}. + Sometimes it is not possible or convenient to create an alist or +an obarray containing all the intended possible completions ahead +of time. In such a case, you can supply your own function to compute +the completion of a given string. This is called @dfn{programmed +completion}. Emacs uses programmed completion when completing file +names (@pxref{File Name Completion}), among many other cases. - To use this feature, pass a symbol with a function definition as the -@var{collection} argument to @code{completing-read}. The function + To use this feature, pass a function as the @var{collection} +argument to @code{completing-read}. The function @code{completing-read} arranges to pass your completion function along -to @code{try-completion} and @code{all-completions}, which will then let -your function do all the work. +to @code{try-completion}, @code{all-completions}, and other basic +completion functions, which will then let your function do all +the work. The completion function should accept three arguments: @@ -1450,10 +1660,14 @@ none. Your function should call the predicate for each possible match, and ignore the possible match if the predicate returns @code{nil}. @item -A flag specifying the type of operation. +A flag specifying the type of operation. The best way to think about +it is that the function stands for an object (in the +``object-oriented'' sense of the word), and this third argument +specifies which method to run. @end itemize - There are three flag values for three operations: + There are currently four methods, i.e. four flag values, one for +each of the four different basic operations: @itemize @bullet @item @@ -1475,27 +1689,36 @@ string. @code{lambda} specifies @code{test-completion}. The completion function should return @code{t} if the specified string is an exact match for some possibility; @code{nil} otherwise. -@end itemize - - It would be consistent and clean for completion functions to allow -lambda expressions (lists that are functions) as well as function -symbols as @var{collection}, but this is impossible. Lists as -completion tables already have other meanings, and it would be -unreliable to treat one differently just because it is also a possible -function. So you must arrange for any function you wish to use for -completion to be encapsulated in a symbol. - Emacs uses programmed completion when completing file names. -@xref{File Name Completion}. +@item +@code{(boundaries . SUFFIX)} specifies @code{completion-boundaries}. +The function should return a value of the form @code{(boundaries +START . END)} where START is the position of the beginning boundary in +in the string to complete, and END is the position of the end boundary +in SUFFIX. +@end itemize -@defmac dynamic-completion-table function -This macro is a convenient way to write a function that can act as +@defun completion-table-dynamic function +This function is a convenient way to write a function that can act as programmed completion function. The argument @var{function} should be a function that takes one argument, a string, and returns an alist of possible completions of it. You can think of -@code{dynamic-completion-table} as a transducer between that interface +@code{completion-table-dynamic} as a transducer between that interface and the interface for programmed completion functions. -@end defmac +@end defun + +@defvar completion-annotate-function +The value of this variable, if non-@code{nil}, should be a function +for ``annotating'' the entries in the @samp{*Completions*} buffer. +The function should accept a single argument, the completion string +for an entry. It should return an additional string to display next +to that entry in the @samp{*Completions*} buffer, or @code{nil} if no +additional string is to be displayed. + +The function can determine the collection used for the current +completion via the variable @code{minibuffer-completion-table} +(@pxref{Completion Commands}). +@end defvar @node Yes-or-No Queries @section Yes-or-No Queries @@ -1769,7 +1992,7 @@ keys in minibuffer local keymaps. @deffn Command self-insert-and-exit This command exits the active minibuffer after inserting the last -character typed on the keyboard (found in @code{last-command-char}; +character typed on the keyboard (found in @code{last-command-event}; @pxref{Command Loop Info}). @end deffn @@ -1964,10 +2187,12 @@ windows. If a float, it specifies a fraction of the height of the frame. If an integer, it specifies a number of lines. @end defopt -@defun minibuffer-message string +@defun minibuffer-message string &rest args This function displays @var{string} temporarily at the end of the minibuffer text, for two seconds, or until the next input event -arrives, whichever comes first. +arrives, whichever comes first. If @var{args} is non-@code{nil}, the +actual message is obtained by passing @var{string} and @var{args} +through @code{format}. @xref{Formatting Strings}. @end defun @ignore