Next: Text handling Prev: File Inclusion Up: Top

10 Diverting and undiverting output

Diversions are a way of temporarily saving output.  The output of `m4'
can at any time be diverted to a temporary file, and be reinserted into
the output stream, "undiverted", again at a later time.

   Numbered diversions are counted from 0 upwards, diversion number 0
being the normal output stream.  The number of simultaneous diversions
is limited mainly by the memory used to describe them, because GNU `m4'
tries to keep diversions in memory.  However, there is a limit to the
overall memory usable by all diversions taken altogether (512K,
currently).  When this maximum is about to be exceeded, a temporary
file is opened to receive the contents of the biggest diversion still
in memory, freeing this memory for other diversions.  When creating the
temporary file, `m4' honors the value of the environment variable
`TMPDIR', and falls back to `/tmp'.  So, it is theoretically possible
that the number and aggregate size of diversions is limited only by
available disk space.

   Diversions make it possible to generate output in a different order
than the input was read.  It is possible to implement topological
sorting dependencies.  For example, GNU Autoconf makes use of
diversions under the hood to ensure that the expansion of a prerequisite
macro appears in the output prior to the expansion of a dependent macro,
regardless of which order the two macros were invoked in the user's
input file.

* Divert
Diverting output
* Undivert
Undiverting output
* Divnum
Diversion numbers
* Cleardivert
Discarding diverted text

automatically generated by info2www