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. The first two, eval-if-mode and set-option! are exceptions in that they are typically used by the user's initialization file ``~/.unroff'' to customize unroff, rather than by programmers of unroff.
This procedure assigns value to the option name. The value must be appropriate for the option's type.
This macro is typically used to evaluate a sequence of expressions, forms, depending on the output format and macro package specified in the command line. mode is a list of two symbols, an output format and a macro package name; the wildcard `*' can be used for both elements. The forms are evaluated if the first symbol matches the value of the option -f and the second symbol matches the value of the option -m; in this case the result of the last sub-expression is returned. Otherwise the forms are ignored and #f is returned. Example:
(eval-if-mode (* html) (set-option! 'mail-address "net@cs.tu-berlin.de"))
These procedures print message and the optional args on the port returned by error-port using the primitive format. The message is prefixed by the program name, current input file name and line number, and, in case of warn, the word ``warning''. A newline is appended. quit causes the program to exit with an exit code of 1, and warn returns the empty string (and can therefore be used as the last form in event procedures).
Returns the value of the specified option.
Defines a new option with the specified name, type, and initial value. name and type are strings or symbols. There exist a number of predefined, basic option types as described in the manual page unroff(1). The initial value need not match the option's type; for example, the following expression is valid:
(define-option 'author 'string #f)
This procedure defines a new option type named name which can then be used in calls to define-option. If an option of this type is specified in the command line, the procedure pre-check is applied to the option's value (a string). In this case, if pre-check returns #f, quit is called with an error message including the string pre-msg, which should describe the expected option value format (e.g. ``a character''). If the check succeeds, the procedure converter is called with the option's current value and with the string as given in the command line. 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.
Finally, the predicate post-check is applied either to the result of converter or, if the option was set through a call to set-option!, to this procedure's argument. If the predicate returns #f, a error is signaled with an error message including post-msg as described in the previous paragraph. For example, the predefined option type ``boolean'' is defined as follows:
(define-option-type 'boolean
(lambda (x) (member x '("0" "1"))) "0 or 1"
(lambda (old new) (string=? new "1"))
boolean? "a boolean")
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. Then the specified forms are evaluated, the stream is reassigned its previous value, and the result of the last sub-expression in forms is returned. The macros recur on the primitives open-input-stream, open-output-stream, and append-output-stream, respectively.
Reads input lines using read-line-expand until either end-of-stream is reached (in this case a warning is displayed) or a line matching the string argument stop is encountered.