divert extension

From 9f5e389c810aacbd70b04f2530aa52a897cd0ad9 Mon Sep 17 00:00:00 2001
From: Eric Blake <[email protected]>
Date: Fri, 28 Nov 2008 07:46:57 -0700
Subject: [PATCH] Add extension to divert builtin.

* src/builtin.c (m4_divert): Support optional second parameter.
* src/output.c (divert_text): Optimize empty output.
* doc/m4.texinfo (Divert): Document the extension.
* NEWS: Likewise.
* THANKS: Update.
Reported by Daniel Richard G.

Signed-off-by: Eric Blake <[email protected]>
(cherry picked from commit 4f82b1e37666722c57e9e6fd2495d9c1cd694db8)
---
 ChangeLog      |   10 +++++++++
 NEWS           |    5 ++++
 THANKS         |    1 +
 doc/m4.texinfo |   61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 src/builtin.c  |    3 +-
 src/output.c   |    2 +-
 6 files changed, 79 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d100a59..2085dea 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2008-11-28  Eric Blake  <[email protected]>
+
+	Add extension to divert builtin.
+	* src/builtin.c (m4_divert): Support optional second parameter.
+	* src/output.c (divert_text): Optimize empty output.
+	* doc/m4.texinfo (Divert): Document the extension.
+	* NEWS: Likewise.
+	* THANKS: Update.
+	Reported by Daniel Richard G.
+
 2008-11-26  Eric Blake  <[email protected]>
 
 	Keep COPYING in repository.
diff --git a/NEWS b/NEWS
index bb61b72..3fb4d90 100644
--- a/NEWS
+++ b/NEWS
@@ -42,6 +42,11 @@ Foundation, Inc.
    then apply this patch:
      http://git.sv.gnu.org/gitweb/?p=autoconf.git;a=commitdiff;h=56d42fa71
 
+** The `divert' builtin now accepts an optional second argument of text
+   that is immediately placed in the new diversion, regardless of whether
+   the current expansion is nested within argument collection of another
+   macro.
+
 ** The `-d'/`--debug' command-line option now understands `-' and `+'
    modifiers, the way the builtin `debugmode' has always done; this allows
    `-d-V' to disable prior debug settings from the command line, similar to
diff --git a/THANKS b/THANKS
index 6a048b9..bb8a651 100644
--- a/THANKS
+++ b/THANKS
@@ -28,6 +28,7 @@ Cesar Strauss		[email protected]
 Chris McGuire		[email protected]
 Damian Menscher		[email protected]
 Dan Jacobson		[email protected]
+Daniel Richard G.	[email protected]
 David J. MacKenzie	[email protected]
 David Perlin		[email protected]
 Elbert Pol		[email protected]
diff --git a/doc/m4.texinfo b/doc/m4.texinfo
index f77a6b5..8301bb7 100644
--- a/doc/m4.texinfo
+++ b/doc/m4.texinfo
@@ -5603,11 +5603,17 @@ Divert
 @cindex files, diverting output to
 Output is diverted using @code{divert}:
 
-@deffn Builtin divert (@dvar{number, 0})
+@deffn Builtin divert (@dvar{number, 0}, @ovar{text})
 The current diversion is changed to @var{number}.  If @var{number} is left
 out or empty, it is assumed to be zero.  If @var{number} cannot be
 parsed, the diversion is unchanged.
 
+@cindex @acronym{GNU} extensions
+As a @acronym{GNU} extension, if optional @var{text} is supplied and
+@var{number} was valid, then @var{text} is immediately output to the new
+diversion, regardless of whether the expansion of @code{divert} occurred
+while collecting arguments for another macro.
+
 The expansion of @code{divert} is void.
 @end deffn
 
@@ -5671,6 +5677,59 @@ Divert
 @result{}world
 @end example
 
+The ability to immediately output extra text is a @acronym{GNU}
+extension, but it can prove useful for ensuring that text goes to a
+particular diversion no matter how many pending macro expansions are in
+progress.  For a demonstration of why this is useful, it is important to
+understand in the example below why @samp{one} is output in diversion 2,
+not diversion 1, while @samp{three} and @samp{five} both end up in the
+correctly numbered diversion.  The key point is that when @code{divert}
+is executed unquoted as part of the argument collection of another
+macro, the side effect takes place immediately, but the text @samp{one}
+is not passed to any diversion until after the @samp{divert(`2')} and
+the enclosing @code{echo} have also taken place.  The example with
+@samp{three} shows how following the quoting rule of thumb delays the
+invocation of @code{divert} until it is not nested in any argument
+collection context, while the example with @samp{five} shows the use of
+the optional argument to speed up the output process.
+
+@example
+define(`echo', `$1')
+@result{}
+echo(divert(`1')`one'divert(`2'))`'dnl
+echo(`divert(`3')three`'divert(`4')')`'dnl
+echo(divert(`5', `five')divert(`6'))`'dnl
+divert
+@result{}
+undivert(`1')
+@result{}
+undivert(`2')
+@result{}one
+undivert(`3')
+@result{}three
+undivert(`4')
+@result{}
+undivert(`5')
+@result{}five
+undivert(`6')
+@result{}
+@end example
+
+@ignore
+@comment additional tests, not worth documenting in manual
+
+@comment options: -s
+@example
+$ @kbd{m4 -s}
+define(`echo', `$1')dnl
+divert(`-1', `discarded without warning')
+divert`'dnl
+echo(` world'divert(divnum, `hello'))
+@result{}#line 4 "stdin"
+@result{}hello world
+@end example
+@end ignore
+
 Note that @code{divert} is an English word, but also an active macro
 without arguments.  When processing plain text, the word might appear in
 normal text and be unintentionally swallowed as a macro invocation.  One
diff --git a/src/builtin.c b/src/builtin.c
index 267292c..24f2df6 100644
--- a/src/builtin.c
+++ b/src/builtin.c
@@ -1304,11 +1304,12 @@ m4_divert (struct obstack *obs, int argc, macro_arguments *argv)
   const call_info *me = arg_info (argv);
   int i = 0;
 
-  bad_argc (me, argc, 0, 1);
+  bad_argc (me, argc, 0, 2);
   if (argc >= 2 && !numeric_arg (me, ARG (1), &i))
     return;
 
   make_diversion (i);
+  divert_text (NULL, ARG (2), ARG_LEN (2), current_line);
 }
 
 /*-----------------------------------------------------.
diff --git a/src/output.c b/src/output.c
index 6d74ecd..6a02b80 100644
--- a/src/output.c
+++ b/src/output.c
@@ -479,7 +479,7 @@ divert_text (struct obstack *obs, const char *text, int length, int line)
 
   /* Do nothing if TEXT should be discarded.  */
 
-  if (output_diversion == NULL)
+  if (output_diversion == NULL || !length)
     return;
 
   /* Output TEXT to a file, or in-memory diversion buffer.  */
-- 
1.6.0.4