224 lines
8.9 KiB
Racket
224 lines
8.9 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual "utils.rkt" (for-label scribble/racket))
|
|
|
|
@title[#:tag "scheme"]{Racket}
|
|
|
|
@defmodule*[(scribble/racket scribble/scheme)]{The
|
|
@racket[scribble/racket] library (or @racketmodname[scribble/scheme]
|
|
for backward compatibility) provides utilities for typesetting Racket
|
|
code. The @racket[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 @racket[id] to a form similar to @racket[racket] or
|
|
@racket[racketblock] for typesetting code. The form generated by
|
|
@racket[define-code] handles source-location information, escapes via
|
|
@racket[unquote] by default, preserves binding and property information,
|
|
and supports @tech{element transformers}.
|
|
|
|
The supplied @racket[typeset-expr] expression should produce a
|
|
procedure that performs the actual typesetting. This expression is
|
|
normally @racket[to-element] or @racket[to-paragraph]. The argument
|
|
supplied to @racket[typeset-expr] is normally a syntax object, but
|
|
more generally it is the result of applying @racket[d->s-expr].
|
|
|
|
The optional @racket[uncode-id] specifies the default escape from
|
|
literal code to be recognized by @racket[id], and the default for
|
|
@racket[uncode-id] is @racket[unsyntax]. A use of the @racket[id] form
|
|
can specify an alternate escape via @racket[#:escape], as in
|
|
@racket[racketblock] and @racket[racket].
|
|
|
|
The optional @racket[d->s-expr] should produce a procedure that
|
|
accepts three arguments suitable for @racket[datum->syntax]: a syntax
|
|
object or @racket[#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 @racket[typeset-expr] to typeset the
|
|
code. Normally, @racket[d->s-expr] is @racket[datum->syntax].
|
|
|
|
The @racket[stx-prop-expr] should produce a procedure for recording a
|
|
@racket['paren-shape] property when the source expression uses with
|
|
@racket[id] has such a property. The default is
|
|
@racket[syntax-property].}
|
|
|
|
@defproc[(to-paragraph [v any/c]
|
|
[#:expr? expr? any/c #f]
|
|
[#:escapes? escapes? any/c #t]
|
|
[#:color? color? any/c #t]
|
|
[#:wrap-elem wrap-elem (element? . -> . element?) (lambda (e) e)])
|
|
block?]{
|
|
|
|
Typesets an S-expression that is represented by a syntax object, where
|
|
source-location information in the syntax object controls the
|
|
generated layout. When source-location information is not available,
|
|
default spacing is used (in the same single-line style as
|
|
@racket[to-element]).
|
|
|
|
Identifiers that have @racket[for-label] bindings are typeset and
|
|
hyperlinked based on definitions declared elsewhere (via
|
|
@racket[defproc], @racket[defform], etc.). Unless @racket[escapes?]
|
|
is @racket[#f], the identifiers
|
|
@racketidfont{code:line}, @racketidfont{code:comment},
|
|
@racketidfont{code:blank}, @racketidfont{code:hilite}, and
|
|
@racketidfont{code:quote} are handled as in @racket[racketblock], as
|
|
are identifiers that start with @litchar{_}.
|
|
|
|
In addition, the given @racket[v] can contain @racket[var-id],
|
|
@racket[shaped-parens], @racket[just-context], or
|
|
@racket[literal-syntax] structures to be typeset specially (see each
|
|
structure type for details), or it can contain @racket[element]
|
|
structures that are used directly in the output.
|
|
|
|
If @racket[expr?] is true, then @racket[v] is rendered in expression
|
|
style, much like @racket[print] with the @racket[print-as-expression]
|
|
parameter set to @racket[#t]. In that case, @racket[for-label]
|
|
bindings on identifiers are ignored, since the identifiers are all
|
|
quoted in the output. Typically, @racket[expr?] is set to true for
|
|
printing result values.
|
|
|
|
If @racket[color?] is @racket[#f], then the output is typeset without
|
|
coloring.
|
|
|
|
The @racket[wrap-elem] procedure is applied to each element
|
|
constructed for the resulting block. When combined with @racket[#f]
|
|
for @racket[color?], for example, the @racket[wrap-elem] procedure can
|
|
be used to give a style to an element.}
|
|
|
|
|
|
@defproc[((to-paragraph/prefix [prefix1 any/c] [prefix any/c] [suffix any/c])
|
|
[v any/c] [#:expr? expr? any/c #f] [#:escapes? escapes? any/c #t]
|
|
[#:color? color? any/c #f]
|
|
[#:wrap-elem wrap-elem (element? . -> . element?) (lambda (e) e)])
|
|
block?]{
|
|
|
|
Like @racket[to-paragraph], but @racket[prefix1] is prefixed onto the
|
|
first line, @racket[prefix] is prefix to any subsequent line, and
|
|
@racket[suffix] is added to the end. The @racket[prefix1],
|
|
@racket[prefix], and @racket[suffix] arguments are used as
|
|
@tech{content}, except that if @racket[suffix] is a list of elements,
|
|
it is added to the end on its own line.}
|
|
|
|
|
|
@defproc[(to-element [v any/c]
|
|
[#:expr? expr? any/c #f]
|
|
[#:escapes? escapes? any/c #t]
|
|
[#:defn? defn? any/c #f]) element?]{
|
|
|
|
Like @racket[to-paragraph], except that source-location information is
|
|
mostly ignored, since the result is meant to be inlined into a
|
|
paragraph. If @racket[defn?] is true, then an identifier is styled as
|
|
a definition site.}
|
|
|
|
@defproc[(to-element/no-color [v any/c]
|
|
[#:expr? expr? any/c #f]
|
|
[#:escapes? escapes? any/c #t])
|
|
element?]{
|
|
|
|
Like @racket[to-element], but @racket[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 @racket[to-paragraph] and variants encounter a @racket[var-id]
|
|
structure, it is typeset as @racket[sym] in the variable font, like
|
|
@racket[racketvarfont]---unless the @racket[var-id] appears under
|
|
quote or quasiquote, in which case @racket[sym] is typeset as a symbol.}
|
|
|
|
|
|
@defstruct[shaped-parens ([val any/c]
|
|
[shape char?])]{
|
|
|
|
When @racket[to-paragraph] and variants encounter a
|
|
@racket[shaped-parens] structure, it is typeset like a syntax object
|
|
that has a @racket['paren-shape] property with value @racket[shape].}
|
|
|
|
|
|
@defstruct[long-boolean ([val boolean?])]{
|
|
|
|
When @racket[to-paragraph] and variants encounter a
|
|
@racket[long-boolean] structure, it is typeset as @racket[#true] or @racket[#false],
|
|
as opposed to @racket[#t] or @racket[#f].}
|
|
|
|
|
|
@defstruct[just-context ([val any/c]
|
|
[context syntax?])]{
|
|
|
|
When @racket[to-paragraph] and variants encounter a
|
|
@racket[just-context] structure, it is typeset using the
|
|
source-location information of @racket[val] just the lexical context
|
|
of @racket[ctx].}
|
|
|
|
|
|
@defstruct[literal-syntax ([stx any/c])]{
|
|
|
|
When @racket[to-paragraph] and variants encounter a
|
|
@racket[literal-syntax] structure, it is typeset as the string form of
|
|
@racket[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 @racket[for-syntax]; returns @racket[#t] if @racket[v] is an
|
|
@tech{element transformer} created by
|
|
@racket[make-element-id-transformer], @racket[#f] otherwise.}
|
|
|
|
|
|
@defproc[(make-element-id-transformer [proc (syntax? . -> . syntax?)])
|
|
element-id-transformer?]{
|
|
|
|
Provided @racket[for-syntax]; creates an @deftech{element
|
|
transformer}. When an identifier has a transformer binding to an
|
|
@tech{element transformer}, then forms generated by
|
|
@racket[define-code] (including @racket[racket] and
|
|
@racket[racketblock]) typeset the identifier by applying the
|
|
@racket[proc] to the identifier. The result must be an expression
|
|
whose value, typically an @racket[element], is passed on to functions
|
|
like @racket[to-paragraph] .}
|
|
|
|
@defproc[(variable-id? [v any/c]) boolean?]{
|
|
|
|
Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an
|
|
@tech{element transformer} created by @racket[make-variable-id],
|
|
@racket[#f] otherwise.}
|
|
|
|
|
|
@defproc[(make-variable-id [sym (or/c symbol? identifier?)])
|
|
variable-id?]{
|
|
|
|
Provided @racket[for-syntax]; like @racket[make-element-id-transformer] for
|
|
a transformer that produces @racket[sym] typeset as a variable (like
|
|
@racket[racketvarfont])---unless it appears under quote or quasiquote,
|
|
in which case @racket[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 Racket programs, results, and I/O.}
|