Scribble Examples Evaluator Forms
| (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)))
(table
(style
"RktBlk"
(list
'tt-chars
(css-addition '(collects #"scribble" #"racket.css"))
(tex-addition '(collects #"scribble" #"racket.tex"))))
(list
(list (paragraph (style #f '()) "Examples:"))
(list
(nested-flow
(style 'code-inset '())
(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))))
(table
(style
"RktBlk"
(list
'tt-chars
(css-addition '(collects #"scribble" #"racket.css"))
(tex-addition '(collects #"scribble" #"racket.tex"))))
(list
(list (paragraph (style #f '()) "Example:"))
(list
(nested-flow
(style 'code-inset '())
(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)
(table
(style
"RktBlk"
(list
'tt-chars
(css-addition '(collects #"scribble" #"racket.css"))
(tex-addition '(collects #"scribble" #"racket.tex"))))
(list
(list (paragraph (style #f '()) "Example:"))
(list
(nested-flow
(style 'code-inset '())
(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.