| 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> </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 "(" :suffix ")") |
| 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 ";;; ") |
| 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 "(" :suffix ")") |
| 154 |
(write (pprint-pop)) |
| 155 |
(pprint-exit-if-list-exhausted) |
| 156 |
(write-char #\Space) |
| 157 |
(pprint-logical-block (nil (pprint-pop) :prefix "(" :suffix ")") |
| 158 |
(pprint-exit-if-list-exhausted) |
| 159 |
(loop (pprint-logical-block (nil (pprint-pop) :prefix "(" :suffix ")") |
| 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 “<tt>#(...)</tt>” notation. |
| 230 |
</p> |
| 231 |
<div class="example"> |
| 232 |
<pre class="example">(defun pprint-vector (*standard-output* v) |
| 233 |
(pprint-logical-block (nil nil :prefix "#(" :suffix ")") |
| 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 "~:<~W ~@_~:I~W ~:_~W~1I ~_~W~:>" list)) |
| 262 |
|
| 263 |
(defun pprint-let (*standard-output* list) |
| 264 |
(format T "~:<~W~<tt>^</tt>~:<~@{~:<~@{~W~<tt>^</tt>~_~}~:>~<tt>^</tt>~:_~}~:>~1I~@{~<tt>^</tt>~_~W~}~:>" 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 "#.(/ ~W ~W)" |
| 279 |
(numerator obj) (denominator obj)))) |
| 280 |
|
| 281 |
(set-pprint-dispatch '(and ratio (satisfies minusp)) |
| 282 |
#'(lambda (s obj) |
| 283 |
(format s "#.(- (/ ~W ~W))" |
| 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 "'~W") 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 "~@<#<~;~W and ~2I~_~/pprint-fill/~;>~:>") |
| 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 "Lucy" |
| 357 |
:kids '("Mark" "Bob" . "Dan"))) |
| 358 |
:right-margin 25 :pretty T :escape nil :miser-width nil) |
| 359 |
(PRINCIPAL-FAMILY |
| 360 |
#<Lucy and |
| 361 |
Mark Bob . Dan>) |
| 362 |
</pre></div> |
| 363 |
|
| 364 |
<p>Note that a pretty printing function for a structure is different from |
| 365 |
the structure’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> </p> |
| 380 |
</div> |
| 381 |
|
| 382 |
|
| 383 |
|
| 384 |
</body> |
| 385 |
</html> |