|
1 | 1 | #lang scribble/doc |
2 | | -@(require "common.rkt" |
3 | | - (for-label mzlib/pconvert |
4 | | - mzlib/pconvert-prop |
5 | | - racket/contract |
6 | | - racket/pretty)) |
| 2 | +@(require "common.rkt") |
7 | 3 |
|
8 | | -@mzlib[#:mode title pconvert] |
9 | | - |
10 | | -The @racketmodname[mzlib/pconvert] library defines routines for |
11 | | -printing Racket values as @racket[eval]uable S-expressions. Racket's |
12 | | -default printing mode also prints values as expressions (in contrast |
13 | | -to the Lisp and Racket tradition of printing @racket[read]able |
14 | | -S-expressions), but @racketmodname[mzlib/pconvert] is more |
15 | | -configurable and approximates expressions for a wider range of |
16 | | -values. For example, procedures print using @racketresultfont{lambda} |
17 | | -instead of @racketresultfont{#<procedure>}. |
18 | | - |
19 | | -The @racket[print-convert] procedure does not print values; rather, it |
20 | | -converts a Racket value into another Racket value such that the new |
21 | | -value @racket[pretty-write]s as a Racket expression that evaluates to |
22 | | -the original value. For example, @racket[(pretty-write (print-convert |
23 | | -`(9 ,(box 5) #(6 7))))] prints the literal expression |
24 | | -@racketresult[(list 9 (box 5) (vector 6 7))] to the current output |
25 | | -port. |
26 | | - |
27 | | -To install print converting into the read-eval-print loop, require |
28 | | -@racketmodname[mzlib/pconvert] and call the procedure |
29 | | -@racket[install-converting-printer]. |
30 | | - |
31 | | -In addition to @racket[print-convert], this library provides |
32 | | -@racket[print-convert], @racket[build-share], @racket[get-shared], |
33 | | -and @racket[print-convert-expr]. The last three are used to convert |
34 | | -sub-expressions of a larger expression (potentially with shared |
35 | | -structure). |
36 | | - |
37 | | -See also @racket[prop:print-convert-constructor-name]. |
38 | | - |
39 | | -@defboolparam[abbreviate-cons-as-list abbreviate?]{ |
40 | | - |
41 | | -A parameter that controls how lists are represented with |
42 | | -constructor-style conversion. If the parameter's value is @racket[#t], |
43 | | -lists are represented using @racket[list]. Otherwise, lists are |
44 | | -represented using @racket[cons]. The initial value of the parameter is |
45 | | -@racket[#t].} |
46 | | - |
47 | | - |
48 | | -@defboolparam[booleans-as-true/false use-name?]{ |
49 | | - |
50 | | -A parameter that controls how @racket[#t] and @racket[#f] are |
51 | | -represented. If the parameter's value is @racket[#t], then @racket[#t] |
52 | | -is represented as @racket[true] and @racket[#f] is represented as |
53 | | -@racket[false]. The initial value of the parameter is @racket[#t].} |
54 | | - |
55 | | - |
56 | | -@defparam[use-named/undefined-handler use-handler (any/c . -> . any/c)]{ |
57 | | - |
58 | | -A parameter that controls how values that have inferred names are |
59 | | -represented. The procedure is passed a value. If the procedure returns |
60 | | -true, the procedure associated with @racket[named/undefined-handler] |
61 | | -is invoked to render that value. Only values that have inferred names |
62 | | -but are not defined at the top-level are used with this handler. |
63 | | - |
64 | | -The initial value of the parameter is @racket[(lambda (x) #f)].} |
65 | | - |
66 | | - |
67 | | -@defparam[named/undefined-handler use-handler (any/c . -> . any/c)]{ |
68 | | - |
69 | | -Parameter for a procedure that controls how values that have inferred |
70 | | -names are represented. The procedure is called only if |
71 | | -@racket[use-named/undefined-handler] returns true for some value. In |
72 | | -that case, the procedure is passed that same value, and the result of |
73 | | -the parameter is used as the representation for the value. |
74 | | - |
75 | | -The initial value of the parameter is @racket[(lambda (x) #f)].} |
76 | | - |
77 | | - |
78 | | -@defboolparam[add-make-prefix-to-constructor add-prefix?]{ |
79 | | - |
80 | | -A parameter that controls whether a @racketidfont{make-} prefix is |
81 | | -added to a constructor name for a structure instance. The initial |
82 | | -value of the parameter is @racket[#f].} |
83 | | - |
84 | | -@defboolparam[hash-table-constructor-with-lists use-list?]{ |
85 | | - A parameter that controls whether the key/value pairs in a |
86 | | - hash are printed with @racketidfont{cons} or |
87 | | - @racketidfont{list}. The initial value of the parameter is |
88 | | - @racket[#f], meaning that a hash table like @racket[(hash 'x 1 'y 2)] |
89 | | - converts to @racket['(make-immutable-hash (list (cons 'y 2) (cons 'x 1)))]. |
90 | | - |
91 | | - @history[#:added "1.2"] |
92 | | -} |
93 | | - |
94 | | - |
95 | | - |
96 | | -@defproc[(build-share [v any/c]) ....]{ |
97 | | - |
98 | | -Takes a value and computes sharing information used for representing |
99 | | -the value as an expression. The return value is an opaque structure |
100 | | -that can be passed back into @racket[get-shared] or |
101 | | -@racket[print-convert-expr].} |
102 | | - |
103 | | - |
104 | | -@defboolparam[constructor-style-printing use-constructors?]{ |
105 | | - |
106 | | -Parameter that controls how values are represented after conversion. |
107 | | -If this parameter's value is @racket[#t], then constructors are used; |
108 | | -e.g., pair containing @racket[1] and @racket[2] is represented as |
109 | | -@racket[(cons 1 2)]. Otherwise, @racket[quasiquote]-style syntax is |
110 | | -used; e.g., the pair containing @racket[1] and @racket[2] is |
111 | | -represented as @racket[`(1 . 2)]. The initial value of the parameter |
112 | | -is @racket[#f]. |
113 | | - |
114 | | -The constructor used for mutable pairs is @racketidfont{mcons}, unless |
115 | | -@racket[print-mpair-curly-braces] is set to @racket[#f], in which case |
116 | | -@racketidfont{cons} and @racketidfont{list} are used. Similarly, when |
117 | | -using @racket[quasiquote] style and @racket[print-mpair-curly-braces] |
118 | | -is set to @racket[#f], mutable pair constructions are represented |
119 | | -using @racketidfont{quote}, @racketidfont{quasiquote}, etc. |
120 | | - |
121 | | -See also @racket[quasi-read-style-printing] and |
122 | | -@racket[prop:print-convert-constructor-name].} |
123 | | - |
124 | | - |
125 | | -@defparam[current-build-share-hook |
126 | | - hook |
127 | | - (any/c (any/c . -> . void?) |
128 | | - (any/c . -> . void?) . -> . any)]{ |
129 | | - |
130 | | -Parameter that sets a procedure used by @racket[print-convert] and |
131 | | -@racket[build-share] to assemble sharing information. The procedure |
132 | | -@racket[hook] takes three arguments: a value @racket[_v], a procedure |
133 | | -@racket[_basic-share], and a procedure @racket[_sub-share]; the return |
134 | | -value is ignored. The @racket[basic-share] procedure takes @racket[_v] |
135 | | -and performs the built-in sharing analysis, while the |
136 | | -@racket[_sub-share] procedure takes a component of @racket[_v] ands |
137 | | -analyzes it. Sharing information is accumulated as values are passed |
138 | | -to @racket[basic-share] and @racket[sub-share]. |
139 | | - |
140 | | -A @racket[current-build-share-hook] procedure usually works together |
141 | | -with a @racket[current-print-convert-hook] procedure.} |
142 | | - |
143 | | - |
144 | | -@defparam[current-build-share-name-hook hook (any/c . -> . (or/c symbol? false/c))]{ |
145 | | - |
146 | | -Parameter that sets a procedure used by @racket[print-convert] and |
147 | | -@racket[build-share] to generate a new name for a shared value. The |
148 | | -@racket[hook] procedure takes a single value and returns a symbol for |
149 | | -the value's name. If @racket[hook] returns @racket[#f], a name is |
150 | | -generated using the form |
151 | | -``@racketidfont{-}@racket[_n]@racketidfont{-}, where @racket[n] is an |
152 | | -integer.} |
153 | | - |
154 | | - |
155 | | -@defparam[current-print-convert-hook |
156 | | - hook |
157 | | - (any/c (any/c . -> . any/c) |
158 | | - (any/c . -> . any/c) |
159 | | - . -> . any/c)]{ |
160 | | - |
161 | | -Parameter that sets a procedure used by @racket[print-convert] and |
162 | | -@racket[print-convert-expr] to convert values. The procedure |
163 | | -@racket[hook] takes three arguments---a value @racket[_v], a procedure |
164 | | -@racket[_basic-convert], and a procedure @racket[_sub-convert]---and |
165 | | -returns the converted representation of @racket[_v]. The |
166 | | -@racket[_basic-convert] procedure takes @racket[_v] and returns the |
167 | | -default conversion, while the @racket[_sub-convert] procedure takes a |
168 | | -component of @racket[_v] and returns its conversion. |
169 | | - |
170 | | -A @racket[current-print-convert-hook] procedure usually works together |
171 | | -with a @racket[current-build-share-hook] procedure.} |
172 | | - |
173 | | - |
174 | | -@defparam[current-read-eval-convert-print-prompt str string?]{ |
175 | | - |
176 | | -Parameter that sets the prompt used by |
177 | | -@racket[install-converting-printer]. |
178 | | -The initial value is @racket["|- "].} |
179 | | - |
180 | | - |
181 | | -@defproc[(get-shared [share-info ....] |
182 | | - [cycles-only? any/c #f]) |
183 | | - (list-of (cons/c symbol? any/c))]{ |
184 | | - |
185 | | -The @racket[shared-info] value must be a result from @racket[build-share]. |
186 | | -The procedure returns a list matching variables to shared values |
187 | | -within the value passed to @racket[build-share]. |
188 | | - |
189 | | -The default value for @racket[cycles-only?] is @racket[#f]; |
190 | | -if it is not @racket[#f], @racket[get-shared] returns only information |
191 | | -about cycles. |
192 | | - |
193 | | -For example, |
194 | | - |
195 | | -@racketblock[ |
196 | | -(get-shared (build-share (shared ([a (cons 1 b)] |
197 | | - [b (cons 2 a)]) |
198 | | - a))) |
199 | | -] |
200 | | - |
201 | | -might return the list |
202 | | - |
203 | | -@racketblock[ |
204 | | -'((-1- (cons 1 -2-)) (-2- (cons 2 -1-))) |
205 | | -]} |
206 | | - |
207 | | - |
208 | | -@defproc[(install-converting-printer) void?]{ |
209 | | - |
210 | | -Sets the current print handler to print values using |
211 | | -@racket[print-convert] and sets @racket[print-as-expression] to |
212 | | -@racket[#f] (since the conversion of a value is meant to be printed in |
213 | | -@racket[read]able form rather than @racket[eval]uable form). The |
214 | | -current read handler is also set to use the prompt returned by |
215 | | -@racket[current-read-eval-convert-print-prompt].} |
216 | | - |
217 | | - |
218 | | -@defproc[(print-convert [v any/c][cycles-only? any/c (show-sharing)]) any/c]{ |
219 | | - |
220 | | -Converts the value @racket[v]. If @racket[cycles-only?] is not |
221 | | -@racket[#f], then only circular objects are included in the |
222 | | -output.} |
223 | | - |
224 | | - |
225 | | -@defproc[(print-convert-expr [share-info ....] |
226 | | - [v any/c] |
227 | | - [unroll-once? any/c]) any/c]{ |
228 | | - |
229 | | -Converts the value @racket[v] using sharing information |
230 | | -@racket[share-info], which was previously returned by |
231 | | -@racket[build-share] for a value containing @racket[v]. If the most |
232 | | -recent call to @racket[get-shared] with @racket[share-info] requested |
233 | | -information only for cycles, then @racket[print-convert-expr] will |
234 | | -only display sharing among values for cycles, rather than showing all |
235 | | -value sharing. |
236 | | - |
237 | | -The @racket[unroll-once?] argument is used if @racket[v] is a shared |
238 | | -value in @racket[share-info]. In this case, if @racket[unroll-once?] |
239 | | -is @racket[#f], then the return value will be a shared-value |
240 | | -identifier; otherwise, the returned value shows the internal structure |
241 | | -of @racket[v] (using shared value identifiers within @racket[v]'s |
242 | | -immediate structure as appropriate).} |
243 | | - |
244 | | - |
245 | | -@defboolparam[quasi-read-style-printing on?]{ |
246 | | - |
247 | | -Parameter that controls how vectors and boxes are represented after |
248 | | -conversion when the value of @racket[constructor-style-printing] is |
249 | | -@racket[#f]. If @racket[quasi-read-style-printing] is set to |
250 | | -@racket[#f], then boxes and vectors are unquoted and represented using |
251 | | -constructors. For example, the list of a box containing the number 1 |
252 | | -and a vector containing the number 1 is represented as @racketresult[`(,(box |
253 | | -1) ,(vector 1))]. If the parameter's value is @racket[#t], then |
254 | | -@racket[#&....] and @racket[#(....)] are used, e.g., @racket[`(#&1 |
255 | | -#(1))]. The initial value of the parameter is @racket[#t].} |
256 | | - |
257 | | - |
258 | | -@defboolparam[show-sharing show?]{ |
259 | | - |
260 | | -Parameter that determines whether sub-value sharing is conserved (and |
261 | | -shown) in the converted output by default. The initial value of the |
262 | | -parameter is @racket[#t].} |
263 | | - |
264 | | - |
265 | | -@defboolparam[whole/fractional-exact-numbers whole-frac?]{ |
266 | | - |
267 | | -Parameter that controls how exact, non-integer numbers are converted |
268 | | -when the numerator is greater than the denominator. If the parameter's |
269 | | -value is @racket[#t], the number is converted to the form @racket[(+ |
270 | | -_integer _fraction)] (i.e., a list containing @racket['+], an exact |
271 | | -integer, and an exact rational less than @racket[1] and greater than |
272 | | -@racket[-1]). The initial value of the parameter is @racket[#f].} |
| 4 | +@title{@racket[mzlib/pconvert]} |
273 | 5 |
|
| 6 | +See @racketmodname[mzlib/pconvert]. |
0 commit comments