Function: regexp-opt

regexp-opt is an autoloaded and byte-compiled function defined in regexp-opt.el.gz.

Signature

(regexp-opt STRINGS &optional PAREN)

Documentation

Return a regexp to match a string in the list STRINGS.

Each member of STRINGS is treated as a fixed string, not as a regexp. Optional PAREN specifies how the returned regexp is surrounded by grouping constructs.

If STRINGS is the empty list, the return value is a regexp that never matches anything.

The optional argument PAREN can be any of the following:

a string
    the resulting regexp is preceded by PAREN and followed by
    \), e.g. use "\\\\(?1:" to produce an explicitly numbered
    group.

words
    the resulting regexp is surrounded by \<\( and \)\>.

symbols
    the resulting regexp is surrounded by \_<\( and \)\_>.

non-nil
    the resulting regexp is surrounded by \( and \).

nil
    the resulting regexp is surrounded by \(?: and \), if it is
    necessary to ensure that a postfix operator appended to it will
    apply to the whole expression.

The returned regexp is ordered in such a way that it will always match the longest string possible.

Up to reordering, the resulting regexp is equivalent to but usually more efficient than that of a simplified version:

 (defun simplified-regexp-opt (strings &optional paren)
   (let ((parens
          (cond ((stringp paren) (cons paren "\\\\)"))
                ((eq paren 'words) '("\\\\\\=<\\\\(" . "\\\\)\\\\>"))
                ((eq paren 'symbols) '("\\\\_<\\\\(" . "\\\\)\\\\_>"))
                ((null paren) '("\\\\(?:" . "\\\\)"))
                (t '("\\\\(" . "\\\\)")))))
     (concat (car parens)
             (mapconcat 'regexp-quote strings "\\\\|")
             (cdr parens))))

Other relevant functions are documented in the regexp group.

View in manual

Probably introduced at or before Emacs version 20.1.

Shortdoc

;; regexp
(regexp-opt '("foo" "bar"))
    => "\\(?:bar\\|foo\\)"

Aliases

c-regexp-opt (obsolete since 29.1) verilog-regexp-opt

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/regexp-opt.el.gz
;;; Code:

;;;###autoload
(defun regexp-opt (strings &optional paren)
  "Return a regexp to match a string in the list STRINGS.
Each member of STRINGS is treated as a fixed string, not as a regexp.
Optional PAREN specifies how the returned regexp is surrounded by
grouping constructs.

If STRINGS is the empty list, the return value is a regexp that
never matches anything.

The optional argument PAREN can be any of the following:

a string
    the resulting regexp is preceded by PAREN and followed by
    \\), e.g.  use \"\\\\(?1:\" to produce an explicitly numbered
    group.

`words'
    the resulting regexp is surrounded by \\=\\<\\( and \\)\\>.

`symbols'
    the resulting regexp is surrounded by \\_<\\( and \\)\\_>.

non-nil
    the resulting regexp is surrounded by \\( and \\).

nil
    the resulting regexp is surrounded by \\(?: and \\), if it is
    necessary to ensure that a postfix operator appended to it will
    apply to the whole expression.

The returned regexp is ordered in such a way that it will always
match the longest string possible.

Up to reordering, the resulting regexp is equivalent to but
usually more efficient than that of a simplified version:

 (defun simplified-regexp-opt (strings &optional paren)
   (let ((parens
          (cond ((stringp paren)       (cons paren \"\\\\)\"))
                ((eq paren \\='words)    \\='(\"\\\\\\=<\\\\(\" . \"\\\\)\\\\>\"))
                ((eq paren \\='symbols) \\='(\"\\\\_<\\\\(\" . \"\\\\)\\\\_>\"))
                ((null paren)          \\='(\"\\\\(?:\" . \"\\\\)\"))
                (t                       \\='(\"\\\\(\" . \"\\\\)\")))))
     (concat (car parens)
             (mapconcat \\='regexp-quote strings \"\\\\|\")
             (cdr parens))))"
  (declare (ftype (function (list &optional t) string))
           (pure t) (side-effect-free t))
  (save-match-data
    ;; Recurse on the sorted list.
    (let* ((max-lisp-eval-depth 10000)
	   (completion-ignore-case nil)
	   (completion-regexp-list nil)
	   (open (cond ((stringp paren) paren) (paren "\\(")))
	   (re (if strings
                   (regexp-opt-group
                    (delete-dups (sort strings))
                    (or open t) (not open))
                 ;; No strings: return an unmatchable regexp.
                 (concat (or open "\\(?:") regexp-unmatchable "\\)"))))
      (cond ((eq paren 'words)
	     (concat "\\<" re "\\>"))
	    ((eq paren 'symbols)
	     (concat "\\_<" re "\\_>"))
	    (t re)))))