[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Changes to m4/doc/m4.texinfo,v
From: |
Eric Blake |
Subject: |
Changes to m4/doc/m4.texinfo,v |
Date: |
Thu, 21 Dec 2006 14:17:18 +0000 |
CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/12/21 14:17:17
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.82
retrieving revision 1.83
diff -u -b -r1.82 -r1.83
--- doc/m4.texinfo 9 Dec 2006 16:53:28 -0000 1.82
+++ doc/m4.texinfo 21 Dec 2006 14:17:17 -0000 1.83
@@ -4936,11 +4936,12 @@
@cindex length of strings
@cindex strings, length of
+The length of a string can be calculated by @code{len}:
+
@deffn {Builtin (m4)} len (@var{string})
-The length of a string can be calculated by @code{len},
-which expands to the length of @var{string}, as a decimal number.
+Expands to the length of @var{string}, as a decimal number.
-The builtin macro @code{len} is recognized only when given arguments.
+The macro @code{len} is recognized only with parameters.
@end deffn
@example
@@ -4953,9 +4954,10 @@
@node Index macro
@section Searching for substrings
+Searching for substrings is done with @code{index}:
+
@deffn {Builtin (m4)} index (@var{string}, @var{substring})
-Searching for substrings is done with @code{index},
-which expands to the index of the first occurrence of @var{substring} in
+Expands to the index of the first occurrence of @var{substring} in
@var{string}. The first character in @var{string} has index 0. If
@var{substring} does not occur in @var{string}, @code{index} expands to
@samp{-1}.
@@ -4970,30 +4972,49 @@
@result{}-1
@end example
+Omitting @var{substring} evokes a warning, but still produces output.
+
address@hidden
+index(`abc')
address@hidden:stdin:1: Warning: index: too few arguments: 1 < 2
address@hidden
address@hidden example
+
@node Regexp
@section Searching for regular expressions
@cindex regular expressions
address@hidden GNU extensions
address@hidden @acronym{GNU} extensions
+Searching for regular expressions is done with the builtin
address@hidden:
+
@deffn {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @var{resyntax})
@deffnx {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @
@ovar{replacement}, @ovar{resyntax})
-Searching for regular expressions is done with the builtin
address@hidden, which searches for @var{regexp} in @var{string}. The
-syntax of regular expressions is similar to that of Perl, @acronym{GNU} Awk
-and Egrep: so called ``Extended Regular Expression''.
+Searches for @var{regexp} in @var{string}.
+
+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. If exactly three arguments given, then the
+third argument is treated as @var{resyntax} only if it matches a known
+syntax name, otherwise it is treated as @var{replacement}.
If @var{replacement} is omitted, @code{regexp} expands to the index of
-the first match of @var{regexp} in @var{string}. If @var{replacement}
-is specified and matches, then it expands into @var{replacement}. If
address@hidden does not match anywhere in @var{string}, it expands to -1.
+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{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.
+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.
+The macro @code{regexp} is recognized only with parameters.
@end deffn
@example
@@ -5001,16 +5022,34 @@
@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:stdin:2: Warning: regexp: sub-expression 1 not present
address@hidden:stdin:2: Warning: regexp: trailing \ ignored in replacement
address@hidden
+regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6')
address@hidden:stdin:3: Warning: regexp: sub-expression 4 not present
address@hidden:stdin:3: Warning: regexp: sub-expression 5 not present
address@hidden:stdin:3: Warning: regexp: sub-expression 6 not present
address@hidden
address@hidden example
+
+Omitting @var{regexp} evokes a warning, but still produces output.
+
address@hidden
+regexp(`abc')
address@hidden:stdin:1: Warning: regexp: too few arguments: 1 < 2
address@hidden
@end example
If @var{resyntax} is given, @var{regexp} must be given according to
@@ -5021,16 +5060,24 @@
regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***',
`POSIX_EXTENDED')
@result{}*** Unix *** nix ***
+regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***')
address@hidden
@end example
-Occasionally, you might want to pass an @var{resyntax} argument
-without wishing to give @var{replacement}. If the @strong{last}
-argument is a valid @var{resyntax} it is used as such whether
-or not a @var{replacement} argument is also given:
+Occasionally, you might want to pass an @var{resyntax} argument without
+wishing to give @var{replacement}. If there are exactly three
+arguments, and the last argument is a valid @var{resyntax}, it is used
+as such, rather than as a replacement.
@example
regexp(`GNUs not Unix', `\w(\w+)$', `POSIX_EXTENDED')
@result{}9
+regexp(`GNUs not Unix', `\w(\w+)$', `POSIX_EXTENDED', `POSIX_EXTENDED')
address@hidden
+regexp(`GNUs not Unix', `\w(\w+)$', `POSIX_EXTENDED', `')
address@hidden
+regexp(`GNUs not Unix', `\w\(\w+\)$', `POSIX_EXTENDED', `')
address@hidden
@end example
@node Substr
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/12/04
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/12/09
- Changes to m4/doc/m4.texinfo,v,
Eric Blake <=
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/12/22
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/12/22
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/12/26
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/12/27