4.5 Evaluation and Examples

Added in version 1.16 of package scribble-lib.

Each keyword option can be provided at most once:

• #:eval eval-expr — Specifies an evaluator, where eval-expr must produce either #f or 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 or is #f, an evaluator is created using make-base-eval. See also make-eval-factory.

• #:once — Specifies that the evaluator should be closed with close-eval after the all datums are evaluated. The #:once option is assumed if #:eval is not specified.

• #:escape escape-id — Specifies an escape identifier, as in racketblock.

• #:label label-expr — Specifies a label for the examples, which defaults to “Example:” or “Examples:” (depending on the number of datums). A #f value for label-expr suppresses the label.

• #:hidden — Specifies that the datums and results should not be typeset, but instead evaluated for a side-effect, and disables eval:error. Typically, this option is combined with #:eval to configure an evaluator.

• #:result-only — Specifies that the datum results should be typeset, but not the datums themselves, and implies #:label #f.

• #:no-result — Implies #:no-prompt and #:label #f, specifies that no results should be typeset, and disables eval:error.

• #:no-inset — Specifies that the examples should be typeset without indentation, i.e., like racketinput0 instead of racketinput.

• #:no-prompt — Specifies that each examples should be typeset without a leading prompt, i.e., like racketblock instead of racketinput. A prompt can be omitted from a specific datum by wrapping it with eval:no-prompt.

• #:preserve-source-locations — Specifies that the original source locations for each datum should be preserved for evaluation. Preserving source locations can be useful for documenting forms that depend on source locations, such as Redex’s typesetting macros.

• #:lang — Implies #:no-result prefixes the typeset datum sequence with a #lang line using language-name as the module’s language.

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.

• A datum of the form (code:line code-datum ...) evaluates each code-datum, but only the last result is used.

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

• A datum of the form (eval:error eval-datum) is treated like eval-datum, but eval-datum is expected to raise an exception, and an error is shown as the evaluation’s result.

• 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. Otherwise, content-expr is typeset as the input form (which rarely makes sense for a reader of the example).

• 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.

• A datum of the form (eval:no-prompt eval-datum ...) is treated like (code:line eval-datum ...), but no prompt is shown before the group, and a blank line is added before and after eval-datum and its result.

A datum cannot be a keyword. To specify a datum that is a keyword, wrap it with code:line.

When evaluating a datum produces an error (and datum does not have an eval:error wrapper), an exception is raised by examples.

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.

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)))

@examples[#: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.

4.5.1 Legacy Evaluation

In addition to the forms listed below, scribble/eval re-exports several functions from scribble/example: make-base-eval make-base-eval-factory, make-eval-factory, make-log-based-eval, close-eval, and scribble-eval-handler.

• the “Examples:” label is always supressed,

• exceptions raised during the evaluation of a datum are always rendered as errors, unless #:no-errors? is specified with a true value; and

• the #:once option is never implicitly used.

Changed in version 1.14 of package scribble-lib: Added #:no-errors?, eval:no-prompt, and eval:error, and changed code:line to support multiple datums.

Use examples with #:no-indent, instead.

Use examples with #:no-prompt, instead.

Use examples with #:hidden, instead.

Use examples with #:result-only, instead.

Use examples with #:no-result, instead.

Use examples with #:no-result and #:no-indent, instead.

Use examples with #:lang, instead.

Use examples with eval:no-prompt wrappers on definitions, instead.

Use examples from scribble/example, instead.

Use examples from scribble/example with the #:label option, instead.

Use examples with eval:no-prompt wrappers on definitions, instead.

Use examples with the #:label option and eval:no-prompt wrappers on definitions, instead.

Use examples with the #:preserve-source-locations option, instead.