m4: Regexp
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. ⇒Syntax of Regular Expressions
(emacs)Regexps. 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