### 11.3 Searching for regular expressions ¶

Searching for regular expressions is done with the builtin `regexp`:

Builtin: regexp (string, regexp, [replacement]) ¶

  Searches for regexp in string. The syntax for regular expressions is the same as in GNU Emacs, which is similar to BRE, Basic Regular Expressions in POSIX. See Syntax of Regular Expressions in the GNU Emacs Manual. Support for ERE, Extended Regular Expressions is not available, but will be added in GNU M4 2.0.

  If replacement is omitted, `regexp` expands to the index of the first match of regexp in string. If regexp does not match anywhere in string, it expands to -1.

  If replacement is supplied, and there was a match, `regexp` changes the expansion to this argument, with ‘`\n`’ substituted by the text matched by the nth parenthesized sub-expression of regexp, up to nine sub-expressions. The escape ‘`\&`’ is replaced by the text of the entire regular expression matched. For all other characters, ‘`\`’ treats the next character literally. A warning is issued if there were fewer sub-expressions than the ‘`\n`’ requested, or if there is a trailing ‘`\`’. If there was no match, `regexp` expands to the empty string.

  The macro `regexp` is recognized only with parameters.

    regexp(`GNUs not Unix', `\<[a-z]\w+')
    ⇒5
    regexp(`GNUs not Unix', `\<Q\w*')
    ⇒-1
    regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
    ⇒*** Unix *** nix ***
    regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
    ⇒

Here are some more examples on the handling of backslash:

    regexp(`abc', `\(b\)', `\\\10\a')
    ⇒\b0a
    regexp(`abc', `b', `\1\')
    error→m4:stdin:2: Warning: sub-expression 1 not present
    error→m4:stdin:2: Warning: trailing \ ignored in replacement
    ⇒
    regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6')
    error→m4:stdin:3: Warning: sub-expression 4 not present
    error→m4:stdin:3: Warning: sub-expression 5 not present
    error→m4:stdin:3: Warning: sub-expression 6 not present
    ⇒c

Omitting regexp evokes a warning, but still produces output; contrast this with an empty regexp argument.

    regexp(`abc')
    error→m4:stdin:1: Warning: too few arguments to builtin `regexp'
    ⇒0
    regexp(`abc', `')
    ⇒0
    regexp(`abc', `', `\\def')
    ⇒\def