@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, 2008 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
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}).
+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}).
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
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
@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.
* 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 File Names:: Using completion to read file names and
+ shell commands.
* Programmed Completion:: Writing your own completion-function.
@end menu
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}.
+an element of @var{collection}. If @var{require-match} is
+@code{confirm-only}, the user can exit with any input, but she will
+be asked for a confirmation if the input is not an element of
+@var{collection}. Any other value of @var{require-match} behaves like
+@code{t}, except that the exit commands won't exit if it does non-null
+completion.
However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns 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.
@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{nill}, 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}.
@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.
+ Here is a couple of other high-level completion functions, designed
+for reading file names and shell commands. They provide 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
@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
+@code{minibuffer-local-filename-must-match-map} if @var{existing} is
non-@code{nil}. @xref{Completion Commands}.
The argument @var{directory} specifies the directory to use for
@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 Programmed Completion
@subsection Programmed Completion
@cindex programmed completion
Emacs uses programmed completion when completing file names.
@xref{File Name Completion}.
-@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
@node Yes-or-No Queries
@section Yes-or-No Queries
@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