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