m4-commit
[Top][All Lists]
Advanced

[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{~},




reply via email to

[Prev in Thread] Current Thread [Next in Thread]