Info Catalog m4: Divert m4: Diversions m4: Divnum

m4: Undivert

 
 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' (⇒
 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
 

Info Catalog m4: Divert m4: Diversions m4: Divnum