Next: , Previous: Diagnostic Macros, Up: Programming in M4sugar


8.3.3 Diversion support

M4sugar makes heavy use of diversions, because it is often the case that text that must appear early in the output is not discovered until late in the input. Additionally, some of the topological sorting algorithms used in resolving macro dependencies use diversions. Therefore, most macros should not need to change diversions directly, but rather rely on higher-level M4sugar macros to manage diversions transparently.

To make diversion management easier, M4sugar uses the concept of named diversions. Rather than using diversion numbers directly, it is nicer to associate a name with each diversion; the diversion number associated with a particular diversion name is an implementation detail, so you should only use diversion names. In general, you should not output text to a named diversion until after calling the appropriate initialization routine for your language (m4_init, AS_INIT, AT_INIT, ...), although there are some exceptions documented below.

M4sugar defines two named diversions.

KILL
Text written to this diversion is discarded. This is the default diversion once M4sugar is initialized.
GROW
This diversion is used behind the scenes by topological sorting macros, such as AC_REQUIRE.

M4sh adds several more named diversions.

BINSH
This diversion is reserved for the `#!' interpreter line.
HEADER-REVISION
This diversion holds text from AC_REVISION.
HEADER-COMMENT
This diversion holds comments about the purpose of a file.
HEADER-COPYRIGHT
This diversion is managed by AC_COPYRIGHT.
M4SH-SANITIZE
This diversion contains M4sh sanitization code, used to ensure M4sh is executing in a reasonable shell environment.
M4SH-INIT
This diversion contains M4sh initialization code, initializing variables that are required by other M4sh macros.
BODY
This diversion contains the body of the shell code, and is the default diversion once M4sh is initialized.

Autotest inherits diversions from M4sh, and changes the default diversion from BODY back to KILL. It also adds several more named diversions, with the following subset designed for developer use.

PREPARE_TESTS
This diversion contains initialization sequences which are executed after atconfig and atlocal, and after all command line arguments have been parsed, but prior to running any tests. It can be used to set up state that is required across all tests. This diversion will work even before AT_INIT.

For now, the named diversions of Autoconf and Autoheader, and the remaining diversions of Autotest, are not documented. In other words, intentionally outputting text into an undocumented diversion is subject to breakage in a future release of Autoconf.

— Macro: m4_divert_once (diversion, [content])

Similar to m4_divert_text, except that content is only output to diversion if this is the first time that m4_divert_once has been called with its particular arguments.

— Macro: m4_divert_pop ([diversion])

If provided, check that the current diversion is indeed diversion. Then change to the diversion located earlier on the stack, giving an error if an attempt is made to pop beyond the initial m4sugar diversion of KILL.

— Macro: m4_divert_push (diversion)

Remember the former diversion on the diversion stack, and output subsequent text into diversion. M4sugar maintains a diversion stack, and issues an error if there is not a matching pop for every push.

— Macro: m4_divert_text (diversion, [content])

Output content and a newline into diversion, without affecting the current diversion. Shorthand for:

          m4_divert_push([diversion])content
          m4_divert_pop([diversion])dnl
     
— Macro: m4_init

Initialize the M4sugar environment, setting up the default named diversion to be KILL.