121 lines
3.8 KiB
HTML
121 lines
3.8 KiB
HTML
<html>
|
|
<head>
|
|
<!-- This file has been generated by unroff 1.0, 03/21/96 19:29:43. -->
|
|
<!-- Do not edit! -->
|
|
<link rev="made" href="mailto:net@informatik.uni-bremen.de">
|
|
<title>unroff Programmer's Manual, section 6.</title>
|
|
</head><body>
|
|
<h2><a name="section6">6.</a> <tt> </tt>Event Procedures with Side-Effects
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Besides the basic events described in the
|
|
<a href="m-3.html#.events">preceding sections</a>,
|
|
another group of--slightly different--events exist and can
|
|
be handled by user-defined Scheme procedures.<tt> </tt>
|
|
These events are not related to troff functions, but to a number of
|
|
other conditions that are encountered when processing documents:
|
|
<ul>
|
|
<li>
|
|
the end of an input line
|
|
<li>
|
|
the beginning of a troff input file processed by
|
|
<i>unroff
|
|
</i><li>
|
|
the end of a troff input file
|
|
<li>
|
|
startup of the program
|
|
<li>
|
|
termination of the program
|
|
<li>
|
|
a keyword/value option encountered in the command line.<tt> </tt>
|
|
</ul>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Among other tasks, these events can be used to generate a prologue and
|
|
epilogue for each input file.<tt> </tt>
|
|
In contrast to the events described in the previous section, handlers for
|
|
these events are called solely for their side-effects.<tt> </tt>
|
|
Each event handler must be a Scheme procedure.<tt> </tt>
|
|
Their results are ignored, thus the procedures must have side-effects
|
|
to be useful.<tt> </tt>
|
|
Another difference is that more than one event handler can be associated
|
|
with each request.<tt> </tt>
|
|
A numeric
|
|
<i>level
|
|
</i>(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.<tt> </tt>
|
|
<h2>
|
|
(defevent <i>event</i> <i>level</i> <i>handler</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Associates the procedure
|
|
<i>handler
|
|
</i>with an event and returns the previous event handler registered
|
|
for this combination of event and level.<tt> </tt>
|
|
<i>level
|
|
</i>is an integer between 0 and 99;
|
|
<i>handler
|
|
</i>is a procedure, or the literal #f to remove a previously defined handler.<tt> </tt>
|
|
<i>event
|
|
</i>indicates the type of event and is one of the following Scheme symbols:
|
|
<i>line
|
|
</i>(end of input line),
|
|
<i>prolog
|
|
</i>(beginning of input file),
|
|
<i>epilog
|
|
</i>(end of input file),
|
|
<i>start
|
|
</i>(program start),
|
|
<i>exit
|
|
</i>(program termination),
|
|
<i>option
|
|
</i>(keyword/value command line option).<tt> </tt>
|
|
<p>
|
|
Procedures defined for the events
|
|
<i>prolog
|
|
</i>and
|
|
<i>epilog
|
|
</i>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
|
|
<i>unroff
|
|
</i>is taking its input from standard input.<tt> </tt>
|
|
Procedures defined for the event
|
|
<i>option
|
|
</i>are passed the option's name and value as strings.<tt> </tt>
|
|
All other event procedures are invoked without arguments.<tt> </tt>
|
|
<i>unroff
|
|
</i>provides a default handler for
|
|
<i>option
|
|
</i>(see the
|
|
<a href="m-15.html#.options">primitives for options</a>
|
|
below).<tt> </tt>
|
|
<p>
|
|
Example:
|
|
<dl><dt><dd>
|
|
<pre>
|
|
(defevent 'exit 50 ; cleanup on exit
|
|
(lambda ()
|
|
...))
|
|
</pre>
|
|
</dl>
|
|
The handler defined in this way will be executed on termination,
|
|
after any handlers with levels 0-49.<tt> </tt>
|
|
<h2>
|
|
(eventdef <i>event</i> <i>level</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Returns the procedure defined as a handler for
|
|
<i>event
|
|
</i>and
|
|
<i>level</i>,
|
|
or #f if no such handler exists.<tt> </tt>
|
|
See
|
|
<i>defevent
|
|
</i>above for a description of the arguments.<tt> </tt>
|
|
<p><hr>
|
|
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 21, 1996, <tt> </tt> <tt> </tt>net@informatik.uni-bremen.de</body>
|
|
</html>
|