From b8630261dda1988bd1cabe7fc1b567b6e140eabb Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Thu, 13 Feb 2014 23:36:42 -0800 Subject: [PATCH] Some read-regexp doc * lisp/replace.el (map-query-replace-regexp) (read-regexp-defaults-function, read-regexp): Doc fixes. * etc/NEWS: Related edits. --- etc/NEWS | 9 +++---- lisp/ChangeLog | 3 +++ lisp/replace.el | 64 ++++++++++++++++++++++++++++++------------------- 3 files changed, 45 insertions(+), 31 deletions(-) diff --git a/etc/NEWS b/etc/NEWS index f00ee0b4648..4e05203676f 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -251,12 +251,6 @@ and this variable has been marked obsolete. ** `emacs-bzr-version' has been renamed to `emacs-repository-version', and works for git too, if you fetch the repository notes. -** `read-regexp-defaults-function' defines a function to provide default -values for reading regexps by commands like `rgrep', `lgrep' `occur', -`highlight-regexp', etc. You can customize this to specify a function -that provides a default value from the regexp last history element, -or from the symbol found at point. - +++ ** New option `load-prefer-newer' affects how the `load' function chooses the file to load. If this is non-nil, then when both .el and .elc @@ -1090,6 +1084,9 @@ 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. + ** Completion changes *** The separator for `completing-read-multiple' can now be a regexp. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 21eeff7bffe..8c097ad87b0 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,8 @@ 2014-02-14 Glenn Morris + * replace.el (map-query-replace-regexp) + (read-regexp-defaults-function, read-regexp): Doc fixes. + * dired.el (dired-read-regexp): * faces.el (list-faces-display): * misearch.el (multi-isearch-read-matching-buffers) diff --git a/lisp/replace.el b/lisp/replace.el index cebb10d5133..fafa5ec8390 100644 --- a/lisp/replace.el +++ b/lisp/replace.el @@ -450,6 +450,7 @@ of the region. Otherwise, operate from point to the end of the buffer. Non-interactively, TO-STRINGS may be a list of replacement strings. +Interactively, reads the regexp using `read-regexp'. Use \\\\[next-history-element] \ to pull the last incremental search regexp to the minibuffer that reads REGEXP. @@ -627,17 +628,16 @@ of `history-length', which see.") "History of regexp for occur's collect operation") (defcustom read-regexp-defaults-function nil - "Function that provides default regexp(s) for regexp reading commands. -This function should take no arguments and return one of nil, a -regexp or a list of regexps. The return value of this function is used -as DEFAULTS param of `read-regexp'. This function is called only during -interactive use. + "Function that provides default regexp(s) for `read-regexp'. +This function should take no arguments and return one of: nil, a +regexp, or a list of regexps. Interactively, `read-regexp' uses +the return value of this function for its DEFAULT argument. -If you need different defaults for different commands, -use `this-command' to identify the command under execution. +As an example, set this variable to `find-tag-default-as-regexp' +to default to the symbol at point. -You can customize `read-regexp-defaults-function' to the value -`find-tag-default-as-regexp' to highlight a symbol at point." +To provide different default regexps for different commands, +the function that you set this to can check `this-command'." :type '(choice (const :tag "No default regexp reading function" nil) (const :tag "Latest regexp history" regexp-history-last) @@ -647,7 +647,7 @@ You can customize `read-regexp-defaults-function' to the value find-tag-default-as-regexp) (function-item :tag "Tag at point as symbol regexp" find-tag-default-as-symbol-regexp) - (function :tag "Function to provide default for read-regexp")) + (function :tag "Your choice of function")) :group 'matching :version "24.4") @@ -666,21 +666,35 @@ via \\\\[next-history-element]." (defun read-regexp (prompt &optional defaults history) "Read and return a regular expression as a string. -When PROMPT doesn't end with a colon and space, it adds a final \": \". -If the first element of DEFAULTS is non-nil, it's added to the prompt. - -Optional arg DEFAULTS has the form (DEFAULT . SUGGESTIONS) -or simply DEFAULT where DEFAULT, if non-nil, should be a string that -is returned as the default value when the user enters empty input. -SUGGESTIONS is a list of strings that can be inserted into -the minibuffer using \\\\[next-history-element]. \ -The values supplied in SUGGESTIONS -are prepended to the list of standard suggestions returned by -`read-regexp-suggestions'. The default values can be customized -by `read-regexp-defaults-function'. - -Optional arg HISTORY is a symbol to use for the history list. -If HISTORY is nil, `regexp-history' is used." +Prompt with the string PROMPT. If PROMPT ends in \":\" (followed by +optional whitespace), use it as-is. Otherwise, add \": \" to the end, +possible preceded by the default result (see below). + +The optional argument DEFAULTS can be either: nil, a string, a list +of strings, or a symbol. We use DEFAULTS to construct the default +return value in case of empty input. + +If DEFAULTS is a string, we use it as-is. + +If DEFAULTS is a list of strings, the first element is the +default return value, but all the elements are accessible +using the history command \\\\[next-history-element]. + +If DEFAULTS is a non-nil symbol, then if `read-regexp-defaults-function' +is non-nil, we use that in place of DEFAULTS in the following: + If DEFAULTS is the symbol `regexp-history-last', we use the first + element of HISTORY (if specified) or `regexp-history'. + If DEFAULTS is a function, we call it with no arguments and use + what it returns, which should be either nil, a string, or a list of strings. + +We append the standard values from `read-regexp-suggestions' to DEFAULTS +before using it. + +If the first element of DEFAULTS is non-nil (and if PROMPT does not end +in \":\", followed by optional whitespace), we add it to the prompt. + +The optional argument HISTORY is a symbol to use for the history list. +If nil, uses `regexp-history'." (let* ((defaults (if (and defaults (symbolp defaults)) (cond -- 2.39.2