scheme.scrbl (9124B)
1 #lang scribble/doc 2 @(require scribble/manual "utils.rkt" (for-label scribble/racket)) 3 4 @title[#:tag "scheme"]{Racket} 5 6 @defmodule*[(scribble/racket scribble/scheme)]{The 7 @racket[scribble/racket] library (or @racketmodname[scribble/scheme] 8 for backward compatibility) provides utilities for typesetting Racket 9 code. The @racket[scribble/manual] forms provide a higher-level 10 interface.} 11 12 @defform*[[(define-code id typeset-expr) 13 (define-code id typeset-expr uncode-id) 14 (define-code id typeset-expr uncode-id d->s-expr) 15 (define-code id typeset-expr uncode-id d->s-expr stx-prop-expr)]]{ 16 17 Binds @racket[id] to a form similar to @racket[racket] or 18 @racket[racketblock] for typesetting code. The form generated by 19 @racket[define-code] handles source-location information, escapes via 20 @racket[unquote] by default, preserves binding and property information, 21 and supports @tech{element transformers}. 22 23 The supplied @racket[typeset-expr] expression should produce a 24 procedure that performs the actual typesetting. This expression is 25 normally @racket[to-element] or @racket[to-paragraph]. The argument 26 supplied to @racket[typeset-expr] is normally a syntax object, but 27 more generally it is the result of applying @racket[d->s-expr]. 28 29 The optional @racket[uncode-id] specifies the default escape from 30 literal code to be recognized by @racket[id], and the default for 31 @racket[uncode-id] is @racket[unsyntax]. A use of the @racket[id] form 32 can specify an alternate escape via @racket[#:escape], as in 33 @racket[racketblock] and @racket[racket]. 34 35 The optional @racket[d->s-expr] should produce a procedure that 36 accepts three arguments suitable for @racket[datum->syntax]: a syntax 37 object or @racket[#f], an arbitrary value, and a vector for a source 38 location. The result should record as much or as little of the 39 argument information as needed by @racket[typeset-expr] to typeset the 40 code. Normally, @racket[d->s-expr] is @racket[datum->syntax]. 41 42 The @racket[stx-prop-expr] should produce a procedure for recording a 43 @racket['paren-shape] property when the source expression uses with 44 @racket[id] has such a property. The default is 45 @racket[syntax-property].} 46 47 @defproc[(to-paragraph [v any/c] 48 [#:expr? expr? any/c #f] 49 [#:escapes? escapes? any/c #t] 50 [#:color? color? any/c #t] 51 [#:wrap-elem wrap-elem (element? . -> . element?) (lambda (e) e)]) 52 block?]{ 53 54 Typesets an S-expression that is represented by a syntax object, where 55 source-location information in the syntax object controls the 56 generated layout. When source-location information is not available, 57 default spacing is used (in the same single-line style as 58 @racket[to-element]). 59 60 Identifiers that have @racket[for-label] bindings are typeset and 61 hyperlinked based on definitions declared elsewhere (via 62 @racket[defproc], @racket[defform], etc.). Unless @racket[escapes?] 63 is @racket[#f], the identifiers 64 @racketidfont{code:line}, @racketidfont{code:comment}, 65 @racketidfont{code:blank}, @racketidfont{code:hilite}, and 66 @racketidfont{code:quote} are handled as in @racket[racketblock], as 67 are identifiers that start with @litchar{_}. 68 69 In addition, the given @racket[v] can contain @racket[var-id], 70 @racket[shaped-parens], @racket[just-context], or 71 @racket[literal-syntax] structures to be typeset specially (see each 72 structure type for details), or it can contain @racket[element] 73 structures that are used directly in the output. 74 75 If @racket[expr?] is true, then @racket[v] is rendered in expression 76 style, much like @racket[print] with the @racket[print-as-expression] 77 parameter set to @racket[#t]. In that case, @racket[for-label] 78 bindings on identifiers are ignored, since the identifiers are all 79 quoted in the output. Typically, @racket[expr?] is set to true for 80 printing result values. 81 82 If @racket[color?] is @racket[#f], then the output is typeset without 83 coloring. 84 85 The @racket[wrap-elem] procedure is applied to each element 86 constructed for the resulting block. When combined with @racket[#f] 87 for @racket[color?], for example, the @racket[wrap-elem] procedure can 88 be used to give a style to an element.} 89 90 91 @defproc[((to-paragraph/prefix [prefix1 any/c] [prefix any/c] [suffix any/c]) 92 [v any/c] [#:expr? expr? any/c #f] [#:escapes? escapes? any/c #t] 93 [#:color? color? any/c #f] 94 [#:wrap-elem wrap-elem (element? . -> . element?) (lambda (e) e)]) 95 block?]{ 96 97 Like @racket[to-paragraph], but @racket[prefix1] is prefixed onto the 98 first line, @racket[prefix] is prefix to any subsequent line, and 99 @racket[suffix] is added to the end. The @racket[prefix1], 100 @racket[prefix], and @racket[suffix] arguments are used as 101 @tech{content}, except that if @racket[suffix] is a list of elements, 102 it is added to the end on its own line.} 103 104 105 @defproc[(to-element [v any/c] 106 [#:expr? expr? any/c #f] 107 [#:escapes? escapes? any/c #t] 108 [#:defn? defn? any/c #f]) element?]{ 109 110 Like @racket[to-paragraph], except that source-location information is 111 mostly ignored, since the result is meant to be inlined into a 112 paragraph. If @racket[defn?] is true, then an identifier is styled as 113 a definition site.} 114 115 @defproc[(to-element/no-color [v any/c] 116 [#:expr? expr? any/c #f] 117 [#:escapes? escapes? any/c #t]) 118 element?]{ 119 120 Like @racket[to-element], but @racket[for-syntax] bindings are 121 ignored, and the generated text is uncolored. This variant is 122 typically used to typeset results.} 123 124 125 @defstruct[var-id ([sym (or/c symbol? identifier?)])]{ 126 127 When @racket[to-paragraph] and variants encounter a @racket[var-id] 128 structure, it is typeset as @racket[sym] in the variable font, like 129 @racket[racketvarfont]---unless the @racket[var-id] appears under 130 quote or quasiquote, in which case @racket[sym] is typeset as a symbol.} 131 132 133 @defstruct[shaped-parens ([val any/c] 134 [shape char?])]{ 135 136 When @racket[to-paragraph] and variants encounter a 137 @racket[shaped-parens] structure, it is typeset like a syntax object 138 that has a @racket['paren-shape] property with value @racket[shape].} 139 140 141 @defstruct[long-boolean ([val boolean?])]{ 142 143 When @racket[to-paragraph] and variants encounter a 144 @racket[long-boolean] structure, it is typeset as @racket[#true] or @racket[#false], 145 as opposed to @racket[#t] or @racket[#f].} 146 147 148 @defstruct[just-context ([val any/c] 149 [context syntax?])]{ 150 151 When @racket[to-paragraph] and variants encounter a 152 @racket[just-context] structure, it is typeset using the 153 source-location information of @racket[val] just the lexical context 154 of @racket[ctx].} 155 156 157 @defstruct[literal-syntax ([stx any/c])]{ 158 159 When @racket[to-paragraph] and variants encounter a 160 @racket[literal-syntax] structure, it is typeset as the string form of 161 @racket[stx]. This can be used to typeset a syntax-object value in the 162 way that the default printer would represent the value.} 163 164 165 @defproc[(element-id-transformer? [v any/c]) boolean?]{ 166 167 Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an 168 @tech{element transformer} created by 169 @racket[make-element-id-transformer], @racket[#f] otherwise.} 170 171 172 @defproc[(make-element-id-transformer [proc (syntax? . -> . syntax?)]) 173 element-id-transformer?]{ 174 175 Provided @racket[for-syntax]; creates an @deftech{element 176 transformer}. When an identifier has a transformer binding to an 177 @tech{element transformer}, then forms generated by 178 @racket[define-code] (including @racket[racket] and 179 @racket[racketblock]) typeset the identifier by applying the 180 @racket[proc] to the identifier. The result must be an expression 181 whose value, typically an @racket[element], is passed on to functions 182 like @racket[to-paragraph] .} 183 184 @defproc[(variable-id? [v any/c]) boolean?]{ 185 186 Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an 187 @tech{element transformer} created by @racket[make-variable-id], 188 @racket[#f] otherwise.} 189 190 191 @defproc[(make-variable-id [sym (or/c symbol? identifier?)]) 192 variable-id?]{ 193 194 Provided @racket[for-syntax]; like @racket[make-element-id-transformer] for 195 a transformer that produces @racket[sym] typeset as a variable (like 196 @racket[racketvarfont])---unless it appears under quote or quasiquote, 197 in which case @racket[sym] is typeset as a symbol.} 198 199 @deftogether[( 200 @defthing[output-color style?] 201 @defthing[input-color style?] 202 @defthing[input-background-color style?] 203 @defthing[no-color style?] 204 @defthing[reader-color style?] 205 @defthing[result-color style?] 206 @defthing[keyword-color style?] 207 @defthing[comment-color style?] 208 @defthing[paren-color style?] 209 @defthing[meta-color style?] 210 @defthing[value-color style?] 211 @defthing[symbol-color style?] 212 @defthing[variable-color style?] 213 @defthing[opt-color style?] 214 @defthing[error-color style?] 215 @defthing[syntax-link-color style?] 216 @defthing[value-link-color style?] 217 @defthing[module-color style?] 218 @defthing[module-link-color style?] 219 @defthing[block-color style?] 220 @defthing[highlighted-color style?] 221 )]{ 222 223 Styles that are used for coloring Racket programs, results, and I/O.}