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.

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'."
  (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)
	 (input (read-from-minibuffer
                 (if (string-match-p ":[ \t]*\\'" prompt)
                     prompt
                   (format-prompt prompt (and (length> default 0)
                                              (query-replace-descr default))))
		 nil nil nil (or history 'regexp-history) suggestions t)))
    (if (equal input "")
	;; Return the default value when the user enters empty input.
	(prog1 (or default input)
	  (when default
	    (add-to-history (or history 'regexp-history) default)))
      ;; Otherwise, add non-empty input to the history and return input.
      (prog1 input
	(add-to-history (or history 'regexp-history) input)))))