10 Scheme

(require scribble/scheme)

The scribble/scheme library provides utilities for typesetting Scheme code. The scribble/manual forms provide a higher-level interface.

(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 id to a form similar to scheme or schemeblock for typesetting code. The form generated by define-code handles source-location information, escapes via unquote, preservation of binding and property information, and element transformers.

The supplied typeset-expr expression should produce a procedure that performs the actual typesetting. This expression is normally to-element or to-paragraph. The argument supplied to typeset-expr is normally a syntax object, but more generally it is the result of applying d->s-expr.

The optional uncode-id specifies the escape from literal code to be recognized by id. The default is unsyntax.

The optional d->s-expr should produce a procedure that accepts three arguments suitable for datum->syntax: a syntax object or #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 typeset-expr to typeset the code. Normally, d->s-expr is datum->syntax.

The stx-prop-expr should produce a procedure for recording a 'paren-shape property when the source expression uses with id has such a property. The default is syntax-property.

(to-paragraph v) → block?

v : any/c

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 for-label bindings are typeset and hyperlinked based on definitions declared elsewhere (via defproc, defform, etc.). The identifiers code:line, code:comment, and code:blank are handled as in schemeblock, as are identifiers that start with _.

In addition, the given v can contain var-id, shaped-parens, just-context, or literal-syntax structures to be typeset specially (see each structure type for details), or it can contain element structures that are used directly in the output.

((to-paragraph/prefix   prefix1             prefix             suffix)             v)   →   block?

prefix1 : any/c

prefix : any/c

suffix : any/c

v : any/c

Like to-paragraph, but prefix1 is prefixed onto the first line, prefix is prefix to any subsequent line, and suffix is added to the end. The prefix1, prefix, and suffix arguments are used as elements, except that if suffix is a list of elements, it is added to the end on its own line.

(to-element v) → element?

v : any/c

Like to-paragraph, except that source-location information is mostly ignored, since the result is meant to be inlined into a paragraph.

(to-element/no-color v) → element?

v : any/c

Like to-element, but for-syntax bindings are ignored, and the generated text is uncolored. This variant is typically used to typeset results.

(struct var-id (sym))

sym : (or/c symbol? identifier?)

When to-paragraph and variants encounter a var-id structure, it is typeset as sym in the variable font, like schemevarfont – unless the var-id appears under quote or quasiquote, in which case sym is typeset as a symbol.

(struct shaped-parens (val shape))

val : any/c

shape : char?

When to-paragraph and variants encounter a shaped-parens structure, it is typeset like a syntax object that has a 'paren-shape property with value shape.

(struct just-context (val context))

val : any/c

context : syntax?

When to-paragraph and variants encounter a just-context structure, it is typeset using the source-location information of val just the lexical context of ctx.

(struct literal-syntax (stx))

stx : any/c

When to-paragraph and variants encounter a literal-syntax structure, it is typeset as the string form of stx. This can be used to typeset a syntax-object value in the way that the default printer would represent the value.

(element-id-transformer? v) → boolean?

v : any/c

Provided for-syntax; returns #t if v is an element transformer created by make-element-id-transformer, #f otherwise.

(make-element-id-transformer proc) → element-id-transformer?

proc : (syntax? . -> . syntax?)

Provided for-syntax; creates an element transformer. When an identifier has a transformer binding to an element transformer, then forms generated by define-code (including scheme and schemeblock) typeset the identifier by applying the proc to the identifier. The result must be an expression whose value, typically an element, is passed on to functions like to-paragraph .

(variable-id? v) → boolean?

v : any/c

Provided for-syntax; returns #t if v is an element transformer created by make-variable-id, #f otherwise.

(make-variable-id sym) → variable-id?

sym : (or/c symbol? identifier?)

Provided for-syntax; like element-id-transformer for a transformer that produces sym typeset as a variable (like schemevarfont) – unless it appears under quote or quasiquote, in which case sym is typeset as a symbol.