procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Some doc for read-regexp

Browse source 
* doc/lispref/minibuf.texi (Text from Minibuffer):
Update read-regexp details.
Mention read-regexp-defaults-function.

* etc/NEWS: Related markup.
This commit is contained in:
Glenn Morris 2014-02-16 18:12:50 -08:00
parent dd7691b7f3
commit 2836affa62
3 changed files with 64 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
doc/lispref/ChangeLog
View file

@ -1,3 +1,8 @@
2014-02-17 Glenn Morris <rgm@gnu.org>
* minibuf.texi (Text from Minibuffer): Update read-regexp details.
Mention read-regexp-defaults-function.
2014-02-13 Glenn Morris <rgm@gnu.org>
* debugging.texi (Debugger Commands): Tiny edits.

75
doc/lispref/minibuf.texi
View file

@ -211,25 +211,39 @@ This function works by calling the
@end smallexample
@end defun
@defun read-regexp prompt &optional default history
@defun read-regexp prompt &optional defaults history
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}.
minibuffer and returns it. If the minibuffer prompt string
@var{prompt} does not end in @samp{:} (followed by optional
whitespace), the function adds @samp{: } to the end, preceded by the
default return value (see below), if that is non-empty.
The optional argument @var{default} 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.
The optional argument @var{defaults} controls the default value to
return if the user enters null input, and should be one of: a string;
@code{nil}, which is equivalent to an empty string; a list of strings;
or a symbol.
The optional argument @var{history}, if non-@code{nil}, is a symbol
specifying a minibuffer history list to use (@pxref{Minibuffer
History}). If it is omitted or @code{nil}, the history list defaults
to @code{regexp-history}.
If @var{defaults} is a symbol, @code{read-regexp} consults the value
of the variable @code{read-regexp-defaults-function} (see below), and
if that is non-@code{nil} uses it in preference to @var{defaults}.
The value in this case should be either:
@code{read-regexp} also 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
@code{regexp-history-last}, which means to use the first element of
the appropriate minibuffer history list (see below).
@item
A function of no arguments, whose return value (which should be
@code{nil}, a string, or a list of strings) becomes the value of
@var{defaults}.
@end itemize
@code{read-regexp} now ensures that the result of processing
@var{defaults} is a list (i.e., if the value is @code{nil} or a
string, it converts it to a list of one element). To this list,
@code{read-regexp} then appends a few potentially useful candidates for
input. These are:
@itemize @minus
@item
@ -242,10 +256,37 @@ The last string used in an incremental search.
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.
The function now has a list of regular expressions that it passes to
@code{read-from-minibuffer} to obtain the user's input. The first
element of the list is the default result in case of empty input. All
elements of the list are available to the user as the ``future
minibuffer history list'' (@pxref{Minibuffer History, future list,,
emacs, The GNU Emacs Manual}).
The optional argument @var{history}, if non-@code{nil}, is a symbol
specifying a minibuffer history list to use (@pxref{Minibuffer
History}). If it is omitted or @code{nil}, the history list defaults
to @code{regexp-history}.
@end defun
@defvar read-regexp-defaults-function
The function @code{read-regexp} may use the value of this variable to
determine its list of default regular expressions. If non-@code{nil},
the value of this variable should be either:
@itemize @minus
@item
The symbol @code{regexp-history-last}.
@item
A function of no arguments that returns either @code{nil}, a string,
or a list of strings.
@end itemize
@noindent
See @code{read-regexp} above for details of how these values are used.
@end defvar
@defvar minibuffer-allow-text-properties
If this variable is @code{nil}, then @code{read-from-minibuffer}
and @code{read-string} strip all text properties from the minibuffer

1
etc/NEWS
View file

@ -1097,6 +1097,7 @@ respecting file-local variables.
+++
** New function `get-pos-property'.
+++
** `read-regexp' now uses the new variable `read-regexp-defaults-function'
as a function to call to provide default values.