Function: read-regexp

read-regexp is a byte-compiled function defined in replace.el.gz.

Signature

(read-regexp PROMPT &optional DEFAULTS HISTORY)

Documentation

Read and return a regular expression as a string.

Prompt with the string PROMPT. If PROMPT ends in ":" (followed by optional whitespace), use it as-is. Otherwise, add ": " to the end, possibly preceded by the default result (see below).

The optional argument DEFAULTS is used to construct the default return value in case of empty input. DEFAULTS can be nil, a string, a list of strings, or a symbol.

If DEFAULTS is a string, the function uses 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 M-n (next-history-element).

If DEFAULTS is the symbol regexp-history-last, the default return value will be the first element of HISTORY. If HISTORY is omitted or nil, regexp-history is used instead. If DEFAULTS is a symbol with a function definition, it is called with no arguments and should return either nil, a string, or a list of strings, which will be used as above. Other symbol values for DEFAULTS are ignored.

If read-regexp-defaults-function is non-nil, its value is used instead of DEFAULTS in the two cases described in the last paragraph.

Before using whatever value DEFAULTS yields, the function appends the standard values from read-regexp-suggestions to that value.

If the first element of DEFAULTS is non-nil (and if PROMPT does not end in ":", followed by optional whitespace), DEFAULT is added to the prompt.

The optional argument HISTORY is a symbol to use for the history list. If nil, use regexp-history.

If the user has used the M-s c (read-regexp-toggle-case-fold) command to specify case sensitivity, the returned string will have a text property named case-fold that has a value of either fold or inhibit-fold. (It's up to the caller of read-regexp to respect this or not; see read-regexp-case-fold-search.)

This command uses the read-regexp-map keymap while reading the regexp from the user.

View in manual

Probably introduced at or before Emacs version 23.1.

Source Code

;; Defined in /usr/src/emacs/lisp/replace.el.gz
(defun read-regexp (prompt &optional defaults history)
  "Read and return a regular expression as a string.
Prompt with the string PROMPT.  If PROMPT ends in \":\" (followed by
optional whitespace), use it as-is.  Otherwise, add \": \" to the end,
possibly preceded by the default result (see below).

The optional argument DEFAULTS is used to construct the default
return value in case of empty input.  DEFAULTS can be nil, a string,
a list of strings, or a symbol.

If DEFAULTS is a string, the function uses 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 \\<minibuffer-local-map>\\[next-history-element].

If DEFAULTS is the symbol `regexp-history-last', the default return
value will be the first element of HISTORY.  If HISTORY is omitted or
nil, `regexp-history' is used instead.
If DEFAULTS is a symbol with a function definition, it is called with
no arguments and should return either nil, a string, or a list of
strings, which will be used as above.
Other symbol values for DEFAULTS are ignored.

If `read-regexp-defaults-function' is non-nil, its value is used
instead of DEFAULTS in the two cases described in the last paragraph.

Before using whatever value DEFAULTS yields, the function appends the
standard values from `read-regexp-suggestions' to that value.

If the first element of DEFAULTS is non-nil (and if PROMPT does not end
in \":\", followed by optional whitespace), DEFAULT is added to the prompt.

The optional argument HISTORY is a symbol to use for the history list.
If nil, use `regexp-history'.

If the user has used the \\<read-regexp-map>\\[read-regexp-toggle-case-fold] command to specify case
sensitivity, the returned string will have a text property named
`case-fold' that has a value of either `fold' or
`inhibit-fold'.  (It's up to the caller of `read-regexp' to
respect this or not; see `read-regexp-case-fold-search'.)

This command uses the `read-regexp-map' keymap while reading the
regexp from the user."
  (let* ((defaults
	   (if (and defaults (symbolp defaults))
	       (cond
		((eq (or read-regexp-defaults-function defaults)
		     'regexp-history-last)
		 (car (symbol-value (or history 'regexp-history))))
		((functionp (or read-regexp-defaults-function defaults))
		 (funcall (or read-regexp-defaults-function defaults))))
	     defaults))
	 (default     (if (consp defaults) (car defaults) defaults))
	 (suggestions (if (listp defaults) defaults (list defaults)))
	 (suggestions (append suggestions (read-regexp-suggestions)))
	 (suggestions (delete-dups (delq nil (delete "" suggestions))))
	 ;; Do not automatically add default to the history for empty input.
	 (history-add-new-input nil)
         ;; `read-regexp--case-fold' dynamically bound and may be
         ;; altered by `M-c'.
         (read-regexp--case-fold case-fold-search)
	 (input (read-from-minibuffer
                 (if (string-match-p ":[ \t]*\\'" prompt)
                     prompt
                   (format-prompt prompt (and (length> default 0)
                                              (query-replace-descr default))))
		 nil read-regexp-map
                 nil (or history 'regexp-history) suggestions t))
         (result (if (equal input "")
                     ;; Return the default value when the user enters
                     ;; empty input.
                     default
                   input)))
    (when result
      (add-to-history (or history 'regexp-history) result))
    (if (and result
             (or (eq read-regexp--case-fold 'fold)
                 (eq read-regexp--case-fold 'inhibit-fold)))
        (propertize result 'case-fold read-regexp--case-fold)
      (or result input))))