unroff-website/www/doc/m-4.html

<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/21/96 19:29:41. -->
<!-- Do not edit! -->
<link rev="made" href="mailto:net@informatik.uni-bremen.de">
<title>unroff Programmer's Manual, section 4.</title>
</head><body>
<h2><a name="section4">4.</a>&#160;<tt> </tt>Defining Event Handlers
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>In the following list of Scheme primitives, the argument
<i>name
</i>denotes the name of a troff request, macro, escape sequence
etc.  (without any initial period or escape character) and can be
supplied in form of a Scheme string, a Scheme symbol, or
a Scheme character:
<dl><dt><dd>
<pre>
(defrequest "ti" ...)

(defrequest 'sp  ...)

(defescape  #\h  ...)
</pre>
</dl>
(the primitives
<i>defrequest
</i>and
<i>defescape
</i>will be introduced in a moment).<tt> </tt>
An argument named
<i>handler
</i>is either a procedure (usually a lambda expression) which returns
a string, a symbol, or a character; or
<i>handler
</i>can itself be specified as a string, symbol, or character.<tt> </tt>
In addition, the literal ``#f'' (false) can be supplied as a
<i>handler
</i>argument to remove any event handler that is currently associated with
that event.<tt> </tt>
Each of the ``def'' primitives listed below returns the handler
that was previously associated with the corresponding event,
or ``#f'' if the event was not handled.<tt> </tt>
<h2>
(defrequest <i>name</i> <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>Associates the given handler with the given troff request.<tt> </tt>
If
<i>handler
</i>is a procedure, it is passed the request's name and arguments
as strings when called later.<tt> </tt>
Passing the name of the request as the first argument aids in
associating the same procedure with several different requests.<tt> </tt>
<i>unroff
</i>does not limit the number of arguments to requests, thus,
an event handling procedure for a requests that takes a variable
number of arguments could be defined like this:
<dl><dt><dd>
<pre>
(defrequest 'rm
  (lambda (rm . args) ...))
</pre>
</dl>
<p>
If the request is invoked with fewer arguments than the procedure
has formal arguments, the remaining arguments are bound to
the empty string.<tt> </tt>
If the request is invoked with
<i>more
</i>arguments than the procedure has formal arguments, the last lambda
variable is assigned a string consisting of the (space-delimited)
arguments left over after the other formal arguments have been bound to
the other actual arguments.<tt> </tt>
However, if
<i>handler
</i>has only one formal argument, an error message is displayed when the
request is called with any arguments at all and the event is skipped.<tt> </tt>
For example, consider the following handler for the (non-existing)
request ``xx'':
<dl><dt><dd>
<pre>
(defrequest 'xx
  (lambda (name a b) ...))
</pre>
</dl>
The procedure's arguments
<i>a
</i>and
<i>b
</i>will be bound as follows when the request is invoked:
<dl><dt><dd>
<pre>
.xx foo              name="xx"  a="foo"  b=""

.xx foo bar baz      name="xx"  a="foo"  b="bar baz"
</pre>
</dl>
<h2>
(defmacro <i>name</i> <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>Associates
<i>handler
</i>with the given troff macro, superseding
any definition for this macro established by the ordinary ``.de''
request.<tt> </tt>
The only difference between
<i>defrequest
</i>and
<i>defmacro
</i>is the way arguments are bound in case
<i>handler
</i>is a procedure
(troff employs slightly different rules when parsing the call
to a request and a macro invocation).<tt> </tt>
The quote character can be used in the latter case to surround
arguments containing spaces, while quote characters are treated as
normal characters in requests, which allows for the following
remarkable troff idiom:
<dl><dt><dd>
<pre>
.ds xy "hello
</pre>
</dl>
In contrast to event handlers defined for requests, the formal
arguments of a handler procedure associated with a macro must
match the actual arguments in the normal way, that is, as if
the procedure were invoked from within Scheme.<tt> </tt>
A warning message is displayed if the number of macro arguments
does not match the number of formal procedure arguments, and
the event is skipped.<tt> </tt>
<h2>
(defspecial <i>name</i> <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>Associates
<i>handler
</i>with the special character whose name is
<i>name</i>.<tt> </tt>
The name must have a length of 2.<tt> </tt>
In addition, an empty name can be specified to define a
``fallback'' handler that is called for special characters
for which no handler exists.<tt> </tt>
Like all event handler procedures,
<i>handler
</i>can have arbitrary side-effects in addition to returning a
result; for example, the procedure may display a warning message
if the special character cannot be represented in the target
language and an approximation must be rendered instead.<tt> </tt>
<h2>
(defstring <i>name</i> <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>Associates a handler with the specified troff string.<tt> </tt>
As
<i>unroff
</i>provides a default handler for the request ``.ds'' to implement
used-defined strings,
<i>defstring
</i>is primarily used to give definitions for strings exported by
troff macro packages.<tt> </tt>
<h2>
(defnumreg <i>name</i> <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>This request behaves like
<i>defstring</i>,
except that it works on number registers.<tt> </tt>
Note that the Scheme primitive
<i>number-&gt;string
</i>may have to be used by
<i>handler
</i>(if it is a procedure) to convert a numeric result into a string
that can be returned from the handler.<tt> </tt>
<p>
In troff input, number registers as well as strings, special
characters, and escape sequences can be denoted using the groff
``long name'' syntax, unless troff compatibility has been enabled:
<dl><dt><dd>
<pre>
\n[numreg]   \n[string]   \f[font]   \[em]   ...
</pre>
</dl>
<h2>
(defescape <i>name</i> <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>Associates an event handler with an escape sequence.<tt> </tt>
<i>name
</i>must have a length of 1, unless the empty string is
given to define a ``fallback'' event handler (as with
<i>defspecial</i>).<tt> </tt>
Handlers defined for certain escape sequences are passed
a second argument in addition to the name of the escape sequence.<tt> </tt>
This is true for all escape sequences that have an argument
according to the troff specification:
<dl><dt><dd>
<pre>
\b  \c  \f  \h  \k  \l  \n  \o  \s  \v  \w  \x  \z
\*  \$  \"
</pre>
</dl>
In addition, handlers for these groff escape sequences are passed an
additional argument unless troff compatibility is enabled:
<dl><dt><dd>
<pre>
\A  \C  \L  \N  \R  \V  \Y  \Z
</pre>
</dl>
The form of an escape sequence argument is determined by the
troff specification and cannot be programmed; for example, the
handler for `\z' is passed a character or a special character,
and the handler for `\"' is invoked with the rest of the current
input line sans the terminating newline.<tt> </tt>
(The latter can be used to translate troff comments.)
<p>
Handlers registered for the escape sequences `\n' and '\s' are
passed an optional third argument, one of the Scheme characters
#\+ and #\-, if the escape sequence argument begins with a sign.<tt> </tt>
The sign is then stripped from the actual argument.<tt> </tt>
<p>
As `\n' and `\*' are treated as ordinary escape sequences,
handlers can be defined for them to achieve some form of fallback
for number register and strings.<tt> </tt>
<i>unroff
</i>provides suitable default handlers for `\n', `\*', and '\$' as part
of the implementation of user-defined number registers, strings,
and macros.<tt> </tt>
These handlers can be overridden if desired.<tt> </tt>
<h2>
(defchar <i>name</i> <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>Associates
<i>handler
</i>with a character.<tt> </tt>
<i>name
</i>must have a length of 1.<tt> </tt>
Each time the specified character is encountered in the troff
input, the result (or value) of
<i>handler
</i>is output in place of the character.<tt> </tt>
Character translations are not applied to the result of event
handlers; event procedures can use the Scheme primitive
<a href="m-8.html#.translate"><i>translate</i></a>
(as described below) to execute the character translations
established by calls to
<i>defchar
</i>if desired.<tt> </tt>
<p>
<i>defchar
</i>currently has a number of weaknesses.<tt> </tt>
The argument cannot be a special character
(that is,
<i>name
</i>must be a plain character), and the mechanism cannot be used
to achieve true
<i>output
</i>translations as with the troff request ``.tr'' or the groff
request ``.char''.<tt> </tt>
<h2>
(defsentence <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>Defines a handler to be consulted on end of sentence.<tt> </tt>
If
<i>handler
</i>is a procedure, it is passed the punctuation mark ending the
sentence as its argument (in form of a Scheme character).<tt> </tt>
In any case, if an event handler has been specified, its result
(or value) is output in place of the end-of-sentence mark and
the newline character following it.<tt> </tt>
<h2>
(defequation <i>handler</i>)
</h2>
<p>
&#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>Defines a handler for
<i>eqn
</i>inline equations.<tt> </tt>
If
<i>handler
</i>is a procedure, it is passed the contents of the inline equation
(with the delimiters stripped) as an argument.<tt> </tt>
When an inline equation is encountered in the troff input and a handler
has been defined for inline equations, the handler's result (or value)
is output in place of the equation.<tt> </tt>
<p>
For inline equations to be recognized, delimiters must be defined first
by passing
<i>eqn
</i>input that includes a ``delim'' directive to the Scheme primitive
<a href="m-13.html#.filter-eqn-line"><i>filter-eqn-line</i></a>
(explained below), as is usually done
by the event handler associated with the request ``.EQ''.<tt> </tt>
<p><hr>
Markup created by <em>unroff</em> 1.0,&#160;<tt> </tt>&#160;<tt> </tt>March 21, 1996,&#160;<tt> </tt>&#160;<tt> </tt>net@informatik.uni-bremen.de</body>
</html>