File: m4.info,  Node: Cleardivert,  Prev: Divnum,  Up: Diversions

10.4 Discarding diverted text
=============================

Often it is not known, when output is diverted, whether the diverted
text is actually needed.  Since all non-empty diversion are brought back
on the main output stream when the end of input is seen, a method of
discarding a diversion is needed.  If all diversions should be
discarded, the easiest is to end the input to ‘m4’ with ‘divert(`-1')’
followed by an explicit ‘undivert’:

     divert(`1')
     Diversion one: divnum
     divert(`2')
     Diversion two: divnum
     divert(`-1')
     undivert
     ^D

No output is produced at all.

   Clearing selected diversions can be done with the following macro:

 -- Composite: cleardivert([DIVERSIONS...])
     Discard the contents of each of the listed numeric DIVERSIONS.

     define(`cleardivert',
     `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
     ⇒

   It is called just like ‘undivert’, but the effect is to clear the
diversions, given by the arguments.  (This macro has a nasty bug!  You
should try to see if you can find it and correct it; or *note Answers:
Improved cleardivert.).