m4: Undivert

1 
1 10.2 Undiverting output
1 =======================
1 
1 Diverted text can be undiverted explicitly using the builtin 'undivert':
1 
1  -- Builtin: undivert ([DIVERSIONS...])
1      Undiverts the numeric DIVERSIONS given by the arguments, in the
1      order given.  If no arguments are supplied, all diversions are
1      undiverted, in numerical order.
1 
1      As a GNU extension, DIVERSIONS may contain non-numeric strings,
1      which are treated as the names of files to copy into the output
1      without expansion.  A warning is issued if a file could not be
1      opened.
1 
1      The expansion of 'undivert' is void.
1 
1      divert(`1')
1      This text is diverted.
1      divert
1      =>
1      This text is not diverted.
1      =>This text is not diverted.
1      undivert(`1')
1      =>
1      =>This text is diverted.
1      =>
1 
1    Notice the last two blank lines.  One of them comes from the newline
1 following 'undivert', the other from the newline that followed the
1 'divert'!  A diversion often starts with a blank line like this.
1 
1    When diverted text is undiverted, it is _not_ reread by 'm4', but
1 rather copied directly to the current output, and it is therefore not an
1 error to undivert into a diversion.  Undiverting the empty string is the
1 same as specifying diversion 0; in either case nothing happens since the
1 output has already been flushed.
1 
1      divert(`1')diverted text
1      divert
1      =>
1      undivert()
1      =>
1      undivert(`0')
1      =>
1      undivert
1      =>diverted text
1      =>
1      divert(`1')more
1      divert(`2')undivert(`1')diverted text`'divert
1      =>
1      undivert(`1')
1      =>
1      undivert(`2')
1      =>more
1      =>diverted text
1 
1    When a diversion has been undiverted, the diverted text is discarded,
1 and it is not possible to bring back diverted text more than once.
1 
1      divert(`1')
1      This text is diverted first.
1      divert(`0')undivert(`1')dnl
1      =>
1      =>This text is diverted first.
1      undivert(`1')
1      =>
1      divert(`1')
1      This text is also diverted but not appended.
1      divert(`0')undivert(`1')dnl
1      =>
1      =>This text is also diverted but not appended.
1 
1    Attempts to undivert the current diversion are silently ignored.
1 Thus, when the current diversion is not 0, the current diversion does
1 not get rearranged among the other diversions.
1 
1      divert(`1')one
1      divert(`2')two
1      divert(`3')three
1      divert(`2')undivert`'dnl
1      divert`'undivert`'dnl
1      =>two
1      =>one
1      =>three
1 
1    GNU 'm4' allows named files to be undiverted.  Given a non-numeric
1 argument, the contents of the file named will be copied, uninterpreted,
11 to the current output.  This complements the builtin 'include' (⇒
 Include).  To illustrate the difference, assume the file 'foo'
1 contains:
1 
1      $ cat foo
1      bar
1 
1 then
1 
1      define(`bar', `BAR')
1      =>
1      undivert(`foo')
1      =>bar
1      =>
1      include(`foo')
1      =>BAR
1      =>
1 
1    If the file is not found (or cannot be read), an error message is
1 issued, and the expansion is void.  It is possible to intermix files and
1 diversion numbers.
1 
1      divert(`1')diversion one
1      divert(`2')undivert(`foo')dnl
1      divert(`3')diversion three
1      divert`'dnl
1      undivert(`1', `2', `foo', `3')dnl
1      =>diversion one
1      =>bar
1      =>bar
1      =>diversion three
1