Debian Codegraph @

info/gcl/Examples-of-using-the-Pretty-Printer.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>Examples of using the Pretty Printer (ANSI and GNU Common Lisp Document)</title>
7
8 <meta name="description" content="Examples of using the Pretty Printer (ANSI and GNU Common Lisp Document)">
9 <meta name="keywords" content="Examples of using the Pretty Printer (ANSI and GNU Common Lisp Document)">
10 <meta name="resource-type" content="document">
11 <meta name="distribution" content="global">
12 <meta name="Generator" content="makeinfo">
13 <link href="index.html" rel="start" title="Top">
14 <link href="The-Lisp-Pretty-Printer.html" rel="up" title="The Lisp Pretty Printer">
15 <link href="Notes-about-the-Pretty-Printer_0060s-Background.html" rel="next" title="Notes about the Pretty Printer`s Background">
16 <link href="Pretty-Printer-Margins.html" rel="prev" title="Pretty Printer Margins">
17 <style type="text/css">
18 <!--
19 a.summary-letter {text-decoration: none}
20 blockquote.indentedblock {margin-right: 0em}
21 div.display {margin-left: 3.2em}
22 div.example {margin-left: 3.2em}
23 div.lisp {margin-left: 3.2em}
24 kbd {font-style: oblique}
25 pre.display {font-family: inherit}
26 pre.format {font-family: inherit}
27 pre.menu-comment {font-family: serif}
28 pre.menu-preformatted {font-family: serif}
29 span.nolinebreak {white-space: nowrap}
30 span.roman {font-family: initial; font-weight: normal}
31 span.sansserif {font-family: sans-serif; font-weight: normal}
32 ul.no-bullet {list-style: none}
33 -->
34 </style>
35
36
37 </head>
38
39 <body lang="en">
40 <span id="Examples-of-using-the-Pretty-Printer"></span><div class="header">
41 <p>
42 Next: <a href="Notes-about-the-Pretty-Printer_0060s-Background.html" accesskey="n" rel="next">Notes about the Pretty Printer`s Background</a>, Previous: <a href="Pretty-Printer-Concepts.html" accesskey="p" rel="prev">Pretty Printer Concepts</a>, Up: <a href="The-Lisp-Pretty-Printer.html" accesskey="u" rel="up">The Lisp Pretty Printer</a> &nbsp; </p>
43 </div>
44 <hr>
45 <span id="Examples-of-using-the-Pretty-Printer-1"></span><h4 class="subsection">22.2.2 Examples of using the Pretty Printer</h4>
46
47 <p>As an example of the interaction of logical blocks, conditional newlines,
48 and indentation, consider the function <tt>simple-pprint-defun</tt> below. This
49 function prints out lists whose <i>cars</i> are <b>defun</b> in the
50 standard way assuming that the list has exactly length <tt>4</tt>.
51 </p>
52 <div class="example">
53 <pre class="example">(defun simple-pprint-defun (*standard-output* list)
54 (pprint-logical-block (*standard-output* list :prefix &quot;(&quot; :suffix &quot;)&quot;)
55 (write (first list))
56 (write-char #\Space)
57 (pprint-newline :miser)
58 (pprint-indent :current 0)
59 (write (second list))
60 (write-char #\Space)
61 (pprint-newline :fill)
62 (write (third list))
63 (pprint-indent :block 1)
64 (write-char #\Space)
65 (pprint-newline :linear)
66 (write (fourth list))))
67 </pre></div>
68
69 <p>Suppose that one evaluates the following:
70 </p>
71 <div class="example">
72 <pre class="example">(simple-pprint-defun *standard-output* '(defun prod (x y) (* x y)))
73 </pre></div>
74
75 <p>If the line width available is greater than or equal to <tt>26</tt>, then all of the
76 output appears on one line. If the line width available is reduced to <tt>25</tt>,
77 a line break is inserted at the
78 linear-style conditional newline
79 <span id="index-linear_002dstyle-conditional-newline"></span>
80 </p>
81 <p>before the
82 <i>expression</i> <tt>(* x y)</tt>, producing the output shown. The
83 <tt>(pprint-indent :block 1)</tt> causes <tt>(* x y)</tt> to be printed at a relative
84 indentation of <tt>1</tt> in the logical block.
85 </p>
86 <div class="example">
87 <pre class="example"> (DEFUN PROD (X Y)
88 (* X Y))
89 </pre></div>
90
91 <p>If the line width available is <tt>15</tt>, a line break is also inserted at the
92 fill style conditional newline before the argument list. The call on
93 <tt>(pprint-indent :current 0)</tt> causes the argument list to line up under the
94 function name.
95 </p>
96 <div class="example">
97 <pre class="example">(DEFUN PROD
98 (X Y)
99 (* X Y))
100 </pre></div>
101
102 <p>If <b>*print-miser-width*</b> were greater than or equal to 14, the example
103 output above would have been as follows, because all indentation changes
104 are ignored in miser mode and line breaks are inserted at
105 miser-style conditional newlines.
106 <span id="index-miser_002dstyle-conditional-newline"></span>
107 </p>
108 <div class="example">
109 <pre class="example"> (DEFUN
110 PROD
111 (X Y)
112 (* X Y))
113 </pre></div>
114
115 <p>As an example of a per-line prefix, consider that evaluating the following
116 produces the output shown with a line width of <tt>20</tt> and
117 <b>*print-miser-width*</b> of <b>nil</b>.
118 </p>
119 <div class="example">
120 <pre class="example"> (pprint-logical-block (*standard-output* nil :per-line-prefix &quot;;;; &quot;)
121 (simple-pprint-defun *standard-output* '(defun prod (x y) (* x y))))
122
123 ;;; (DEFUN PROD
124 ;;; (X Y)
125 ;;; (* X Y))
126 </pre></div>
127
128 <p>As a more complex (and realistic) example, consider the function <tt>pprint-let</tt>
129 below. This specifies how to print a <b>let</b> <i>form</i> in the traditional
130 style. It is more complex than the example above, because it has to deal with
131 nested structure. Also, unlike the example above it contains complete code to
132 readably print any possible list that begins with the <i>symbol</i> <b>let</b>.
133 The outermost <b>pprint-logical-block</b> <i>form</i> handles the printing of
134 the input list as a whole and specifies that parentheses should be printed in the
135 output. The second <b>pprint-logical-block</b> <i>form</i> handles the list
136 of binding pairs. Each pair in the list is itself printed by the innermost
137 <b>pprint-logical-block</b>. (A <b>loop</b> <i>form</i> is used instead of
138 merely decomposing the pair into two <i>objects</i> so that readable output will
139 be produced no matter whether the list corresponding to the pair has one element,
140 two elements, or (being malformed) has more than two elements.)
141 A space and a
142 fill-style conditional newline
143 <span id="index-fill_002dstyle-conditional-newline"></span>
144 </p>
145 <p>are placed after
146 each pair except the last. The loop at the end of the topmost
147 <b>pprint-logical-block</b> <i>form</i> prints out the forms in the body
148 of the <b>let</b> <i>form</i> separated by spaces and
149 linear-style conditional newlines.
150 </p>
151 <div class="example">
152 <pre class="example"> (defun pprint-let (*standard-output* list)
153 (pprint-logical-block (nil list :prefix &quot;(&quot; :suffix &quot;)&quot;)
154 (write (pprint-pop))
155 (pprint-exit-if-list-exhausted)
156 (write-char #\Space)
157 (pprint-logical-block (nil (pprint-pop) :prefix &quot;(&quot; :suffix &quot;)&quot;)
158 (pprint-exit-if-list-exhausted)
159 (loop (pprint-logical-block (nil (pprint-pop) :prefix &quot;(&quot; :suffix &quot;)&quot;)
160 (pprint-exit-if-list-exhausted)
161 (loop (write (pprint-pop))
162 (pprint-exit-if-list-exhausted)
163 (write-char #\Space)
164 (pprint-newline :linear)))
165 (pprint-exit-if-list-exhausted)
166 (write-char #\Space)
167 (pprint-newline :fill)))
168 (pprint-indent :block 1)
169 (loop (pprint-exit-if-list-exhausted)
170 (write-char #\Space)
171 (pprint-newline :linear)
172 (write (pprint-pop)))))
173 </pre></div>
174
175 <p>Suppose that one evaluates the following with <b>*print-level*</b> being 4,
176 and <b>*print-circle*</b> being <i>true</i>.
177 </p>
178 <div class="example">
179 <pre class="example"> (pprint-let *standard-output*
180 '#1=(let (x (*print-length* (f (g 3)))
181 (z . 2) (k (car y)))
182 (setq x (sqrt z)) #1#))
183 </pre></div>
184
185 <p>If the line length is greater than or equal to <tt>77</tt>, the output produced
186 appears on one line. However, if the line length is <tt>76</tt>, line breaks are
187 inserted at the linear-style conditional newlines separating the forms in
188 the body and the output below is produced. Note that, the degenerate
189 binding pair <tt>x</tt> is printed readably even though it fails to be a list; a
190 depth abbreviation marker is printed in place of <tt>(g 3)</tt>; the binding pair
191 <tt>(z . 2)</tt> is printed readably even though it is not a proper list; and
192 appropriate circularity markers are printed.
193 </p>
194 <div class="example">
195 <pre class="example"> #1=(LET (X (*PRINT-LENGTH* (F #)) (Z . 2) (K (CAR Y)))
196 (SETQ X (SQRT Z))
197 #1#)
198 </pre></div>
199
200 <p>If the line length is reduced to <tt>35</tt>, a line break is inserted at one of the
201 fill-style conditional newlines separating the binding pairs.
202 </p>
203 <div class="example">
204 <pre class="example"> #1=(LET (X (*PRINT-PRETTY* (F #))
205 (Z . 2) (K (CAR Y)))
206 (SETQ X (SQRT Z))
207 #1#)
208 </pre></div>
209
210 <p>Suppose that the line length is further reduced to <tt>22</tt> and <b>*print-length*</b> is
211 set to <tt>3</tt>. In this situation, line breaks are inserted after both the first
212 and second binding pairs. In addition, the second binding pair is itself
213 broken across two lines. Clause (b) of the description of fill-style
214 conditional newlines (see the <i>function</i> <b>pprint-newline</b>)
215 prevents the binding pair <tt>(z . 2)</tt> from being printed
216 at the end of the third line. Note that the length abbreviation hides the
217 circularity from view and therefore the printing of circularity markers
218 disappears.
219 </p>
220 <div class="example">
221 <pre class="example"> (LET (X
222 (*PRINT-LENGTH*
223 (F #))
224 (Z . 2) ...)
225 (SETQ X (SQRT Z))
226 ...)
227 </pre></div>
228
229 <p>The next function prints a vector using &ldquo;<tt>#(...)</tt>&rdquo; notation.
230 </p>
231 <div class="example">
232 <pre class="example">(defun pprint-vector (*standard-output* v)
233 (pprint-logical-block (nil nil :prefix &quot;#(&quot; :suffix &quot;)&quot;)
234 (let ((end (length v)) (i 0))
235 (when (plusp end)
236 (loop (pprint-pop)
237 (write (aref v i))
238 (if (= (incf i) end) (return nil))
239 (write-char #\Space)
240 (pprint-newline :fill))))))
241 </pre></div>
242
243 <p>Evaluating the following with a line length of 15 produces the output shown.
244 </p>
245 <div class="example">
246 <pre class="example"> (pprint-vector *standard-output* '#(12 34 567 8 9012 34 567 89 0 1 23))
247
248 #(12 34 567 8
249 9012 34 567
250 89 0 1 23)
251 </pre></div>
252
253 <p>As examples of the convenience of specifying pretty printing with
254 <i>format strings</i>, consider that the functions <tt>simple-pprint-defun</tt>
255 and <tt>pprint-let</tt> used as examples above can be compactly defined as follows.
256 (The function <tt>pprint-vector</tt> cannot be defined using <b>format</b>
257 because the data structure it traverses is not a list.)
258 </p>
259 <div class="example">
260 <pre class="example">(defun simple-pprint-defun (*standard-output* list)
261 (format T &quot;~:&lt;~W ~@_~:I~W ~:_~W~1I ~_~W~:&gt;&quot; list))
262
263 (defun pprint-let (*standard-output* list)
264 (format T &quot;~:&lt;~W~<tt>^</tt>~:&lt;~@{~:&lt;~@{~W~<tt>^</tt>~_~}~:&gt;~<tt>^</tt>~:_~}~:&gt;~1I~@{~<tt>^</tt>~_~W~}~:&gt;&quot; list))
265 </pre></div>
266
267 <p>In the following example, the first <i>form</i> restores
268 <b>*print-pprint-dispatch*</b> to the equivalent of its initial value.
269 The next two forms then set up a special way to pretty print ratios.
270 Note that the more specific <i>type specifier</i> has to be associated
271 with a higher priority.
272 </p>
273 <div class="example">
274 <pre class="example"> (setq *print-pprint-dispatch* (copy-pprint-dispatch nil))
275
276 (set-pprint-dispatch 'ratio
277 #'(lambda (s obj)
278 (format s &quot;#.(/ ~W ~W)&quot;
279 (numerator obj) (denominator obj))))
280
281 (set-pprint-dispatch '(and ratio (satisfies minusp))
282 #'(lambda (s obj)
283 (format s &quot;#.(- (/ ~W ~W))&quot;
284 (- (numerator obj)) (denominator obj)))
285 5)
286
287 (pprint '(1/3 -2/3))
288 (#.(/ 1 3) #.(- (/ 2 3)))
289 </pre></div>
290
291 <p>The following two <i>forms</i> illustrate the definition of
292 pretty printing functions for types of <i>code</i>. The first
293 <i>form</i> illustrates how to specify the traditional method
294 for printing quoted objects using <i>single-quote</i>. Note
295 the care taken to ensure that data lists that happen to begin
296 with <b>quote</b> will be printed readably. The second form
297 specifies that lists beginning with the symbol <tt>my-let</tt>
298 should print the same way that lists beginning with <b>let</b>
299 print when the initial <i>pprint dispatch table</i> is in effect.
300 </p>
301 <div class="example">
302 <pre class="example"> (set-pprint-dispatch '(cons (member quote)) ()
303 #'(lambda (s list)
304 (if (and (consp (cdr list)) (null (cddr list)))
305 (funcall (formatter &quot;'~W&quot;) s (cadr list))
306 (pprint-fill s list))))
307
308 (set-pprint-dispatch '(cons (member my-let))
309 (pprint-dispatch '(let) nil))
310 </pre></div>
311
312 <p>The next example specifies a default method for printing lists that do not
313 correspond to function calls. Note that the functions <b>pprint-linear</b>,
314 <b>pprint-fill</b>, and <b>pprint-tabular</b> are all defined with
315 optional <i>colon-p</i> and <i>at-sign-p</i> arguments so that they can
316 be used as <b>pprint dispatch functions</b> as well as <tt>~/.../</tt>
317 functions.
318 </p>
319 <div class="example">
320 <pre class="example"> (set-pprint-dispatch '(cons (not (and symbol (satisfies fboundp))))
321 #'pprint-fill -5)
322
323 ;; Assume a line length of 9
324 (pprint '(0 b c d e f g h i j k))
325 (0 b c d
326 e f g h
327 i j k)
328 </pre></div>
329
330 <p>This final example shows how to define a pretty printing function for a
331 user defined data structure.
332 </p>
333 <div class="example">
334 <pre class="example"> (defstruct family mom kids)
335
336 (set-pprint-dispatch 'family
337 #'(lambda (s f)
338 (funcall (formatter &quot;~@&lt;#&lt;~;~W and ~2I~_~/pprint-fill/~;&gt;~:&gt;&quot;)
339 s (family-mom f) (family-kids f))))
340 </pre></div>
341
342 <p>The pretty printing function for the structure <tt>family</tt> specifies how to
343 adjust the layout of the output so that it can fit aesthetically into
344 a variety of line widths. In addition, it obeys
345 the printer control variables <b>*print-level*</b>,
346 <b>*print-length*</b>, <b>*print-lines*</b>,
347 <b>*print-circle*</b>
348 and <b>*print-escape*</b>,
349 and can tolerate several different kinds of malformity in the data structure.
350 The output below shows what is printed out with a right margin of <tt>25</tt>,
351 <b>*print-pretty*</b> being <i>true</i>, <b>*print-escape*</b> being <i>false</i>,
352 and a malformed <tt>kids</tt> list.
353 </p>
354 <div class="example">
355 <pre class="example"> (write (list 'principal-family
356 (make-family :mom &quot;Lucy&quot;
357 :kids '(&quot;Mark&quot; &quot;Bob&quot; . &quot;Dan&quot;)))
358 :right-margin 25 :pretty T :escape nil :miser-width nil)
359 (PRINCIPAL-FAMILY
360 #&lt;Lucy and
361 Mark Bob . Dan&gt;)
362 </pre></div>
363
364 <p>Note that a pretty printing function for a structure is different from
365 the structure&rsquo;s <b>print-object</b> <i>method</i>.
366 While
367 <b>print-object</b> <i>methods</i>
368 are permanently associated with a structure,
369 pretty printing functions are stored in
370 <i>pprint dispatch tables</i> and can be rapidly changed to reflect
371 different printing needs. If there is no pretty printing function for
372 a structure in the current <i>pprint dispatch table</i>,
373 its <b>print-object</b> <i>method</i>
374 is used instead.
375 </p>
376 <hr>
377 <div class="header">
378 <p>
379 Next: <a href="Notes-about-the-Pretty-Printer_0060s-Background.html" accesskey="n" rel="next">Notes about the Pretty Printer`s Background</a>, Previous: <a href="Pretty-Printer-Concepts.html" accesskey="p" rel="prev">Pretty Printer Concepts</a>, Up: <a href="The-Lisp-Pretty-Printer.html" accesskey="u" rel="up">The Lisp Pretty Printer</a> &nbsp; </p>
380 </div>
381
382
383
384 </body>
385 </html>