3.4 Evaluation and Examples🔗ℹ

The forms to evaluate are grouped into chunks, where extra space is rendered between different chunks. When repls are provided directly to examples after any chunkss, they are implicitly grouped into a final ~repl chunk.

The keyword for a chunk determines its rendering:

• ~defn: Each form to evaluate and its results are shown without a leading > prompt. Output and error output are also collected and rendered in between the input form and result. As the keyword suggests, this kind of chunk makes the most sense for definitions, which have no result.

• ~repl: Each form to evaluate is shown with a leading > prompt, but no prompt is shown for the evaluation’s output or result.

• ~result: Only output and the result of evaluation are shown, and the form that was evaluated is not itself rendered.

• ~hidden: Neither the form to evaluate nor its output and result are show. Forms are evaluated only for their side effects.

• ~version_at_least: Splices the contained chunks as long as the rutime system version is at least version_string, omits the chunks otherwise.

Each repl within a chunk has one of several forms:

• A plain form: The form both typeset and evaluated. Evaluation must not raise an (uncaught) exception.

• Using ~error: The form both typeset and evaluated, and it must raise an (uncaught) exception. The exception message is printed as error output.

• Using ~check: Like a plain form, but expect_form is also evaluated, and the two results must be ==.

• Using ~fake: The typeset_form is rendered, but not evaluated. The result_form is not typeset, but it is evaluated for its output and result to be rendered.

• A ~blank: No form is typeset or evaluated. Instead, an empty line is rendered.

By default, a fresh evaluator is created with make_rhombus_eval to evaluate the expressions, and the evaluator is closed afterward. Supply the ~eval option to use a different evaluator.

The result of a ~label option’s expression is used to label the examples. When the result is #false, the default, then no label is shown.

The ~indent option can provide an expression to produce a nonnegative exact integer. That number of additional spaces is used to indent the example. The default is 0.

The ~spacer_info_box option can provide a box the hold spacer binding information for linking methods after a .. By default, an box specific to the evaluator is created or found (if the ~eval option is present) in a weak table.

The ~escape option selects an alternate escape for rendering expression—needed, for example, if the example itself involves a #, escape.

If attach is a true value, then a lang module instance is attached to the namespace where the enclosing document is run, and the new evaluator uses that instance in a fresh top-level namespace. Using an attached instance can be much faster than freshly loading a language in an evaluator namespace, but any state in the language ends up shared among evaluators.