(autoconf.info)Diversion support

Next: Conditional constructs Prev: 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.
     Text written to this diversion is discarded.  This is the default
     diversion once M4sugar is initialized.

     This diversion is used behind the scenes by topological sorting
     macros, such as `AC_REQUIRE'.

   M4sh adds several more named diversions.
     This diversion is reserved for the `#!' interpreter line.

     This diversion holds text from `AC_REVISION'.

     This diversion holds comments about the purpose of a file.

     This diversion is managed by `AC_COPYRIGHT'.

     This diversion contains M4sh sanitization code, used to ensure
     M4sh is executing in a reasonable shell environment.

     This diversion contains M4sh initialization code, initializing
     variables that are required by other M4sh macros.

     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.
     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

 -- Macro: m4_divert_text (DIVERSION, [CONTENT])
     Output CONTENT and a newline into DIVERSION, without affecting the
     current diversion.  Shorthand for:

 -- Macro: m4_init
     Initialize the M4sugar environment, setting up the default named
     diversion to be `KILL'.

automatically generated by info2www