299 lines
10 KiB
HTML
299 lines
10 KiB
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> <tt> </tt>Defining Event Handlers
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <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>
|
|
 <tt> </tt> <tt> </tt> <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>
|
|
 <tt> </tt> <tt> </tt> <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>
|
|
 <tt> </tt> <tt> </tt> <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>
|
|
 <tt> </tt> <tt> </tt> <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>
|
|
 <tt> </tt> <tt> </tt> <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->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>
|
|
 <tt> </tt> <tt> </tt> <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>
|
|
 <tt> </tt> <tt> </tt> <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>
|
|
 <tt> </tt> <tt> </tt> <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>
|
|
 <tt> </tt> <tt> </tt> <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, <tt> </tt> <tt> </tt>March 21, 1996, <tt> </tt> <tt> </tt>net@informatik.uni-bremen.de</body>
|
|
</html>
|