[SCM] GNU M4 source repository branch, branch-1_4, updated. branch-cvs-readonly-56-g345b7b6

[Eric Blake]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU M4 source repository".

http://git.sv.gnu.org/gitweb/?p=m4.git;a=commitdiff;h=345b7b6429d6b042b39fefd500c06e83d301d4ff

The branch, branch-1_4 has been updated
       via  345b7b6429d6b042b39fefd500c06e83d301d4ff (commit)
      from  6e45bac29917da4289b841d1f339851e1def72d9 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 345b7b6429d6b042b39fefd500c06e83d301d4ff
Author: Eric Blake <address@hidden>
Date:   Tue Feb 19 13:36:53 2008 -0700

    Clean up foreach example.
    
    * doc/m4.texinfo (Foreach, Improved foreach): Document another
    shortcoming in foreach.m4.
    
    Signed-off-by: Eric Blake <address@hidden>

-----------------------------------------------------------------------

Summary of changes:
 ChangeLog      |    6 +++++
 doc/m4.texinfo |   57 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 57 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 86f8cb8..62b78a9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2008-02-19  Eric Blake  <address@hidden>
+
+       Clean up foreach example.
+       * doc/m4.texinfo (Foreach, Improved foreach): Document another
+       shortcoming in foreach.m4.
+
 2008-02-18  Eric Blake  <address@hidden>
 
        Avoid some magic numbers.
diff --git a/doc/m4.texinfo b/doc/m4.texinfo
index 6172277..56445c0 100644
--- a/doc/m4.texinfo
+++ b/doc/m4.texinfo
@@ -2919,6 +2919,7 @@ An actual implementation of these three macros is 
distributed as
 @address@hidden/@/examples/@/quote.m4} in this package.  First,
 let's examine their usage:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`quote.m4')
@@ -2951,6 +2952,7 @@ other hand, results in a string no matter what, since it 
is still
 possible to tell whether it was invoked without arguments based on the
 resulting string.
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 undivert(`quote.m4')dnl
@@ -3012,6 +3014,7 @@ invocation is restored.
 
 It can, for example, be used for simple counting:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`forloop.m4')
@@ -3022,6 +3025,7 @@ forloop(`i', `1', `8', `i ')
 
 For-loops can be nested, like:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`forloop.m4')
@@ -3049,6 +3053,7 @@ not finished, it increments the iterator (using the 
predefined macro
 Here is an actual implementation of @code{forloop}, distributed as
 @address@hidden/@/examples/@/forloop.m4} in this package:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 undivert(`forloop.m4')dnl
@@ -3095,6 +3100,7 @@ using an implementation of @code{foreach} distributed as
 @address@hidden/@/examples/@/foreach.m4}, and @code{foreachq}
 in @address@hidden/@/examples/@/foreachq.m4}.
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`foreach.m4')
@@ -3117,6 +3123,7 @@ It is possible to be more complex; each element of the 
@var{paren-list}
 or @var{quote-list} can itself be a list, to pass as further arguments
 to a helper macro.  This example generates a shell case statement:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`foreach.m4')
@@ -3146,6 +3153,7 @@ needed to grab the first element of a list.  Second,
 through the original list.  Here is a simple implementation of
 @code{foreach}:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 undivert(`foreach.m4')dnl
@@ -3172,6 +3180,7 @@ expecting the macro name on output after one layer of 
quotes is removed
 during list iteration and the final layer removed during the final
 rescan:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 define(`a', `1')define(`b', `2')define(`c', `3')
@@ -3196,6 +3205,7 @@ foreachq(`x', ```a'', ``(b'', ``c)''', `x
 
 Obviously, @code{foreachq} did a better job; here is its implementation:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 undivert(`foreachq.m4')dnl
@@ -3218,10 +3228,25 @@ has its own severe flaw.  Whereas the @code{foreach} 
implementation was
 linear, this macro is quadratic in the number of list elements, and is
 much more likely to trip up the limit set by the command line option
 @option{--nesting-limit} (or @option{-L}, @pxref{Limits control, ,
-Invoking m4}).  (It is possible to have robust iteration with linear
-behavior for either list style.  See if you can learn from the best
-elements of both of these implementations to create robust macros; or
address@hidden foreach, , Answers}).
+Invoking m4}).  Additionally, this implementation does not expand
address@hidden(address@hidden')} very well, when compared with
address@hidden
+
address@hidden examples
address@hidden
+$ @kbd{m4 -I examples}
+include(`foreach.m4')include(`foreachq.m4')
address@hidden
+foreach(`name', `(`a', `b')', ` defn(`name')')
address@hidden a b
+foreachq(`name', ``a', `b'', ` defn(`name')')
address@hidden _arg1(`a', `b') _arg1(shift(`a', `b'))
address@hidden example
+
+It is possible to have robust iteration with linear behavior and sane
address@hidden contents for either list style.  See if you can learn
+from the best elements of both of these implementations to create robust
+macros (or @pxref{Improved foreach, , Answers}).
 
 @node Debugging
 @chapter How to debug macros and input
@@ -4436,6 +4461,7 @@ Normally file inclusion is used to insert the contents of 
a file
 into the input stream.  The contents of the file will be read by
 @code{m4} and macro calls in the file will be expanded:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 define(`foo', `FOO')
@@ -4452,6 +4478,7 @@ of the file can be used to define macros that operate on 
entire files.
 Here is an example, which defines @samp{bar} to expand to the contents
 of @file{incl.m4}:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 define(`bar', include(`incl.m4'))
@@ -5236,6 +5263,7 @@ word to upper case and the remaining characters to lower 
case.
 First, an example of their usage, using implementations distributed in
 @address@hidden/@/examples/@/capitalize.m4}.
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`capitalize.m4')
@@ -5255,6 +5283,7 @@ merely parses out the words, and replaces them with an 
invocation of
 some subtle flaws.  You should try to see if you can find and correct
 them; or @pxref{Improved capitalize, , Answers}).
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 undivert(`capitalize.m4')dnl
@@ -5346,6 +5375,7 @@ ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success',
 Using the @code{forloop} macro defined earlier (@pxref{Forloop}), this
 example shows how @code{format} can be used to produce tabular output.
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`forloop.m4')
@@ -6220,6 +6250,7 @@ message output.
 This example reuses the file @file{incl.m4} mentioned earlier
 (@pxref{Include}):
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 define(`foo', ``$0' called at __file__:__line__')
@@ -6978,6 +7009,7 @@ shipped as @address@hidden/@/examples/@/forloop2.m4}; this
 version also optimizes based on the fact that the starting bound does
 not need to be passed to the helper @address@hidden
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 undivert(`forloop2.m4')dnl
@@ -7060,6 +7092,7 @@ The @code{foreach} and @code{foreachq} macros 
(@pxref{Foreach}) as
 presented earlier each have flaws.  First, we will examine and fix the
 quadratic behavior of @code{foreachq}:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`foreachq.m4')
@@ -7101,6 +7134,7 @@ fewer macros, is less likely to run into machine limits, 
and most
 importantly, performs faster.  The fixed version of @code{foreachq} can
 be found in @address@hidden/@/examples/@/foreachq2.m4}:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`foreachq2.m4')
@@ -7134,7 +7168,9 @@ Note that the fixed version calls unquoted helper macros 
in
 in turn must re-supply the layer of quotes lost in the macro invocation.
 Contrast the use of @address@hidden, which quotes the first list
 element, with @address@hidden of the earlier implementation that
-returned the first list element directly.
+returned the first list element directly.  Additionally, by calling the
+helper method immediately, the @samp{defn(address@hidden')} no longer
+contains unexpanded macros.
 
 The astute m4 programmer might notice that the solution above still uses
 more memory, and thus more time, than strictly necessary.  Note that
@@ -7149,6 +7185,7 @@ instead of an arbitrary length list as the key to end 
recursion.  This
 alternative approach is available as
 @address@hidden/@/examples/@/foreach3.m4}:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`foreachq3.m4')
@@ -7196,6 +7233,7 @@ overquotes the arguments to @address@hidden to begin 
with, using
 @address@hidden to remove the extra layer of quoting that was added up
 front:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`foreach2.m4')
@@ -7231,7 +7269,7 @@ foreach(`x', `(`1', `2', `3', `4')', `x
 In summary, recursion over list elements is trickier than it appeared at
 first glance, but provides a powerful idiom within @code{m4} processing.
 As a final demonstration, both list styles are now able to handle
-several scenarios that would wreak havoc on the original
+several scenarios that would wreak havoc on one or both of the original
 implementations.  This points out one other difference between the
 list styles.  @code{foreach} evaluates unquoted list elements only once,
 in preparation for calling @address@hidden, similary for
@@ -7243,6 +7281,7 @@ deciding which list style to use, one must take into 
account whether
 repeating the side effects of unquoted list elements will have any
 detrimental effects.
 
address@hidden examples
 @example
 $ @kbd{m4 -d -I examples}
 include(`foreach2.m4')
@@ -7264,6 +7303,10 @@ foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', 
`<x>')
 dnl 2-element list of unbalanced parentheses
 foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>')
 @result{}<(><)> / <(><)>
+define(`ab', `oops')dnl using defn(`iterator')
+foreach(`x', `(`a', `b')', `defn(`x')') /dnl
+ foreachq(`x', ``a', `b'', `defn(`x')')
address@hidden / ab
 define(`active', `ACT, IVE')
 @result{}
 traceon(`active')
@@ -7355,6 +7398,7 @@ difference between calling @code{capitalize} with the 
expansion of a
 macro, expanding the result of a case change, and changing the case of a
 double-quoted string:
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`capitalize.m4')dnl
@@ -7431,6 +7475,7 @@ must be redefined as @code{_upcase_alt} and 
@code{_downcase_alt}, since
 they contain nested quotes but are invoked with the alternate quoting
 scheme in effect.
 
address@hidden examples
 @example
 $ @kbd{m4 -I examples}
 include(`capitalize2.m4')dnl


hooks/post-receive
--
GNU M4 source repository