Re: another doc update

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Eric Blake on 12/21/2006 7:15 AM:
> 
> Still more progress.  The regexp tests are beefed up to catch more
> regression scenarios.

Also substr and patsubst.

2006-12-27  Eric Blake  <address@hidden>

        * doc/m4.texinfo (Substr, Patsubst): Merge more sections from the
        branch.
        * modules/m4.c (substr): Merge from branch.

- --
Life is short - so eat dessert first!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFkn+084KuGfSFAYARAlswAJ9W1s27wAFWYTyEnUqhyvS/MowfDwCgxPM8
iem1XY7cS07ThD1Rb8KIahc=
=IZfp
-----END PGP SIGNATURE-----

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.86
diff -u -p -r1.86 m4.texinfo
--- doc/m4.texinfo      26 Dec 2006 21:05:53 -0000      1.86
+++ doc/m4.texinfo      27 Dec 2006 14:12:17 -0000
@@ -5269,7 +5269,7 @@ Expands to the index of the first occurr
 @var{substring} does not occur in @var{string}, @code{index} expands to
 @samp{-1}.
 
-The builtin macro @code{index} is recognized only when given arguments.
+The macro @code{index} is recognized only with parameters.
 @end deffn
 
 @example
@@ -5392,21 +5392,36 @@ regexp(`GNUs not Unix', `\w\(\w+\)$', `P
 
 @cindex extracting substrings
 @cindex substrings, extracting
+Substrings are extracted with @code{substr}:
+
 @deffn {Builtin (m4)} substr (@var{string}, @var{from}, @ovar{length})
-Substrings are extracted with @code{substr}, which expands to the
-substring of @var{string}, which starts at index @var{from}, and extends
-for @var{length} characters, or to the end of @var{string}, if
address@hidden is omitted.  The starting index of a string is always 0.
+Expands to the substring of @var{string}, which starts at index
address@hidden, and extends for @var{length} characters, or to the end of
address@hidden, if @var{length} is omitted.  The starting index of a
+is always 0.  The expansion is empty if there is an error parsing
address@hidden or @var{length}, if @var{from} is beyond the end of
address@hidden, or if @var{length} is negative.
+
+The macro @code{substr} is recognized only with parameters.
address@hidden deffn
 
 @example
-substr(`gnus, gnats, and armadillos', 6)
+substr(`gnus, gnats, and armadillos', `6')
 @result{}gnats, and armadillos
-substr(`gnus, gnats, and armadillos', 6, 5)
+substr(`gnus, gnats, and armadillos', `6', `5')
 @result{}gnats
 @end example
 
-The builtin macro @code{substr} is recognized only when given arguments.
address@hidden deffn
+Omitting @var{from} evokes a warning, but still produces output.
+
address@hidden
+substr(`abc')
address@hidden:stdin:1: Warning: substr: too few arguments: 1 < 2
address@hidden
+substr(`abc',)
address@hidden:stdin:2: Warning: substr: empty string treated as 0
address@hidden
address@hidden example
 
 @node Translit
 @section Translating characters
@@ -5415,7 +5430,7 @@ The builtin macro @code{substr} is recog
 @cindex characters, translating
 Character translation is done with @code{translit}:
 
address@hidden {Builtin (m4)} translit (@var{string}, @var{chars}, 
@var{replacement})
address@hidden {Builtin (m4)} translit (@var{string}, @var{chars}, 
@ovar{replacement})
 Expands to @var{string}, with each character that occurs in
 @var{chars} translated into the character from @var{replacement} with
 the same index.
@@ -5481,17 +5496,20 @@ translit(`abc')
 @cindex regular expressions
 @cindex pattern substitution
 @cindex substitution by regular expression
address@hidden GNU extensions
address@hidden @acronym{GNU} extensions
+Global substitution in a string is done by @code{patsubst}:
+
 @deffn {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @
   @ovar{replacement}, @ovar{resyntax})
-Global substitution in a string is done by @code{patsubst}, which
-searches @var{string} for matches of @var{regexp}, and substitutes
+Searches @var{string} for matches of @var{regexp}, and substitutes
 @var{replacement} for each match.
 
-If @var{resyntax} is given, the particular flavor of regular
-expression understood with respect to @var{regexp} can be changed from
-the current default.  @xref{Changeresyntax}, for details of the values
-that can be given for this parameter.
+If @var{resyntax} is given, the particular flavor of regular expression
+understood with respect to @var{regexp} can be changed from the current
+default.  @xref{Changeresyntax}, for details of the values that can be
+given for this argument.  Unlike @var{regexp}, if exactly three
+arguments given, the third argument is always treated as
address@hidden, even if it matches a known syntax name.
 
 The parts of @var{string} that are not covered by any match of
 @var{regexp} are copied to the expansion.  Whenever a match is found, the
@@ -5502,18 +5520,21 @@ to avoid infinite loops.
 
 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.
+The macro @code{patsubst} is recognized only with parameters.
 @end deffn
 
-When used with two arguments, while @code{regexp} returns the position
-of the match, @code{patsubst} deletes it:
+When used with two arguments, @code{regexp} returns the position of the
+match, but @code{patsubst} deletes the match:
 
 @example
 patsubst(`GNUs not Unix', `^', `OBS: ')
@@ -5526,14 +5547,26 @@ patsubst(`GNUs not Unix', `\w+', `(\&)')
 @result{}(GNUs) (not) (Unix)
 patsubst(`GNUs not Unix', `[A-Z][a-z]+')
 @result{}GN address@hidden }
+patsubst(`GNUs not Unix', `not', `NOT\')
address@hidden:stdin:6: Warning: patsubst: trailing \ ignored in replacement
address@hidden NOT Unix
 @end example
 
 Here is a slightly more realistic example, which capitalizes individual
 words or whole sentences, by substituting calls of the macros
 @code{upcase} and @code{downcase} into the strings.
 
address@hidden Composite upcase (@var{text})
address@hidden Composite downcase (@var{text})
address@hidden Composite capitalize (@var{text})
+Expand to @var{text}, but with capitalization changed: @code{upcase}
+changes all letters to upper case, @code{downcase} changes all letters
+to lower case, and @code{capitalize} changes the first character of each
+word to upper case and the remaining characters to lower case.
address@hidden deffn
+
 @example
-define(`upcase',   `translit(`$*', `a-z', `A-Z')')dnl
+define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl
 define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
 define(`capitalize1',
        `regexp(`$1', `^\(\w\)\(\w*\)',
@@ -5559,7 +5592,7 @@ patsubst(`bar foo baz Foo', `\(\w*\) \(f
 
 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 of a match and preserves non-matching pieces:
 
 @example
 define(`patreg',
@@ -5573,6 +5606,14 @@ patreg(`aba abb 121', `\(.\)\(.\)\1', `\
 @result{}bab
 @end example
 
+Omitting @var{regexp} evokes a warning, but still produces output.
+
address@hidden
+patsubst(`abc')
address@hidden:stdin:1: Warning: patsubst: too few arguments: 1 < 2
address@hidden
address@hidden example
+
 @node Format
 @section Formatting strings (printf-like)
 
Index: modules/m4.c
===================================================================
RCS file: /sources/m4/m4/modules/m4.c,v
retrieving revision 1.97
diff -u -p -r1.97 m4.c
--- modules/m4.c        23 Dec 2006 00:02:20 -0000      1.97
+++ modules/m4.c        27 Dec 2006 14:12:17 -0000
@@ -938,7 +938,15 @@ M4BUILTIN_HANDLER (index)
    substring extends to the end of the first argument.  */
 M4BUILTIN_HANDLER (substr)
 {
-  int start, length, avail;
+  int start = 0;
+  int length;
+  int avail;
+
+  if (argc <= 2)
+    {
+      obstack_grow (obs, M4ARG (1), strlen (M4ARG (1)));
+      return;
+    }
 
   length = avail = strlen (M4ARG (1));
   if (!m4_numeric_arg (context, argc, argv, 2, &start))