8.  Calling the Parser

      The following Scheme primitives are used by event procedures for requests, macros, and escape characters to parse their arguments or to parse lines of text that have been read from an input source. Each of the primitives can be invoked with zero or more arguments of type string, symbol, or character. The arguments are concatenated to form a Scheme string which is then passed to the parser, and the result is returned as a new string.

(parse . args)

      This primitive feeds its arguments to the ``escape parsing'' pass as described in the previous section. It scans its arguments for special characters and escape sequences and replaces them by the corresponding event values (or results), and it executes character translations.

(translate . args)

      Like parse above, except that only output character translations (defined by calls to defchar) are executed.

(parse-expand . args)

      This primitive applies the ``expansion parsing'' phase (as described in the previous section) to its arguments. Compared to parse, parse-expand is only used rarely, as input lines read in the normal way are scanned for string and number register references anyway. The sample implementation supplied by unroff for the requests ``.ds'', ``.as'', and '\*' makes use of this primitive to rescan the contents of user-defined strings upon interpolation.

(parse-line . args)

      This primitive parses an entire input line, which may contain a call to a request or macro, as described in the previous section. The line made up by the primitive's arguments is treated exactly as it if were read from an input file, although it need not have a terminating newline. Two places where this primitive is required are the handler for the request ``.so'' and the code that expands user-defined macros.

(parse-copy-mode . args)

      The primitive parse-copy-mode parses its arguments in a manner similar to troff ``copy mode''. In this mode, escape sequences beginning with '\$' are dealt with (by calling their event procedures), the sequence `\\' is replaced by a single `\', and each occurrence of `\.' is replaced by a period. Macro bodies are parsed in copy mode during macro definition and again when the macros are expanded.

      The sample implementation of user-defined macros supplied by unroff defines suitable event handlers for the usual

\$1  \$2 ...

\$0   \$*   \$@

(parse-expression expr fail scale)
(parse-expression-rest expr fail scale)

      These primitives evaluate the numeric expression specified by the string argument expr and return the result as an exact number. The usual troff expression syntax, operators, and scale indicators are supported. If an error occurs during evaluation (for instance, if expr is not a syntactically valid expression), a warning message is displayed and fail (which may be an arbitrary Scheme object) is returned. The character argument scale is the default scale indicator, for example `#\m', or `#\u' for basic units.

      The primitive parse-expression-rest is identical to parse-expression, except that its return value is a cons cell whose car consists of the result of the evaluation and whose cdr is the rest of expr starting at the character position where parsing of the expression stopped. In other words, the primitive evaluates the portion of expr that constitutes a valid expression, and it returns the result and whatever is left over. Warning messages are also suppressed, except if an overflow occurs during evaluation. parse-expression-rest is useful for tasks like parsing the argument of the escape sequences `\l' and `\L' where an expression is immediately followed by another character. Examples:

(parse-expression "(2+8)/5" 0 #\u)     =>  2
(parse-expression "foo" #f #\u)        =>  #f; prints warning

(parse-expression-rest "1+1" #f #\u)         =>  (2 . "")
(parse-expression-rest "(2+8)/5foo" 0 #\u)   =>  (2 . "foo")
(parse-expression-rest "15\&-" 0 #\u)        =>  (15 . "\&-")

(char-expression-delimiter? char)

      Returns #t if the character argument char is valid as the first character of a numeric expression (e.g. a digit), otherwise #f.

(set-scaling! scale factor divisor)
(get-scaling scale)

      These primitives set and read the scale factor and divisor for the specified scale indicator. scale is the scale indicator (a character); factor and divisor are integers. get-scaling returns the scaling for the specified scale indicator as a pair of integers. The factors and divisors are initially set to 1 for all scale indicators; they must be assigned useful values by each back-end.