### 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 closest to older GNU Emacs (grouping via ‘`\(`’ and ‘`\)`’, alternation via ‘`\|`’, one-or-more matching via ‘`+`’, zero-or-one matching via ‘`?`’), although for backwards compatibility reasons, M4 1.4.x does not enable intervals (that is, both ‘`{`’ and ‘`\{`’ match a literal ‘`{`’), nor character classes (that is, ‘`[[:alpha:]]`’ matches a sequence of one of six bytes followed by a literal close bracket, rather than all letters, the same as ‘`[[ahlp:]`’ followed by ‘`]`’). See Syntax of Regular Expressions in the GNU Emacs Manual. Support for intervals, character classes, non-greedy matches, or even alternative regular expression syntax (such as POSIX Basic or Extended Regular Expressions) are likely to be added in a future version of GNU M4.

  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