181 lines
6.8 KiB
Racket
181 lines
6.8 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual
|
|
"utils.ss"
|
|
(for-label scribble/scheme))
|
|
|
|
@title[#:tag "scheme"]{Scheme}
|
|
|
|
@defmodule[scribble/scheme]{The @scheme[scribble/scheme] library
|
|
provides utilities for typesetting Scheme code. The
|
|
@scheme[scribble/manual] forms provide a higher-level interface.}
|
|
|
|
@defform*[[(define-code id typeset-expr)
|
|
(define-code id typeset-expr uncode-id)
|
|
(define-code id typeset-expr uncode-id d->s-expr)
|
|
(define-code id typeset-expr uncode-id d->s-expr stx-prop-expr)]]{
|
|
|
|
Binds @scheme[id] to a form similar to @scheme[scheme] or
|
|
@scheme[schemeblock] for typesetting code. The form generated by
|
|
@scheme[define-code] handles source-location information, escapes via
|
|
@scheme[unquote], preservation of binding and property information,
|
|
and @tech{element transformers}.
|
|
|
|
The supplied @scheme[typeset-expr] expression should produce a
|
|
procedure that performs the actual typesetting. This expression is
|
|
normally @scheme[to-element] or @scheme[to-paragraph]. The argument
|
|
supplied to @scheme[typeset-expr] is normally a syntax object, but
|
|
more generally it is the result of applying @scheme[d->s-expr].
|
|
|
|
The optional @scheme[uncode-id] specifies the escape from literal code
|
|
to be recognized by @scheme[id]. The default is @scheme[unsyntax].
|
|
|
|
The optional @scheme[d->s-expr] should produce a procedure that
|
|
accepts three arguments suitable for @scheme[datum->syntax]: a syntax
|
|
object or @scheme[#f], an arbitrary value, and a vector for a source
|
|
location. The result should record as much or as little of the
|
|
argument information as needed by @scheme[typeset-expr] to typeset the
|
|
code. Normally, @scheme[d->s-expr] is @scheme[datum->syntax].
|
|
|
|
The @scheme[stx-prop-expr] should produce a procedure for recording a
|
|
@scheme['paren-shape] property when the source expression uses with
|
|
@scheme[id] has such a property. The default is
|
|
@scheme[syntax-property].}
|
|
|
|
@defproc[(to-paragraph [v any/c]) block?]{
|
|
|
|
Typesets an S-expression that is represented by a syntax object, where
|
|
source-location information in the syntax object controls the
|
|
generated layout.
|
|
|
|
Identifiers that have @scheme[for-label] bindings are typeset and
|
|
hyperlinked based on definitions declared elsewhere (via
|
|
@scheme[defproc], @scheme[defform], etc.). The identifiers
|
|
@schemeidfont{code:line}, @schemeidfont{code:comment}, and
|
|
@schemeidfont{code:blank} are handled as in @scheme[schemeblock], as
|
|
are identifiers that start with @litchar{_}.
|
|
|
|
In addition, the given @scheme[v] can contain @scheme[var-id],
|
|
@scheme[shaped-parens], @scheme[just-context], or
|
|
@scheme[literal-syntax] structures to be typeset specially (see each
|
|
structure type for details), or it can contain @scheme[element]
|
|
structures that are used directly in the output.}
|
|
|
|
|
|
@defproc[((to-paragraph/prefix [prefix1 any/c] [prefix any/c] [suffix any/c])
|
|
[v any/c])
|
|
block?]{
|
|
|
|
Like @scheme[to-paragraph], but @scheme[prefix1] is prefixed onto the
|
|
first line, @scheme[prefix] is prefix to any subsequent line, and
|
|
@scheme[suffix] is added to the end. The @scheme[prefix1],
|
|
@scheme[prefix], and @scheme[suffix] arguments are used as
|
|
@tech{content}, except that if @scheme[suffix] is a list of elements,
|
|
it is added to the end on its own line.}
|
|
|
|
|
|
@defproc[(to-element [v any/c]) element?]{
|
|
|
|
Like @scheme[to-paragraph], except that source-location information is
|
|
mostly ignored, since the result is meant to be inlined into a
|
|
paragraph.}
|
|
|
|
@defproc[(to-element/no-color [v any/c]) element?]{
|
|
|
|
Like @scheme[to-element], but @scheme[for-syntax] bindings are
|
|
ignored, and the generated text is uncolored. This variant is
|
|
typically used to typeset results.}
|
|
|
|
|
|
@defstruct[var-id ([sym (or/c symbol? identifier?)])]{
|
|
|
|
When @scheme[to-paragraph] and variants encounter a @scheme[var-id]
|
|
structure, it is typeset as @scheme[sym] in the variable font, like
|
|
@scheme[schemevarfont]---unless the @scheme[var-id] appears under
|
|
quote or quasiquote, in which case @scheme[sym] is typeset as a symbol.}
|
|
|
|
|
|
@defstruct[shaped-parens ([val any/c]
|
|
[shape char?])]{
|
|
|
|
When @scheme[to-paragraph] and variants encounter a
|
|
@scheme[shaped-parens] structure, it is typeset like a syntax object
|
|
that has a @scheme['paren-shape] property with value @scheme[shape].}
|
|
|
|
|
|
@defstruct[just-context ([val any/c]
|
|
[context syntax?])]{
|
|
|
|
When @scheme[to-paragraph] and variants encounter a
|
|
@scheme[just-context] structure, it is typeset using the
|
|
source-location information of @scheme[val] just the lexical context
|
|
of @scheme[ctx].}
|
|
|
|
|
|
@defstruct[literal-syntax ([stx any/c])]{
|
|
|
|
When @scheme[to-paragraph] and variants encounter a
|
|
@scheme[literal-syntax] structure, it is typeset as the string form of
|
|
@scheme[stx]. This can be used to typeset a syntax-object value in the
|
|
way that the default printer would represent the value.}
|
|
|
|
|
|
@defproc[(element-id-transformer? [v any/c]) boolean?]{
|
|
|
|
Provided @scheme[for-syntax]; returns @scheme[#t] if @scheme[v] is an
|
|
@tech{element transformer} created by
|
|
@scheme[make-element-id-transformer], @scheme[#f] otherwise.}
|
|
|
|
|
|
@defproc[(make-element-id-transformer [proc (syntax? . -> . syntax?)])
|
|
element-id-transformer?]{
|
|
|
|
Provided @scheme[for-syntax]; creates an @deftech{element
|
|
transformer}. When an identifier has a transformer binding to an
|
|
@tech{element transformer}, then forms generated by
|
|
@scheme[define-code] (including @scheme[scheme] and
|
|
@scheme[schemeblock]) typeset the identifier by applying the
|
|
@scheme[proc] to the identifier. The result must be an expression
|
|
whose value, typically an @scheme[element], is passed on to functions
|
|
like @scheme[to-paragraph] .}
|
|
|
|
@defproc[(variable-id? [v any/c]) boolean?]{
|
|
|
|
Provided @scheme[for-syntax]; returns @scheme[#t] if @scheme[v] is an
|
|
@tech{element transformer} created by @scheme[make-variable-id],
|
|
@scheme[#f] otherwise.}
|
|
|
|
|
|
@defproc[(make-variable-id [sym (or/c symbol? identifier?)])
|
|
variable-id?]{
|
|
|
|
Provided @scheme[for-syntax]; like @scheme[make-element-id-transformer] for
|
|
a transformer that produces @scheme[sym] typeset as a variable (like
|
|
@scheme[schemevarfont])---unless it appears under quote or quasiquote,
|
|
in which case @scheme[sym] is typeset as a symbol.}
|
|
|
|
@deftogether[(
|
|
@defthing[output-color style?]
|
|
@defthing[input-color style?]
|
|
@defthing[input-background-color style?]
|
|
@defthing[no-color style?]
|
|
@defthing[reader-color style?]
|
|
@defthing[result-color style?]
|
|
@defthing[keyword-color style?]
|
|
@defthing[comment-color style?]
|
|
@defthing[paren-color style?]
|
|
@defthing[meta-color style?]
|
|
@defthing[value-color style?]
|
|
@defthing[symbol-color style?]
|
|
@defthing[variable-color style?]
|
|
@defthing[opt-color style?]
|
|
@defthing[error-color style?]
|
|
@defthing[syntax-link-color style?]
|
|
@defthing[value-link-color style?]
|
|
@defthing[module-color style?]
|
|
@defthing[module-link-color style?]
|
|
@defthing[block-color style?]
|
|
@defthing[highlighted-color style?]
|
|
)]{
|
|
|
|
Styles that are used for coloring Scheme programs, results, and I/O.}
|