Scribble Examples Evaluator Forms
define-examples-form
define-persistent-examples-form
6.12

Scribble Examples Evaluator Forms

Jack Firth <[email protected]>

 (require scribble-example)
  package: jack-scribble-example

This library includes forms for defining syntactic forms that render module example code in Scribble documentation.

source code: https://github.com/jackfirth/scribble-example

syntax

(define-examples-form id require-spec ...)

Binds id as a syntactic form similar to examples, but with an evaluator auto constructed for each example set. The evaluator uses racket/base as it’s language and requires each require-spec prior to evaluating the examples.

Examples:
> (define-examples-form racket-list-examples racket/list)
> (racket-list-examples
    (first '(1 2 3))
    (rest '(1 2 3)))

(compound-paragraph

 (style #f '())

 (list

  (paragraph (style #f '()) "Examples:")

  (nested-flow

   (style 'code-inset '(never-indents))

   (list

    (table

     (style

      "RktBlk"

      (list

       'tt-chars

       (css-addition '(collects #"scribble" #"racket.css"))

       (tex-addition '(collects #"scribble" #"racket.tex"))))

     (list

      (list

       (paragraph

        (style #f '(omitable))

        (list

         (element #f (element 'tt "> "))

         (cached-element

          (style

           "RktPn"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "("

          ...)

         (cached-element

          (style

           "RktSym"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "first"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "'"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "("

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "1"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "2"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "3"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          ")"

          ...)

         (cached-element

          (style

           "RktPn"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          ")"

          ...))))

      (list

       (paragraph

        (style #f '())

        (element

         (style

          "RktRes"

          (list

           'tt-chars

           (css-addition '(collects #"scribble" #"racket.css"))

           (tex-addition '(collects #"scribble" #"racket.tex"))))

         (list (cached-element #f "1" ...)))))

      (list

       (paragraph

        (style #f '(omitable))

        (list

         (element #f (element 'tt "> "))

         (cached-element

          (style

           "RktPn"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "("

          ...)

         (cached-element

          (style

           "RktSym"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "rest"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "'"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "("

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "1"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "2"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "3"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          ")"

          ...)

         (cached-element

          (style

           "RktPn"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          ")"

          ...))))

      (list

       (paragraph

        (style #f '())

        (element

         (style

          "RktRes"

          (list

           'tt-chars

           (css-addition '(collects #"scribble" #"racket.css"))

           (tex-addition '(collects #"scribble" #"racket.tex"))))

         (list

          (sized-element

           #f

           (list "'" "(" "2" (element 'tt " ") "3" ")")

           ...)))))))))))

syntax

(define-persistent-examples-form id require-spec ...)

Like define-examples-form, but instead of binding id as an example rendering form, it binds it as a syntactic rule that creates an example rendering form.

Examples:
> (define-persistent-examples-form racket-list-persistent-examples racket/list)
> (racket-list-persistent-examples a-racket-list-example-evaluator)
> (a-racket-list-example-evaluator (define foo (first '(1 2 3))))

(compound-paragraph

 (style #f '())

 (list

  (paragraph (style #f '()) "Example:")

  (nested-flow

   (style 'code-inset '(never-indents))

   (list

    (table

     (style

      "RktBlk"

      (list

       'tt-chars

       (css-addition '(collects #"scribble" #"racket.css"))

       (tex-addition '(collects #"scribble" #"racket.tex"))))

     (list

      (list

       (paragraph

        (style #f '(omitable))

        (list

         (element #f (element 'tt "> "))

         (cached-element

          (style

           "RktPn"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "("

          ...)

         (cached-element

          (style

           "RktSym"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "define"

          ...)

         (cached-element

          (style

           "RktSym"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "foo"

          ...)

         (cached-element

          (style

           "RktPn"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "("

          ...)

         (cached-element

          (style

           "RktSym"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "first"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "'"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "("

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "1"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "2"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "3"

          ...)

         (cached-element

          (style

           "RktVal"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          ")"

          ...)

         (cached-element

          (style

           "RktPn"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          ")"

          ...)

         (cached-element

          (style

           "RktPn"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          ")"

          ...))))))))))

> (a-racket-list-example-evaluator foo)

(compound-paragraph

 (style #f '())

 (list

  (paragraph (style #f '()) "Example:")

  (nested-flow

   (style 'code-inset '(never-indents))

   (list

    (table

     (style

      "RktBlk"

      (list

       'tt-chars

       (css-addition '(collects #"scribble" #"racket.css"))

       (tex-addition '(collects #"scribble" #"racket.tex"))))

     (list

      (list

       (paragraph

        (style #f '(omitable))

        (list

         (element #f (element 'tt "> "))

         (cached-element

          (style

           "RktSym"

           (list

            'tt-chars

            (css-addition '(collects #"scribble" #"racket.css"))

            (tex-addition '(collects #"scribble" #"racket.tex"))))

          "foo"

          ...))))

      (list

       (paragraph

        (style #f '())

        (element

         (style

          "RktRes"

          (list

           'tt-chars

           (css-addition '(collects #"scribble" #"racket.css"))

           (tex-addition '(collects #"scribble" #"racket.tex"))))

         (list (cached-element #f "1" ...)))))))))))

This defines example evaluators that persist state and definitions, allowing for a complex example to be split up into multiple examples seperated by prose.