[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Changes to m4/doc/m4.texinfo,v [branch-1_4]
From: |
Eric Blake |
Subject: |
Changes to m4/doc/m4.texinfo,v [branch-1_4] |
Date: |
Thu, 13 Jul 2006 13:38:22 +0000 |
CVSROOT: /sources/m4
Module name: m4
Branch: branch-1_4
Changes by: Eric Blake <ericb> 06/07/13 13:38:20
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.38
retrieving revision 1.1.1.1.2.39
diff -u -b -r1.1.1.1.2.38 -r1.1.1.1.2.39
--- doc/m4.texinfo 12 Jul 2006 13:27:26 -0000 1.1.1.1.2.38
+++ doc/m4.texinfo 13 Jul 2006 13:38:20 -0000 1.1.1.1.2.39
@@ -418,7 +418,8 @@
@item -Q
@itemx --quiet
@itemx --silent
-Suppress warnings about missing or superfluous arguments in macro calls.
+Suppress warnings, such as missing or superfluous arguments in macro
+calls, or treating the empty string as zero.
@item -W @var{REGEXP}
@itemx address@hidden
@@ -553,7 +554,7 @@
scripts.
@table @code
address@hidden address@hidden
address@hidden address@hidden
@itemx address@hidden
Set the debug-level according to the flags @var{FLAGS}. The debug-level
controls the format and amount of information presented by the debugging
@@ -644,6 +645,7 @@
@error{}and an error message
@end example
+The sequence @samp{^D} in an example indicates the end of the input file.
The majority of these examples are self-contained, and you can run them
with similar results by invoking @kbd{m4 -d}. In fact, the testsuite
that is bundled in the GNU M4 package consists of the examples in this
@@ -658,8 +660,15 @@
regexp(@var{string}, @var{regexp}, opt @var{replacement})
@end example
-All macro arguments in @code{m4} are strings, but some are given special
-interpretation, e.g., as numbers, file names, regular expressions, etc.
+All macro arguments in @code{m4} are strings, but some are given
+special interpretation, e.g., as numbers, file names, regular
+expressions, etc. The documentation for each macro will state how the
+parameters are interpreted, and what happens if the argument cannot be
+parsed according to the desired interpretation. Unless specified
+otherwise, a parameter specified to be a number is parsed as a decimal,
+even if the argument has leading zeros; and parsing the empty string as
+a number results in 0 rather than an error, although a warning will be
+issued.
The @samp{opt} before the third argument shows that this argument is
optional---if it is left out, it is taken to be the empty string. An
@@ -1638,6 +1647,9 @@
@result{}
ifdef(`foo', ``foo' is defined', ``foo' is not defined')
@result{}foo is defined
+ifdef(`no_such_macro', `yes', `no', `extra argument')
address@hidden:4: m4: Warning: excess arguments to builtin `ifdef' ignored
address@hidden
@end example
The macro @code{ifdef} is recognized only with parameters.
@@ -2649,7 +2661,8 @@
@noindent
where @var{number} is the diversion to be used. If @var{number} is left
-out, it is assumed to be zero.
+out or empty, it is assumed to be zero. If @var{number} cannot be
+parsed, the diversion is unchanged.
The expansion of @code{divert} is void.
@@ -3007,7 +3020,8 @@
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 @var{length} is omitted. The starting index of a string
-is always 0.
+is always 0. The expansion is empty if there is an error parsing
address@hidden or @var{length}.
@example
substr(`gnus, gnats, and armadillos', `6')
@@ -3233,13 +3247,20 @@
@noindent
which expand to the numerical value of @var{number}, incremented,
-or decremented, respectively, by one.
+or decremented, respectively, by one. Except for the empty string, the
+expansion is empty if @var{number} could not be parsed.
@example
incr(`4')
@result{}5
decr(`7')
@result{}6
+incr()
address@hidden:3: m4: empty string treated as 0 in builtin `incr'
address@hidden
+decr()
address@hidden:4: m4: empty string treated as 0 in builtin `decr'
address@hidden
@end example
The builtin macros @code{incr} and @code{decr} are recognized only when
@@ -3260,7 +3281,8 @@
@end example
@noindent
-which expands to the value of @var{expression}.
+which expands to the value of @var{expression}. The expansion is empty
+if an error is encountered while parsing the arguments.
Expressions can contain the following operators, listed in order of
decreasing precedence.
@@ -3305,12 +3327,15 @@
version to match @acronym{POSIX}, so use parentheses to force the
desired precedence.
-Numbers without special prefix are given decimal. A simple @samp{0}
+Within @var{expression}, (but not @var{radix} or @var{width}),
+numbers without a special prefix are decimal. A simple @samp{0}
prefix introduces an octal number. @samp{0x} introduces a hexadecimal
number. @samp{0b} introduces a binary number. @samp{0r} introduces a
number expressed in any radix between 1 and 36: the prefix should be
immediately followed by the decimal expression of the radix, a colon,
-then the digits making the number. For any radix, the digits are
+then the digits making the number. For radix 1, leading zeros are
+ignored and all remaining digits must be @samp{1}; for all other
+radices, the digits are
@samp{0}, @samp{1}, @samp{2}, @dots{}. Beyond @samp{9}, the digits are
@samp{a}, @samp{b} @dots{} up to @samp{z}. Lower and upper case letters
can be used interchangeably in numbers prefixes and as number digits.
@@ -3326,6 +3351,8 @@
@result{}-15
eval(index(`Hello world', `llo') >= 0)
@result{}1
+eval(`0r1:0111 + 0b100 + 0r3:12')
address@hidden
define(`square', `eval(`('$1`)**2')')
@result{}
square(`9')
@@ -3335,7 +3362,7 @@
define(`foo', `666')
@result{}
eval(`foo/6')
address@hidden:7: m4: bad expression in eval: foo/6
address@hidden:8: m4: bad expression in eval: foo/6
@result{}
eval(foo/6)
@result{}111
@@ -3365,10 +3392,15 @@
@end example
If @var{radix} is specified, it specifies the radix to be used in the
-expansion. The default radix is 10. The result of @code{eval} is
-always taken to be signed. The @var{width} argument specifies a minimum
-output width. The result is zero-padded to extend the expansion to the
-requested width.
+expansion. The default radix is 10; this is also the case if
address@hidden is the empty string. It is an error if the radix is outside
+the range of 1 through 36, inclusive. The result of @code{eval} is
+always taken to be signed. No radix prefix is output, and for radices
+greater than 10, the digits are lower case. The @var{width} argument
+specifies the minimum output width, excluding any negative sign. The
+result is zero-padded to extend the expansion to the requested width.
+It is an error if the width is negative. On error, the expansion of
address@hidden is empty.
@example
eval(`666', `10')
@@ -3380,11 +3412,15 @@
eval(`666', `6', `10')
@result{}0000003030
eval(`-666', `6', `10')
address@hidden
address@hidden
+eval(`10', `', `0')
address@hidden
+`0r1:'eval(`10', `1', `11')
address@hidden:01111111111
+eval(`10', `16')
address@hidden
@end example
-Take note that @var{radix} cannot be larger than 36.
-
The builtin macro @code{eval} is recognized only when given arguments.
@node Shell commands
@@ -4209,6 +4245,11 @@
@code{m4} treats the shift operators @samp{<<} and @samp{>>} as
well-defined on signed integers (even though they are not in C), and
adds the exponentiation operator @samp{**}.
+
address@hidden
address@hidden requires @code{translit} (@pxref{Translit}) to treat
+each character of the second and third arguments literally, but GNU
address@hidden treats @samp{-} as a range operator.
@end itemize
@node Other Incompatibilities
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/03
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/03
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/07
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/08
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/09
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/11
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/11
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/12
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/12
- Changes to m4/doc/m4.texinfo,v [branch-1_4],
Eric Blake <=
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/13
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/13
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/14
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/14
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/14
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/14
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/15
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/17
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/17
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/07/19