[SCM] GNU M4 source repository branch, branch-1_4, updated. v1.4.10-25-g08d5b5e

[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=08d5b5e080e2ff7e6808cd32956031e03a467095

The branch, branch-1_4 has been updated
       via  08d5b5e080e2ff7e6808cd32956031e03a467095 (commit)
      from  37e491acd84f447920057b1619ebab148adea8b1 (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 08d5b5e080e2ff7e6808cd32956031e03a467095
Author: Eric Blake <address@hidden>
Date:   Sun Oct 28 16:51:28 2007 -0600

    More test coverage for autoconf usage patterns.
    
    * doc/m4.texinfo (Inhibiting Invocation, Pseudo Arguments)
    (Builtin): Add new undocumented tests.
    (Shift): Document cond macro, and add new test.
    
    Signed-off-by: Eric Blake <address@hidden>

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

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

diff --git a/ChangeLog b/ChangeLog
index 992ae22..737a6ec 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2007-10-28  Eric Blake  <address@hidden>
+
+       More test coverage for autoconf usage patterns.
+       * doc/m4.texinfo (Inhibiting Invocation, Pseudo Arguments)
+       (Builtin): Add new undocumented tests.
+       (Shift): Document cond macro, and add new test.
+
 2007-10-27  Eric Blake  <address@hidden>
 
        Document one use of changequote(`(',`)').
diff --git a/doc/m4.texinfo b/doc/m4.texinfo
index 677c859..d7c8140 100644
--- a/doc/m4.texinfo
+++ b/doc/m4.texinfo
@@ -1346,18 +1346,31 @@ empty string.
 
 @cindex rescanning
 The output of macro evaluations is always rescanned.  The following
-example would yield the string @samp{de}, exactly as if @code{m4}
-has been given @address@hidden(`abcde', `3', `2')}} as input:
+example would yield the string @samp{bcd}, exactly as if @code{m4}
+has been given @address@hidden(`abcde', `1', `3')}} as input:
 
 @example
 define(`x', `substr(ab')
 @result{}
-define(`y', `cde, `3', `2')')
+define(`y', `cde, `1', `3')')
 @result{}
 x`'y
address@hidden
address@hidden
 @end example
 
address@hidden
address@hidden Similar, but with argument references, to ensure good test
address@hidden coverage.
address@hidden
+define(`x1', `len(`$1'')
address@hidden
+define(`y1', ``$1')')
address@hidden
+x1(`01234567890123456789')y1(`98765432109876543210')
address@hidden
address@hidden example
address@hidden ignore
+
 Unquoted strings on either side of a quoted string are subject to
 being recognized as macro names.  In the following example, quoting the
 empty string allows for the second @code{macro} to be recognized as such:
@@ -1923,6 +1936,20 @@ foo)
 @result{}bar'
 @end example
 
address@hidden
address@hidden Not worth putting in the manual, but this example is needed for
address@hidden good test coverage of copying large strings across recursion
address@hidden levels.
+
address@hidden
+define(`echo', `$@')dnl
+len((echo(`01234567890123456789',
+          `01234567890123456789')echo(`98765432109876543210',
+                                      `98765432109876543210')))
address@hidden
address@hidden example
address@hidden ignore
+
 A @samp{$} sign in the expansion text, that is not followed by anything
 @code{m4} understands, is simply copied to the macro expansion, as any
 other text is.
@@ -2416,6 +2443,17 @@ builtin(`builtin',)
 @result{}
 @end example
 
address@hidden
address@hidden This example is not worth putting in the manual, but it is
address@hidden needed for full coverage.  Autoconf's m4_include relies heavily
address@hidden on this feature.
+
address@hidden
+builtin(`include', `foo')dnl
address@hidden
address@hidden example
address@hidden ignore
+
 @node Conditionals
 @chapter Conditionals, loops, and recursion
 
@@ -2475,7 +2513,7 @@ as a multibranch, depending on the number of arguments 
supplied:
 @deffnx Builtin ifelse (@var{string-1}, @var{string-2}, @var{equal}, @
   @ovar{not-equal})
 @deffnx Builtin ifelse (@var{string-1}, @var{string-2}, @var{equal-1}, @
-  @var{string-3}, @var{string-4}, @var{equal-2}, @dots{})
+  @var{string-3}, @var{string-4}, @var{equal-2}, @dots{}, @ovar{not-equal})
 Used with only one argument, the @code{ifelse} simply discards it and
 produces no output.
 
@@ -2619,8 +2657,65 @@ reverse(`foo', `bar', `gnats', `and gnus')
 
 While not a very interesting macro, it does show how simple loops can be
 made with @code{shift}, @code{ifelse} and recursion.  It also shows
-that @code{shift} is usually used with @samp{$@@}.  Sometimes, a
-recursive algorithm requires adding quotes to each element:
+that @code{shift} is usually used with @samp{$@@}.  Another example of
+this is an implementation of a short-circuiting conditional operator.
+
address@hidden short-circuiting conditional
address@hidden conditional, short-circuiting
address@hidden Composite cond (@var{test-1}, @var{string-1}, @var{equal-1}, @
+  @ovar{test-2}, @ovar{string-2}, @ovar{equal-2}, @dots{}, @ovar{not-equal})
+Similar to @code{ifelse}, where an equal comparison between the first
+two strings results in the third, otherwise the first three arguments
+are discarded and the process repeats.  The difference is that each
address@hidden<n>} is expanded only when it is encountered.  This means that
+every third argument to @code{cond} is normally given one more level of
+quoting than the corresponding argument to @code{ifelse}.
address@hidden deffn
+
+Here is the implementation of @code{cond}, along with a demonstration of
+how it can short-circuit the side effects in @code{side}.  Notice how
+all the unquoted side effects happen regardless of how many comparisons
+are made with @code{ifelse}, compared with only the relevant effects
+with @code{cond}.
+
address@hidden
+define(`cond',
+`ifelse(`$#', `1', `$1',
+        `ifelse($1, `$2', `$3',
+                `$0(shift(shift(shift($@@))))')')')dnl
+define(`side', `define(`counter', incr(counter))$1')dnl
+define(`example1',
+`define(`counter', `0')dnl
+ifelse(side(`$1'), `yes', `one comparison: ',
+       side(`$1'), `no', `two comparisons: ',
+       side(`$1'), `maybe', `three comparisons: ',
+       `side(`default answer: ')')counter')dnl
+define(`example2',
+`define(`counter', `0')dnl
+cond(`side(`$1')', `yes', `one comparison: ',
+     `side(`$1')', `no', `two comparisons: ',
+     `side(`$1')', `maybe', `three comparisons: ',
+     `side(`default answer: ')')counter')dnl
+example1(`yes')
address@hidden comparison: 3
+example1(`no')
address@hidden comparisons: 3
+example1(`maybe')
address@hidden comparisons: 3
+example1(`feeling rather indecisive today')
address@hidden answer: 4
+example2(`yes')
address@hidden comparison: 1
+example2(`no')
address@hidden comparisons: 2
+example2(`maybe')
address@hidden comparisons: 3
+example2(`feeling rather indecisive today')
address@hidden answer: 4
address@hidden example
+
+Sometimes, a recursive algorithm requires adding quotes to each element,
+or treating multiple arguments as a single element:
 
 @deffn Composite quote (@dots{})
 @deffnx Composite dquote (@dots{})


hooks/post-receive
--
GNU M4 source repository