193 lines
6.0 KiB
HTML
193 lines
6.0 KiB
HTML
<html>
|
|
<head>
|
|
<!-- This file has been generated by unroff 1.0, 03/21/96 19:29:48. -->
|
|
<!-- Do not edit! -->
|
|
<link rev="made" href="mailto:net@informatik.uni-bremen.de">
|
|
<title>unroff Programmer's Manual, section 15.</title>
|
|
</head><body>
|
|
<h2><a name="section15">15.</a> <tt> </tt>Utilities for Back-Ends
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Writers of new back-ends (either for new output formats or for new
|
|
troff macro packages) can benefit from a number of Scheme procedures
|
|
and macros that are exported by the file ``scm/troff.scm'' which is
|
|
loaded from the library directory on startup.<tt> </tt>
|
|
The first two,
|
|
<i>eval-if-mode
|
|
</i>and
|
|
<i>set-option!
|
|
</i>are exceptions in that they are typically used by the user's
|
|
initialization file ``~/.unroff'' to customize
|
|
<i>unroff</i>,
|
|
rather than by programmers of
|
|
<i>unroff</i>.<tt> </tt>
|
|
<h2>
|
|
(set-option! <i>name</i> <i>value</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>This procedure assigns
|
|
<i>value
|
|
</i>to the option
|
|
<i>name</i>.<tt> </tt>
|
|
The value must be appropriate for the option's type.<tt> </tt>
|
|
<h2>
|
|
(eval-if-mode <i>mode</i> <i>.</i> <i>forms</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>This macro is typically used to evaluate a sequence of expressions,
|
|
<i>forms</i>,
|
|
depending on the output format and macro package specified in
|
|
the command line.<tt> </tt>
|
|
<i>mode
|
|
</i>is a list of two symbols, an output format and a macro package
|
|
name; the wildcard `*' can be used for both elements.<tt> </tt>
|
|
The
|
|
<i>forms
|
|
</i>are evaluated if the first symbol matches the value of the option
|
|
<b>-f
|
|
</b>and the second symbol matches the value of the option
|
|
<b>-m</b>;
|
|
in this case the result of the last sub-expression is returned.<tt> </tt>
|
|
Otherwise the forms are ignored and #f is returned.<tt> </tt>
|
|
Example:
|
|
<dl><dt><dd>
|
|
<pre>
|
|
(eval-if-mode (* html)
|
|
(set-option! 'mail-address "net@cs.tu-berlin.de"))
|
|
</pre>
|
|
</dl>
|
|
<h2>
|
|
(quit <i>message</i> <i>.</i> <i>args</i>)
|
|
<br>
|
|
(warn <i>message</i> <i>.</i> <i>args</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>These procedures print
|
|
<i>message
|
|
</i>and the optional
|
|
<i>args
|
|
</i>on the port returned by
|
|
<i>error-port
|
|
</i>using the primitive
|
|
<i>format</i>.<tt> </tt>
|
|
The message is prefixed by the program name, current input file
|
|
name and line number, and, in case of
|
|
<i>warn</i>,
|
|
the word ``warning''.<tt> </tt>
|
|
A newline is appended.<tt> </tt>
|
|
<i>quit
|
|
</i>causes the program to exit with an exit code of 1, and
|
|
<i>warn
|
|
</i>returns the empty string (and can therefore be used as the last
|
|
form in event procedures).<tt> </tt>
|
|
<h2>
|
|
<a name=".options">(option <i>name</i>)</a></h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Returns the value of the specified option.<tt> </tt>
|
|
<h2>
|
|
(define-option <i>name</i> <i>type</i> <i>initial</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Defines a new option with the specified name, type, and initial
|
|
value.<tt> </tt>
|
|
<i>name
|
|
</i>and
|
|
<i>type
|
|
</i>are strings or symbols.<tt> </tt>
|
|
There exist a number of predefined, basic option types as
|
|
described in the
|
|
<a href="./unroff.1.html">manual page</a>
|
|
<i>unroff</i>(1).<tt> </tt>
|
|
The initial value need not match the option's type; for example,
|
|
the following expression is valid:
|
|
<dl><dt><dd>
|
|
<pre>
|
|
(define-option 'author 'string #f)
|
|
</pre>
|
|
</dl>
|
|
<h2>
|
|
(define-option-type <i>name</i> <i>pre-check</i> <i>pre-msg</i> <i>converter</i> <i>post-check</i> <i>post-msg</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>This procedure defines a new option type named
|
|
<i>name
|
|
</i>which can then be used in calls to
|
|
<i>define-option</i>.<tt> </tt>
|
|
If an option of this type is specified in the command line,
|
|
the procedure
|
|
<i>pre-check
|
|
</i>is applied to the option's value (a string).<tt> </tt>
|
|
In this case, if
|
|
<i>pre-check
|
|
</i>returns #f,
|
|
<i>quit
|
|
</i>is called with an error message including the string
|
|
<i>pre-msg</i>,
|
|
which should describe the expected option value format
|
|
(e.g. ``a character'').<tt> </tt>
|
|
If the check succeeds, the procedure
|
|
<i>converter
|
|
</i>is called with the option's current value and with the string as given
|
|
in the command line.<tt> </tt>
|
|
The job of the converter procedure is to convert the option value
|
|
from a string representation to a Scheme object matching the option's
|
|
actual Scheme type.<tt> </tt>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Finally, the predicate
|
|
<i>post-check
|
|
</i>is applied either to the result of
|
|
<i>converter
|
|
</i>or, if the option was set through a call to
|
|
<i>set-option!</i>,
|
|
to this procedure's argument.<tt> </tt>
|
|
If the predicate returns #f, a error is signaled with an error
|
|
message including
|
|
<i>post-msg
|
|
</i>as described in the previous paragraph.<tt> </tt>
|
|
For example, the predefined option type ``boolean'' is defined as
|
|
follows:
|
|
<dl><dt><dd>
|
|
<pre>
|
|
(define-option-type 'boolean
|
|
(lambda (x) (member x '("0" "1"))) "0 or 1"
|
|
(lambda (old new) (string=? new "1"))
|
|
boolean? "a boolean")
|
|
</pre>
|
|
</dl>
|
|
<h2>
|
|
(with-input-from-stream <i>target</i> <i>.</i> <i>forms</i>)
|
|
<br>
|
|
(with-output-to-stream <i>target</i> <i>.</i> <i>forms</i>)
|
|
<br>
|
|
(with-output-appended-to-stream <i>target</i> <i>.</i> <i>forms</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>These macros open an input stream (first macro) or output stream to the
|
|
specified target and assign it to the current input stream (first
|
|
macro) or current output stream.<tt> </tt>
|
|
Then the specified
|
|
<i>forms
|
|
</i>are evaluated, the stream is reassigned its previous value, and
|
|
the result of the last sub-expression in
|
|
<i>forms
|
|
</i>is returned.<tt> </tt>
|
|
The macros recur on the primitives
|
|
<i>open-input-stream</i>,
|
|
<i>open-output-stream</i>,
|
|
and
|
|
<i>append-output-stream</i>,
|
|
respectively.<tt> </tt>
|
|
<h2>
|
|
(skip-lines <i>stop</i>)
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Reads input lines using
|
|
<i>read-line-expand
|
|
</i>until either end-of-stream is reached (in this case a warning
|
|
is displayed) or a line matching the string argument
|
|
<i>stop
|
|
</i>is encountered.<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>
|