6.  Event Procedures with Side-Effects

      Besides the basic events described in the preceding sections, another group of--slightly different--events exist and can be handled by user-defined Scheme procedures. These events are not related to troff functions, but to a number of other conditions that are encountered when processing documents:

• the end of an input line
• the beginning of a troff input file processed by unroff
• the end of a troff input file
• startup of the program
• termination of the program
• a keyword/value option encountered in the command line.

      Among other tasks, these events can be used to generate a prologue and epilogue for each input file. In contrast to the events described in the previous section, handlers for these events are called solely for their side-effects. Each event handler must be a Scheme procedure. Their results are ignored, thus the procedures must have side-effects to be useful. Another difference is that more than one event handler can be associated with each request. A numeric level (a small integer number) is specified together with each event handler, and when the corresponding event is triggered, all procedures defined for this event are executed in increasing order as indicated by their levels.

(defevent event level handler)

      Associates the procedure handler with an event and returns the previous event handler registered for this combination of event and level. level is an integer between 0 and 99; handler is a procedure, or the literal #f to remove a previously defined handler. event indicates the type of event and is one of the following Scheme symbols: line (end of input line), prolog (beginning of input file), epilog (end of input file), start (program start), exit (program termination), option (keyword/value command line option).

Procedures defined for the events prolog and epilog are called with two string arguments: the path name (as specified by the user) and the file name component of the troff input file whose processing has just begun or finished, or the string ``stdin'' if unroff is taking its input from standard input. Procedures defined for the event option are passed the option's name and value as strings. All other event procedures are invoked without arguments. unroff provides a default handler for option (see the primitives for options below).

Example:

(defevent 'exit 50     ; cleanup on exit
  (lambda ()
    ...))

(eventdef event level)

      Returns the procedure defined as a handler for event and level, or #f if no such handler exists. See defevent above for a description of the arguments.