From 2836affa62a72a7f2d132e30f09e5dd93d022343 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sun, 16 Feb 2014 18:12:50 -0800 Subject: [PATCH] Some doc for read-regexp * doc/lispref/minibuf.texi (Text from Minibuffer): Update read-regexp details. Mention read-regexp-defaults-function. * etc/NEWS: Related markup. --- doc/lispref/ChangeLog | 5 +++ doc/lispref/minibuf.texi | 75 +++++++++++++++++++++++++++++++--------- etc/NEWS | 1 + 3 files changed, 64 insertions(+), 17 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index f10577faf77..7869bcfdc2e 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2014-02-17 Glenn Morris + + * minibuf.texi (Text from Minibuffer): Update read-regexp details. + Mention read-regexp-defaults-function. + 2014-02-13 Glenn Morris * debugging.texi (Debugger Commands): Tiny edits. diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index df510862460..63e9e2bbc23 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -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 diff --git a/etc/NEWS b/etc/NEWS index 364046c40f4..278bc7fd003 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -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. -- 2.39.2