4.5 Evaluation and Examples
The scribble/eval library provides
utilities for evaluating code at document-build time and incorporating
the results in the document, especially to show example uses of
defined procedures and syntax.
|(interaction maybe-eval maybe-escape datum ...)|
|maybe-eval|| ||=|| |
| || ||||| ||#:eval eval-expr|
| || || || || |
|maybe-escape|| ||=|| |
| || ||||| ||#:escape escape-id|
, except that the result for each input
is shown on the next line. The result is determined by
evaluating the quote
d form of the datum
evaluator produced by eval-expr
, if provided.
The eval-expr must produce a sandbox evaluator via
make-evaluator or make-module-evaluator with the
sandbox-output and sandbox-error-output parameters
set to 'string. If eval-expr is not provided, an
evaluator is created using make-base-eval. See also
If the value of current-print in the sandbox is changed from
its default value, or if print-as-expression in the sandbox
is set to #f, then each evaluation result is formatted to a
port by applying (current-print) to the value; the output
port is set to a pipe that supports specials in the sense of
write-special, and non-character values written to the port
are used as content. Otherwise, when the default
current-print is in place, result values are typeset using
Uses of code:comment and code:blank are
stipped from each datum before evaluation.
If a datum has the form (eval:alts show-datum eval-datum), then show-datum is
typeset, while eval-datum is evaluated.
If a datum has the form
(eval:check eval-datum expect-datum), then both eval-datum and check-datum
are evaluated, and an error is raised if they are not equal?.
As an example,
uses an evaluator whose language is typed/racket/base.
, evaluates the quote
d form of
, but returns the empty string.
, but produces an element representing
the printed form of the evaluation result.
|(def+int maybe-eval maybe-escape defn-datum expr-datum ...)|
, except the defn-datum
typeset as for racketblock
(i.e., no prompt) and a line of
space is inserted before the expr-datum
|(defs+int maybe-eval maybe-escape (defn-datum ...) expr-datum ...)|
, but for multiple leading definitions.
|(examples maybe-eval maybe-escape datum ...)|
, but with an “Examples:” label prefixed.
, but each definition using define
among the datum
s is typeset without a
prompt, and with line of space after it.
Creates an evaluator using (make-evaluator 'racket/base)
setting sandbox parameters to disable limits, setting the outputs to
, and not adding extra security guards.
If pretty-print? is true, the sandbox’s printer is set to
Produces a function that is like make-base-eval
, except that
each module in mod-paths
is attached to the evaluator’s
namespace. The modules are loaded and instantiated once (when the
-like function is called the first
time) and then attached to each evaluator that is created.
, but each module in mod-paths
also required into the top-level environment for each generated evaluator.
Shuts down an evaluator produced by make-base-eval
when garbage collection cannot otherwise reclaim
an evaluator (e.g., because it is defined in a module body).
A parameter that serves as a hook for evaluation. The evaluator to use
is supplied as the first argument to the parameter’s value, and the
second argument is the form to evaluate. The last argument is
#t if exceptions are being captured (to display exception
results), #f otherwise.