Changes to m4/doc/m4.texinfo,v [branch-1_4]

[Eric Blake]

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 @address@hidden substituted
+by the text matched by the @var{n}th parenthesized sub-expression of
address@hidden, 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
address@hidden@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 ***')
address@hidden Unix *** nix ***
+regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
address@hidden
 @end example
 
-If @var{replacement} is supplied, @code{regexp} changes the expansion
-to this argument, with @address@hidden substituted by the text
-matched by the @var{n}th parenthesized sub-expression of @var{regexp},
address@hidden&} 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 ***')
address@hidden Unix *** nix ***
+regexp(`abc', `\(b\)', `\\\10\a')
address@hidden
+regexp(`abc', `b', `\1\')
address@hidden:2: m4: Warning: sub-expression 1 not present
address@hidden:2: m4: Warning: trailing \ ignored in replacement
address@hidden
 @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 @address@hidden 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,
address@hidden treats the next character literally.  A warning is issued if
+there were fewer sub-expressions than the @address@hidden 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\')
address@hidden:6: m4: Warning: trailing \ ignored in replacement
address@hidden 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
address@hidden of a match and preserves non matching pieces:
+
address@hidden
+define(`patreg',
+`patsubst($@@)
+regexp($@@)')dnl
+patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
address@hidden FOO baz FOO
address@hidden
+patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
address@hidden abb 212
address@hidden
address@hidden example
 
 @node Format
 @section Formatted output