► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

▼ | 4 | Scribbling Documentation

4.1 | Getting Started with Documentation
4.2 | Manual Forms
4.3 | Racket
4.4 | Evaluation and Examples
4.5 | In-Source Documentation
4.6 | BNF Grammars
4.7 | Compatibility Libraries

► | 4.4 | Evaluation and Examples

4.4.1 | Legacy Evaluation

On this page:

examples
make-base-eval
make-base-eval-factory
make-eval-factory
make-log-based-eval
close-eval
scribble-eval-handler
scribble-exn->string
4.4.1`` Legacy Evaluation
interaction
interaction0
interaction/ no-prompt
interaction-eval
interaction-eval-show
racketblock+ eval
racketblock0+ eval
racketmod+ eval
def+ int
defs+ int
examples
examples*
defexamples
defexamples*
as-examples
with-eval-preserve-source-locations

top ← prev up next →

#### 4.4`` Evaluation and Examples

(require scribble/example) | package: scribble-lib

The scribble/example 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.

Added in version 1.16 of package scribble-lib.

> syntax (examples option ... datum ...)
> option |  | = |  | #:eval eval-expr
> |  | | |  | #:once
> |  | | |  | #:escape escape-id
> |  | | |  | #:label label-expr
> |  | | |  | #:hidden
> |  | | |  | #:result-only
> |  | | |  | #:no-inset
> |  | | |  | #:no-prompt
> |  | | |  | #:preserve-source-locations
> |  | | |  | #:no-result
> |  | | |  | #:lang language-name

Similar to racketinput, except that the result for each input datum is shown on the next line. The result is determined by evaluating the quoted form of the datum using the evaluator produced by eval-expr.

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.

> > procedure
> > (make-base-eval | [ | #:pretty-print? pretty-print? |
> > |  | #:lang lang] |
> > |  | input-program ...) |
> → (any/c . -> . any)
> pretty-print? : any/c = #t
> | lang |  | : |  |
> (or/c module-path?
> (list/c 'special symbol?)
> (cons/c 'begin list?))
> |  | = |  | '(begin)
> input-program : any/c

Creates an evaluator using (make-evaluator 'racket/base #:lang lang input-program ...), setting sandbox parameters to disable limits, setting the outputs to 'string, and not adding extra security guards.

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.

> > procedure
> > (make-base-eval-factory |  | mod-paths |
> > | [ | #:pretty-print? pretty-print? |
> > |  | #:lang lang]) |
> → (-> (any/c . -> . any))
> mod-paths : (listof module-path?)
> pretty-print? : any/c = #t
> | lang |  | : |  |
> (or/c module-path?
> (list/c 'special symbol?)
> (cons/c 'begin list?))
> |  | = |  | '(begin)

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 returned make-base-eval-like function is called the first time) and then attached to each evaluator that is created.

> > procedure
> > (make-eval-factory |  | mod-paths |
> > | [ | #:pretty-print? pretty-print? |
> > |  | #:lang lang]) |
> → (-> (any/c . -> . any))
> mod-paths : (listof module-path?)
> pretty-print? : any/c = #t
> | lang |  | : |  |
> (or/c module-path?
> (list/c 'special symbol?)
> (cons/c 'begin list?))
> |  | = |  | '(begin)

Like make-base-eval-factory, but each module in mod-paths is also required into the top-level environment for each generated evaluator.

> procedure (make-log-based-eval log-file mode) → (-> any/c any)
> log-file : path-string?
> mode : (or/c 'record 'replay)

Creates an evaluator (like make-base-eval) that uses a log file to either record or replay evaluations.

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.

> procedure (close-eval eval) → (one-of/c "")
> eval : (any/c . -> . any)

Shuts down an evaluator produced by make-base-eval. Use close-eval when garbage collection cannot otherwise reclaim an evaluator (e.g., because it is defined in a module body).

> parameter (scribble-eval-handler)
> → ((any/c . -> . any) any/c boolean? . -> . any)
> (scribble-eval-handler handler) → void?
> handler : ((any/c . -> . any) any/c boolean? . -> . any)

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.

> parameter (scribble-exn->string) → (-> (or/c exn? any/c) string?)
> (scribble-exn->string handler) → void?
> handler : (-> (or/c exn? any/c) string?)

A parameter that controls how exceptions are rendered by interaction. Defaults to

> (λ (e)
> (if (exn? e)
> (exn-message e)
> (format "uncaught exception: ~s" e)))

##### 4.4.1`` Legacy Evaluation

(require scribble/eval) | package: scribble-lib

The scribble/eval library provides an older interface to the functionality of scribble/example. The scribble/example library should be used, instead.

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.

> syntax (interaction maybe-options datum ...)
> maybe-options |  | = |  | maybe-eval
> |  | | |  | maybe-escape
> |  | | |  | maybe-no-errors
> maybe-eval |  | = |  |
> |  | | |  | #:eval eval-expr
> maybe-escape |  | = |  |
> |  | | |  | #:escape escape-id
> maybe-no-errors |  | = |  |
> |  | | |  | #:no-errors? no-errors?-expr

Like examples from scribble/example, except that

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

> syntax (interaction0 maybe-options datum ...)

Like interaction, but without insetting the code via nested.

Use examples with #:no-indent, instead.

> syntax (interaction/no-prompt maybe-eval maybe-escape datum)

Like interaction, but does not render each datum with a prompt.

Use examples with #:no-prompt, instead.

> syntax (interaction-eval maybe-eval datum)

Like interaction, evaluates the quoted form of datum, but returns the empty string and does not catch exceptions (so eval:error has no effect).

Use examples with #:hidden, instead.

> syntax (interaction-eval-show maybe-eval datum)

Like interaction-eval, but produces an element representing the printed form of the evaluation result.

Use examples with #:result-only, instead.

> syntax (racketblock+eval maybe-eval maybe-escape datum ...)

Combines racketblock and interaction-eval.

Use examples with #:no-result, instead.

> syntax (racketblock0+eval maybe-eval maybe-escape datum ...)

Combines racketblock0 and interaction-eval.

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

> syntax (racketmod+eval maybe-eval maybe-escape name datum ...)

Combines racketmod and interaction-eval.

Use examples with #:lang, instead.

> syntax (def+int maybe-options defn-datum expr-datum ...)

Like interaction, except the defn-datum is typeset as for racketblock (i.e., no prompt) and a line of space is inserted before the expr-datums.

> syntax (defs+int maybe-options (defn-datum ...) expr-datum ...)

Like def+int, but for multiple leading definitions.

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

> syntax (examples maybe-options datum ...)

Like interaction, but with an “Examples:” label prefixed.

Use examples from scribble/example, instead.

> syntax (examples* label-expr maybe-options datum ...)

Like examples, but using the result of label-expr in place of the default “Examples:” label.

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

> syntax (defexamples maybe-options datum ...)

Like examples, but each definition using define or define-struct among the datums is typeset without a prompt, and with line of space after it.

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

> syntax (defexamples* label-expr maybe-options datum ...)

Like defexamples, but using the result of label-expr in place of the default “Examples:” label.

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

> procedure (as-examples b) → block?
> b : block?
> (as-examples label b) → block?
> label : (or/c block? content?)
> b : block?

Adds an “examples” label to b, using either a default label or the given label.

> syntax (with-eval-preserve-source-locations expr ...)

By default, the evaluation forms provided by this module, such as interaction and examples, discard the source locations from the expressions they evaluate. Within a with-eval-preserve-source-locations form, the source locations are preserved. This can be useful for documenting forms that depend on source locations, such as Redex’s typesetting macros.

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

top ← prev up next →