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
(@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
@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. Regular expressions (@pxref{Regular Expressions}) are
-a special kind of strings; use @code{read-regexp} for their minibuffer
-input. 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
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
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
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:
(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
@end example
@end defun
-@defvar read-buffer-function
+@defopt 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
+@end defopt
-@defvar read-buffer-completion-ignore-case
+@defopt read-buffer-completion-ignore-case
If this variable is non-@code{nil}, @code{read-buffer} ignores case
when performing completion.
-@end defvar
+@end defopt
@defun read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp
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 require-match initial
This function is like @code{read-file-name} but allows only directory
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 four 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; and
+@code{emacs21}, which performs completion according to the rules used
+in Emacs 21.
+
@node Programmed Completion
@subsection Programmed Completion
@cindex programmed completion
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
HCoop / bpt / emacs.git / blobdiff