4.5 Evaluation and Examples

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 make-eval-factory.

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 to-element/no-color.

Certain patterns in datum are treated specially:

• A datum of the form (code:line code-datum (code:comment comment-datum ...)) is treated as code-datum for evaluation.

• Other uses of code:comment, code:contract, and code:blank are stripped from each datum before evaluation.

• A datum of the form (eval:alts show-datum eval-datum) is treated as show-datum for typesetting and eval-datum for evaluation.

• A datum of the form (eval:check eval-datum expect-datum) is treated like eval-datum, but check-datum is also evaluated, and an error is raised if they are not equal?.

• A datum of the form (eval:result content-expr out-expr err-expr) involves no sandboxed evaluation; instead, the content result of content-expr is used as the typeset form of the result, out-expr is treated as output printed by the expression, and err-expr is error output printed by the expression. The out-expr and/or err-expr can be omitted, in which case they default to empty strings.

  Normally, eval:result is used in the second part of an eval:alts combination.

• A datum of the form (eval:results content-list-expr out-expr err-expr) is treated like an eval:result form, except that content-list-expr should produce a list of content for multiple results of evaluation. As with eval:result, out-expr and err-expr are optional.

As an example,

#lang scribble/manual

@(require racket/sandbox

scribble/eval)

@(define my-evaluator

(parameterize ([sandbox-output 'string]

[sandbox-error-output 'string])

(make-evaluator 'typed/racket/base)))

@interaction[#:eval my-evaluator

(: my-sqr (Real -> Real))

(define (my-sqr x)

(* x x))

(my-sqr 42)]

uses an evaluator whose language is typed/racket/base.

If pretty-print? is true, the sandbox’s printer is set to pretty-print-handler. In that case, values that are convertible in the sense of convertible? are printed using write-special, except that values that are serializable in the sense of serializable? are serialized for tranfers from inside the sandbox to outside (which can avoid pulling code and support from the sandboxed environment into the document-rendering environment).

Changed in version 1.6 of package scribble-lib: Changed treatment of convertible values that are serializable.

If mode is 'record, the evaluator records every interaction to log-file, replacing log-file if it already exists. The result of each interaction must be serializable.

If mode is 'replay, the evaluator uses the contents of log-file instead of actually performing evaluatings. For each interaction, it compares the term to evaluate against the next interaction recorded in log-file. If the term matches, the stored result is returned; if not, the evaluator raises an error indicating that it is out of sync with log-file.

Use make-log-based-eval to document libraries when the embedded examples rely on external features that may not be present or appropriately configured on all machines.

Added in version 1.12 of package scribble-lib.