(m4.info)Undivert

---

Next: Divnum Prev: Divert Up: Diversions

---

Enter node , (file) or (file)node

10.2 Undiverting output
=======================

Diverted text can be undiverted explicitly using the builtin 'undivert':

 -- Builtin: undivert ([DIVERSIONS...])
     Undiverts the numeric DIVERSIONS given by the arguments, in the
     order given.  If no arguments are supplied, all diversions are
     undiverted, in numerical order.

     As a GNU extension, DIVERSIONS may contain non-numeric strings,
     which are treated as the names of files to copy into the output
     without expansion.  A warning is issued if a file could not be
     opened.

     The expansion of 'undivert' is void.

     divert(`1')
     This text is diverted.
     divert
     =>
     This text is not diverted.
     =>This text is not diverted.
     undivert(`1')
     =>
     =>This text is diverted.
     =>

   Notice the last two blank lines.  One of them comes from the newline
following 'undivert', the other from the newline that followed the
'divert'!  A diversion often starts with a blank line like this.

   When diverted text is undiverted, it is _not_ reread by 'm4', but
rather copied directly to the current output, and it is therefore not an
error to undivert into a diversion.  Undiverting the empty string is the
same as specifying diversion 0; in either case nothing happens since the
output has already been flushed.

     divert(`1')diverted text
     divert
     =>
     undivert()
     =>
     undivert(`0')
     =>
     undivert
     =>diverted text
     =>
     divert(`1')more
     divert(`2')undivert(`1')diverted text`'divert
     =>
     undivert(`1')
     =>
     undivert(`2')
     =>more
     =>diverted text

   When a diversion has been undiverted, the diverted text is discarded,
and it is not possible to bring back diverted text more than once.

     divert(`1')
     This text is diverted first.
     divert(`0')undivert(`1')dnl
     =>
     =>This text is diverted first.
     undivert(`1')
     =>
     divert(`1')
     This text is also diverted but not appended.
     divert(`0')undivert(`1')dnl
     =>
     =>This text is also diverted but not appended.

   Attempts to undivert the current diversion are silently ignored.
Thus, when the current diversion is not 0, the current diversion does
not get rearranged among the other diversions.

     divert(`1')one
     divert(`2')two
     divert(`3')three
     divert(`2')undivert`'dnl
     divert`'undivert`'dnl
     =>two
     =>one
     =>three

   GNU 'm4' allows named files to be undiverted.  Given a non-numeric
argument, the contents of the file named will be copied, uninterpreted,
to the current output.  This complements the builtin 'include' (Note:
Include).  To illustrate the difference, assume the file 'foo'
contains:

     $ cat foo
     bar

then

     define(`bar', `BAR')
     =>
     undivert(`foo')
     =>bar
     =>
     include(`foo')
     =>BAR
     =>

   If the file is not found (or cannot be read), an error message is
issued, and the expansion is void.  It is possible to intermix files and
diversion numbers.

     divert(`1')diversion one
     divert(`2')undivert(`foo')dnl
     divert(`3')diversion three
     divert`'dnl
     undivert(`1', `2', `foo', `3')dnl
     =>diversion one
     =>bar
     =>bar
     =>diversion three