CVSROOT: /sources/m4
Module name: m4
Branch: branch-1_4
Changes by: Eric Blake <ericb> 06/07/14 20:43:23
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.42
retrieving revision 1.1.1.1.2.43
diff -u -b -r1.1.1.1.2.42 -r1.1.1.1.2.43
--- doc/m4.texinfo 14 Jul 2006 15:15:58 -0000 1.1.1.1.2.42
+++ doc/m4.texinfo 14 Jul 2006 20:43:23 -0000 1.1.1.1.2.43
@@ -3115,25 +3115,40 @@
the first match of @var{regexp} in @var{string}. If @var{regexp} does
not match anywhere in @var{string}, it expands to -1.
+If @var{replacement} is supplied, and there was a match, @code{regexp}
+changes the expansion to this argument, with @[EMAIL PROTECTED] substituted
+by the text matched by the @var{n}th parenthesized sub-expression of
[EMAIL PROTECTED], up to nine sub-expressions. The escape @samp{\&} is
+replaced by the text of the entire regular expression matched. For
+all other characters, @samp{\} treats the next character literally. A
+warning is issued if there were fewer sub-expressions than the
[EMAIL PROTECTED]@var{n}} requested, or if there is a trailing @samp{\}. If
there
+was no match, @code{regexp} expands to the empty string.
+
+The builtin macro @code{regexp} is recognized only when given arguments.
+
@example
regexp(`GNUs not Unix', `\<[a-z]\w+')
@result{}5
regexp(`GNUs not Unix', `\<Q\w*')
@result{}-1
+regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
[EMAIL PROTECTED] Unix *** nix ***
+regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
[EMAIL PROTECTED]
@end example
-If @var{replacement} is supplied, @code{regexp} changes the expansion
-to this argument, with @[EMAIL PROTECTED] substituted by the text
-matched by the @var{n}th parenthesized sub-expression of @var{regexp},
[EMAIL PROTECTED]&} being the text the entire regular expression matched.
+Here are some more examples on the handling of backslash:
@example
-regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
[EMAIL PROTECTED] Unix *** nix ***
+regexp(`abc', `\(b\)', `\\\10\a')
[EMAIL PROTECTED]
+regexp(`abc', `b', `\1\')
[EMAIL PROTECTED]:2: m4: Warning: sub-expression 1 not present
[EMAIL PROTECTED]:2: m4: Warning: trailing \ ignored in replacement
[EMAIL PROTECTED]
@end example
-The builtin macro @code{regexp} is recognized only when given arguments.
-
@node Substr
@section Extracting substrings
@@ -3241,12 +3256,19 @@
When a replacement is to be made, @var{replacement} is inserted into
the expansion, with @[EMAIL PROTECTED] substituted by the text matched by
-the @var{n}th parenthesized sub-expression of @var{regexp}, @samp{\&}
-being the text the entire regular expression matched.
+the @var{n}th parenthesized sub-expression of @var{patsubst}, for up to
+nine sub-expressions. The escape @samp{\&} is replaced by the text of
+the entire regular expression matched. For all other characters,
[EMAIL PROTECTED] treats the next character literally. A warning is issued if
+there were fewer sub-expressions than the @[EMAIL PROTECTED] requested, or
+if there is a trailing @samp{\}.
The @var{replacement} argument can be omitted, in which case the text
matched by @var{regexp} is deleted.
+The builtin macro @code{patsubst} is recognized only when given
+arguments.
+
@example
patsubst(`GNUs not Unix', `^', `OBS: ')
@result{}OBS: GNUs not Unix
@@ -3258,6 +3280,9 @@
@result{}(GNUs) (not) (Unix)
patsubst(`GNUs not Unix', `[A-Z][a-z]+')
@result{}GN not @comment
+patsubst(`GNUs not Unix', `not', `NOT\')
[EMAIL PROTECTED]:6: m4: Warning: trailing \ ignored in replacement
[EMAIL PROTECTED] NOT Unix
@end example
Here is a slightly more realistic example, which capitalizes individual
@@ -3276,8 +3301,21 @@
@result{}Gnus Not Unix
@end example
-The builtin macro @code{patsubst} is recognized only when given
-arguments.
+While @code{regexp} replaces the whole input with the replacement as
+soon as there is a match, @code{patsubst} replaces each
[EMAIL PROTECTED] of a match and preserves non matching pieces:
+
[EMAIL PROTECTED]
+define(`patreg',
+`patsubst($@@)
+regexp($@@)')dnl
+patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
[EMAIL PROTECTED] FOO baz FOO
[EMAIL PROTECTED]
+patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
[EMAIL PROTECTED] abb 212
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
@node Format
@section Formatted output
