On this page:
interaction
interaction0
interaction/  no-prompt
interaction-eval
interaction-eval-show
racketblock+  eval
racketblock0+  eval
racketmod+  eval
def+  int
defs+  int
examples
defexamples
make-base-eval
make-base-eval-factory
make-eval-factory
close-eval
scribble-eval-handler
scribble-exn->string
with-eval-preserve-source-locations

4.5 Evaluation and Examples

 (require scribble/eval) package: scribble-lib
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.

syntax

(interaction maybe-eval maybe-escape datum ...)

 
maybe-eval = 
  | #:eval eval-expr
     
maybe-escape = 
  | #:escape escape-id
Like 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, 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 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:

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.

syntax

(interaction0 maybe-eval maybe-escape datum ...)

Like interaction, but without insetting the code via nested.

syntax

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

Like interaction, but does not render the output with a prompt.

syntax

(interaction-eval maybe-eval maybe-escape datum)

Like interaction, evaluates the quoted form of datum, but returns the empty string and does not catch errors.

syntax

(interaction-eval-show maybe-eval maybe-escape datum)

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

syntax

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

syntax

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

syntax

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

syntax

(def+int maybe-eval maybe-escape 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-eval maybe-escape (defn-datum ...) expr-datum ...)

Like def+int, but for multiple leading definitions.

syntax

(examples maybe-eval maybe-escape datum ...)

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

syntax

(defexamples maybe-eval maybe-escape 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.

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

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

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.