[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: |
Wed, 03 Jan 2007 14:44:12 +0000 |
CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 07/01/03 14:44:11
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.87
retrieving revision 1.88
diff -u -b -r1.87 -r1.88
--- doc/m4.texinfo 27 Dec 2006 14:14:27 -0000 1.87
+++ doc/m4.texinfo 3 Jan 2007 14:44:11 -0000 1.88
@@ -46,7 +46,7 @@
a package containing an implementation of the m4 macro language.
Copyright @copyright{} 1989, 1990, 1991, 1992, 1993, 1994, 1998, 1999,
-2000, 2001, 2004, 2005, 2006 Free Software Foundation, Inc.
+2000, 2001, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -5619,14 +5619,16 @@
@cindex formatted output
@cindex output, formatted
address@hidden GNU extensions
address@hidden @acronym{GNU} extensions
+Formatted output can be made with @code{format}:
+
@deffn {Builtin (gnu)} format (@var{format-string}, @dots{})
-Formatted output can be made with @code{format}, which works much like
-the C function @code{printf}. The first argument is a format string,
-which can contain @samp{%} specifications, and the expansion of
address@hidden is the formatted string.
+Works much like the C function @code{printf}. The first argument
address@hidden can contain @samp{%} specifications which are
+satisfied by additional arguments, and the expansion of @code{format} is
+the formatted string.
-The builtin macros @code{format} is recognized only when given arguments.
+The macro @code{format} is recognized only with parameters.
@end deffn
Its use is best described by a few examples:
@@ -5642,12 +5644,15 @@
@result{}5000
@end example
-Using the @code{forloop} macro defined in @xref{Forloop}, this
+Using the @code{forloop} macro defined earlier (@pxref{Forloop}), this
example shows how @code{format} can be used to produce tabular output.
address@hidden ignore
address@hidden examples
@example
-forloop(`i', 1, 10, `format(`%6d squared is %10d
+$ @kbd{m4 -I examples}
+include(`forloop.m4')
address@hidden
+forloop(`i', `1', `10', `format(`%6d squared is %10d
', i, eval(i**2))')
@result{} 1 squared is 1
@result{} 2 squared is 4
@@ -5659,18 +5664,23 @@
@result{} 8 squared is 64
@result{} 9 squared is 81
@result{} 10 squared is 100
address@hidden
@end example
The builtin @code{format} is modeled after the ANSI C @samp{printf}
-function, and supports the normal @samp{%} specifiers: @samp{c},
+function, and supports these @samp{%} specifiers: @samp{c},
@samp{s}, @samp{d}, @samp{o}, @samp{x}, @samp{X}, @samp{u}, @samp{e},
address@hidden, @samp{f}, @samp{F}, @samp{g}, and @samp{G}; it supports
-field widths and precisions, and the
address@hidden, @samp{f}, @samp{F}, @samp{g}, @samp{G}, and @samp{%}; it
+supports field widths and precisions, and the
modifiers @samp{+}, @samp{-}, @address@hidden }}, @samp{0}, @samp{#}, @samp{h}
and
@samp{l}. For more details on the functioning of @code{printf}, see the
C Library Manual.
@c FIXME - format still needs some improvements.
+For now, unrecognized specifiers are silently ignored, but it is
+anticipated that a future release of @acronym{GNU} @code{m4} will support more
+specifiers, and give warnings when problems are encountered. Likewise,
+escape sequences are not yet recognized.
@node Arithmetic
@chapter Macros for doing arithmetic
@@ -5692,22 +5702,34 @@
@cindex decrement operator
@cindex increment operator
+Increment and decrement of integers are supported using the builtins
address@hidden and @code{decr}:
+
@deffn {Builtin (m4)} incr (@var{number})
@deffnx {Builtin (m4)} decr (@var{number})
-Increment and decrement of integers are supported using the builtins
address@hidden and @code{decr}, which expand to the numerical value of
address@hidden, incremented, or decremented, respectively, by one.
+Expand to the numerical value of @var{number}, incremented
+or decremented, respectively, by one. Except for the empty string, the
+expansion is empty if @var{number} could not be parsed.
+
+The macros @code{incr} and @code{decr} are recognized only with
+parameters.
address@hidden deffn
@example
-incr(4)
+incr(`4')
@result{}5
-decr(7)
+decr(`7')
@result{}6
+incr()
address@hidden:stdin:3: Warning: incr: empty string treated as 0
address@hidden
+decr()
address@hidden:stdin:4: Warning: decr: empty string treated as 0
address@hidden
@end example
The builtin macros @code{incr} and @code{decr} are recognized only when
given arguments.
address@hidden deffn
@node Eval
@section Evaluating integer expressions
@@ -5715,30 +5737,37 @@
@cindex integer expression evaluation
@cindex evaluation, of integer expressions
@cindex expressions, evaluation of integer
address@hidden {Builtin (m4)} eval (@var{expression}, @ovar{radix},
@ovar{width})
-Integer expressions are evaluated with @code{eval}, which expands to the
-value of @var{expression}.
+Integer expressions are evaluated with @code{eval}:
+
address@hidden {Builtin (m4)} eval (@var{expression}, @dvar{radix, 10},
@ovar{width})
+Expands to the value of @var{expression}. The expansion is empty
+if an error is encountered while parsing the arguments. If specified,
address@hidden and @var{width} control the format of the output. An error
+is issued if division by zero is attempted.
+
+The macro @code{eval} is recognized only with parameters.
address@hidden deffn
Expressions can contain the following operators, listed in order of
decreasing precedence.
@table @code
address@hidden -
-Unary minus
address@hidden ()
+Parenthesis
address@hidden + - ~ !
+Unary plus and minus, and bitwise and logical negation
@item **
Exponentiation
address@hidden * / % :
-Multiplication, division, modulo and ratio
address@hidden * / %
+Multiplication, division, and modulo
@item + -
Addition and subtraction
@item << >>
Shift left or right
address@hidden == != > >= < <=
address@hidden > >= < <=
Relational operators
address@hidden !
-Logical negation
address@hidden ~
-Bitwise negation
address@hidden == !=
+Equality operators
@item &
Bitwise and
@item ^
@@ -5751,12 +5780,67 @@
Logical or
@end table
-All operators, except exponentiation, are left associative.
+All operators, except exponentiation, are left associative. C
+operators that perform variable assignment, such as @samp{=} or
address@hidden, are forbidden, since @code{eval} only operates on constants,
+not variables.
+
+Note that some older @code{m4} implementations use @samp{^} as an
+alternate operator for the exponentiation, although @acronym{POSIX}
+requires the C behavior of bitwise exclusive-or. The precedence of the
+negation operators, @samp{~} and @samp{!}, was traditionally lower than
+equality. The unary operators @samp{-} and @samp{+} could not be used
+more than once on the same term. The traditional precedence of the
+equality operators @samp{==} and @samp{!=} was identical instead of
+lower than the relational operators such as @samp{<}, even in
address@hidden M4 1.4.x. Starting with version 2.0, @acronym{GNU} M4
+correctly follows @acronym{POSIX} precedence rules. M4 scripts designed
+to be portable between releases must be aware that parentheses may be
+required to enforce C precedence rules. Likewise, division by zero,
+even in the unused branch of a short-circuiting operator, is not always
+well-defined in other implementations.
+
+Following are some examples where the current version of M4 follows C
+precedence rules, but where older versions and some other
+implementations of @code{m4} require explicit parenthesis to get the
+correct result:
-Note that many @code{m4} implementations use @samp{^} as an alternate
-operator for the exponentiation, while many others use @samp{^} for the
-bitwise exclusive-or. GNU @code{m4} changed its behavior: it used to
-exponentiate for @samp{^}, it now computes the bitwise exclusive-or.
address@hidden status: 1
address@hidden
+eval(`1 == 2 > 0')
address@hidden
+eval(`(1 == 2) > 0')
address@hidden
+eval(`! 0 * 2')
address@hidden
+eval(`! (0 * 2)')
address@hidden
+eval(`1 | 1 ^ 1')
address@hidden
+eval(`(1 | 1) ^ 1')
address@hidden
+eval(`+ + - ~ ! ~ 0')
address@hidden
+eval(`++0')
address@hidden:stdin:8: eval: invalid operator: ++0
address@hidden
+eval(`1 = 1')
address@hidden:stdin:9: eval: invalid operator: 1 = 1
address@hidden
+eval(`0 |= 1')
address@hidden:stdin:10: eval: invalid operator: 0 |= 1
address@hidden
+eval(`2 || 1 / 0')
address@hidden
+eval(`0 || 1 / 0')
address@hidden:stdin:12: eval: divide by zero: 0 || 1 / 0
address@hidden
+eval(`0 && 1 % 0')
address@hidden
+eval(`2 && 1 % 0')
address@hidden:stdin:14: eval: modulo by zero: 2 && 1 % 0
address@hidden
address@hidden example
Numbers without special prefix are given decimal. A simple @samp{0}
prefix introduces an octal number. @samp{0x} introduces a hexadecimal
@@ -5776,7 +5860,6 @@
relation return @code{0}.
The builtin macro @code{eval} is recognized only when given arguments.
address@hidden deffn
Here are a few examples of use of @code{eval}.
@@ -5786,18 +5869,18 @@
@result{}-15
eval(index(`Hello world', `llo') >= 0)
@result{}1
-define(`square', `eval(`($1)**2')')
+define(`square', `eval(`($1) ** 2')')
@result{}
square(`9')
@result{}81
-square(square(5)+1)
+square(square(`5')` + 1')
@result{}676
define(`foo', `666')
@result{}
eval(`foo / 6')
@error{}m4:stdin:7: eval: bad expression: foo / 6
@result{}
-eval(foo/6)
+eval(foo / 6)
@result{}111
@end example
@@ -5837,7 +5920,9 @@
It is almost identical to @code{eval}, except the calculations are done
with infinite precision. Numbers may be of any length.
-The @code{:} operator rationally divides two numbers and canonicalizes
address@hidden `:' as ratio conflicts with `?:' - is it worth using `\' instead?
+A new operator, @code{:}, is provided with the same precedence as
+division, and rationally divides two numbers and canonicalizes
the result. The @code{/} operator always returns the quotient of the
division. To convert a rational value to integral, divide (@code{/}) by
1. Some operators such as @code{%}, @code{<<}, @code{>>}, @code{~},
- Changes to m4/doc/m4.texinfo,v,
Eric Blake <=
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/06
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/09
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/12
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/13
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/15
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/23