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