X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/bdb3097a23f057be4a747831cf69aa957f4f67e1..43e124e6826ab3d1e92921638577696d13d36646:/lispref/minibuf.texi diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi index 7b762a654e..a6153fdaca 100644 --- a/lispref/minibuf.texi +++ b/lispref/minibuf.texi @@ -111,14 +111,15 @@ was supplied when Emacs was started. 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. +either one. There are also specialized commands 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 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 +@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method keep-all This function is the most general way to get input through 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 @@ -170,6 +171,9 @@ the setting of @code{enable-multibyte-characters} (@pxref{Text Representations}) from whichever buffer was current before entering the minibuffer. +If @var{keep-all} is non-@code{nil}, even empty and duplicate inputs +are added to the history list. + Use of @var{initial-contents} is mostly deprecated; we recommend using a non-@code{nil} value only in conjunction with specifying a cons cell for @var{hist}. @xref{Initial Input}. @@ -231,9 +235,11 @@ default, it makes the following bindings: @code{abort-recursive-edit} @item @kbd{M-n} +@itemx @key{DOWN} @code{next-history-element} @item @kbd{M-p} +@itemx @key{UP} @code{previous-history-element} @item @kbd{M-s} @@ -408,10 +414,9 @@ symbol, not a list; it is a variable whose value is a list of strings inputs. It's the Lisp programmer's job to specify the right history list for each use of the minibuffer. - The basic minibuffer input functions @code{read-from-minibuffer} and -@code{completing-read} both accept an optional argument named @var{hist} -which is how you specify the history list. Here are the possible -values: + You specify the history list with the optional @var{hist} argument +to either @code{read-from-minibuffer} or @code{completing-read}. Here +are the possible values for it: @table @asis @item @var{variable} @@ -450,13 +455,19 @@ delete old elements if the list gets too long. The variable @code{history-length} specifies the maximum length for most history lists. To specify a different maximum length for a particular history list, put the length in the @code{history-length} property of the -history list symbol. +history list symbol. The variable @code{history-delete-duplicates} +specifies whether to delete duplicates in history. @defvar 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 elements). +@end defvar + +@defvar 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 Here are some of the standard minibuffer history list variables: @@ -575,17 +586,18 @@ for reading certain kinds of names with completion. @node Basic Completion @subsection Basic Completion Functions - The 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. + 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. @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, 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 or symbols, an alist, an +obarray, a hash table, or a function that implements a virtual set of +strings (see below). Completion compares @var{string} against each of the permissible completions specified by @var{collection}; if the beginning of the @@ -598,11 +610,13 @@ match. If @var{collection} is an alist (@pxref{Association Lists}), the permissible completions are the elements of the alist that are either -strings or conses whose @sc{car} is a string. Other elements of the -alist are ignored. (Remember that in Emacs Lisp, the elements of -alists do not @emph{have} to be conses.) As all elements of the alist -can be strings, this case actually includes lists of strings, even -though we usually do not think of such lists as alists. +strings, symbols, 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.) As all +elements of the alist can be strings, this case actually includes +lists of strings or symbols, even though we usually do not think of +such lists as alists. @cindex obarray in completion If @var{collection} is an obarray (@pxref{Creating Symbols}), the names @@ -774,12 +788,12 @@ value @var{fun} returns becomes the permanent value of @var{var}. Here are two examples of use: -@example +@smallexample (defvar foo (lazy-completion-table foo make-my-alist 'global)) (make-local-variable 'bar) (setq bar (lazy-completion-table foo make-my-alist 'local) -@end example +@end smallexample @end defmac @node Minibuffer Completion @@ -835,9 +849,11 @@ Methods}) and the setting of @code{enable-multibyte-characters} (@pxref{Text Representations}) from whichever buffer was current before entering the minibuffer. -Completion ignores case when comparing the input against the possible -matches, if the built-in variable @code{completion-ignore-case} is -non-@code{nil}. @xref{Basic Completion}. +If the built-in variable @code{completion-ignore-case} is +non-@code{nil}, completion ignores case when comparing the input +against the possible matches. @xref{Basic Completion}. In this mode +of operation, @var{predicate} must also ignore case, or you will get +surprising results. Here's an example of using @code{completing-read}: @@ -863,12 +879,9 @@ Complete a foo: fo@point{} If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, @code{completing-read} returns @code{barfoo}. -The @code{completing-read} function binds three variables to pass -information to the commands that actually do completion. These -variables are @code{minibuffer-completion-table}, -@code{minibuffer-completion-predicate} and -@code{minibuffer-completion-confirm}. For more information about them, -see @ref{Completion Commands}. +The @code{completing-read} function binds variables to pass +information to the commands that actually do completion. +They are described in the following section. @end defun @node Completion Commands @@ -882,55 +895,6 @@ some of the commands described below. @xref{Completion Options,,, emacs, The GNU Emacs Manual}, for a short description of Partial Completion mode. -@defvar minibuffer-local-completion-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is not required. By default, this -keymap makes the following bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} -@end table - -@noindent -with other characters bound as in @code{minibuffer-local-map} -(@pxref{Definition of minibuffer-local-map}). -@end defvar - -@defvar minibuffer-local-must-match-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is required. Therefore, no keys -are bound to @code{exit-minibuffer}, the command that exits the -minibuffer unconditionally. By default, this keymap makes the following -bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} - -@item @kbd{C-j} -@code{minibuffer-complete-and-exit} - -@item @key{RET} -@code{minibuffer-complete-and-exit} -@end table - -@noindent -with other characters bound as in @code{minibuffer-local-map}. -@end defvar - @defvar minibuffer-completion-table The value of this variable is the collection used for completion in the minibuffer. This is the global variable that contains what @@ -944,6 +908,13 @@ passes to @code{try-completion}. The variable is also used by the other 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. +@end defvar + @deffn Command minibuffer-complete-word This function completes the minibuffer contents by at most a single word. Even if the minibuffer contents have only one completion, @@ -964,13 +935,6 @@ immediately---the command is programmed to work without confirmation when run twice in succession. @end deffn -@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. The -function @code{minibuffer-complete-and-exit} checks the value of this -variable before it exits. -@end defvar - @deffn Command minibuffer-completion-help This function creates a list of the possible completions of the current minibuffer contents. It works by calling @code{all-completions} @@ -1009,6 +973,55 @@ automatically display a list of possible completions whenever nothing can be completed because the next character is not uniquely determined. @end defopt +@defvar minibuffer-local-completion-map +@code{completing-read} uses this value as the local keymap when an +exact match of one of the completions is not required. By default, this +keymap makes the following bindings: + +@table @asis +@item @kbd{?} +@code{minibuffer-completion-help} + +@item @key{SPC} +@code{minibuffer-complete-word} + +@item @key{TAB} +@code{minibuffer-complete} +@end table + +@noindent +with other characters bound as in @code{minibuffer-local-map} +(@pxref{Definition of minibuffer-local-map}). +@end defvar + +@defvar minibuffer-local-must-match-map +@code{completing-read} uses this value as the local keymap when an +exact match of one of the completions is required. Therefore, no keys +are bound to @code{exit-minibuffer}, the command that exits the +minibuffer unconditionally. By default, this keymap makes the following +bindings: + +@table @asis +@item @kbd{?} +@code{minibuffer-completion-help} + +@item @key{SPC} +@code{minibuffer-complete-word} + +@item @key{TAB} +@code{minibuffer-complete} + +@item @kbd{C-j} +@code{minibuffer-complete-and-exit} + +@item @key{RET} +@code{minibuffer-complete-and-exit} +@end table + +@noindent +with other characters bound as in @code{minibuffer-local-map}. +@end defvar + @node High-Level Completion @subsection High-Level Completion Functions @@ -1273,6 +1286,18 @@ If the user types @key{RET}, @code{read-file-name} returns the file name as the string @code{"/gp/gnu/elisp/manual.texi"}. @end defun +@defvar read-file-name-function +If non-@code{nil}, this should be a function that accepts the same +arguments as @code{read-file-name}. When @code{read-file-name} is +called, it calls this function with the supplied arguments instead of +doing its usual work. +@end defvar + +@defvar read-file-name-completion-ignore-case +If this variable is non-@code{nil}, @code{read-file-name} ignores case +when performing completion. +@end defvar + @defun read-directory-name prompt &optional directory default existing initial This function is like @code{read-file-name} but allows only directory names as completion possibilities. @@ -1281,9 +1306,9 @@ If @var{default} is @code{nil} and @var{initial} is non-@code{nil}, @code{read-directory-name} constructs a substitute default by combining @var{directory} (or the current buffer's default directory if @var{directory} is @code{nil}) and @var{initial}. If both -@var{default} and @var{initial} are @code{nil}, this function uses the -current buffer's default directory as substitute default, ignoring -@var{directory}. +@var{default} and @var{initial} are @code{nil}, this function uses +@var{directory} as substitute default, or the current buffer's default +directory if @var{directory} is @code{nil}. @end defun @defopt insert-default-directory @@ -1715,14 +1740,14 @@ minibuffer. If no minibuffer is active, it returns @code{nil}. @defun minibuffer-prompt-end @tindex minibuffer-prompt-end -This function, available starting in Emacs 21, returns the current +This function returns the current position of the end of the minibuffer prompt, if a minibuffer is current. Otherwise, it returns the minimum valid buffer position. @end defun @defun minibuffer-contents @tindex minibuffer-contents -This function, available starting in Emacs 21, returns the editable +This function returns the editable contents of the minibuffer (that is, everything except the prompt) as a string, if a minibuffer is current. Otherwise, it returns the entire contents of the current buffer. @@ -1736,7 +1761,7 @@ properties, just the characters themselves. @xref{Text Properties}. @defun delete-minibuffer-contents @tindex delete-minibuffer-contents -This function, available starting in Emacs 21, erases the editable +This function erases the editable contents of the minibuffer (that is, everything except the prompt), if a minibuffer is current. Otherwise, it erases the entire buffer. @end defun