mthl
/
texinfo


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238
							<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Pretty-printing</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Format.xhtml" title="Formatted Output (Common-Lisp-style)"/>
    <link rel="next" href="Resources.xhtml" title="Resources"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Pretty-printing" epub:type="subchapter" id="Pretty-printing">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Pretty-printing</h2>
          </div>
        </div>
      </div>
      <p>Pretty-printing is displaying a data structure as text,
by adding line-breaks and indenttaion so that the visual
structure of the output corresponds to the logical structure of
data structure.  This makes it easier to read and understand.
Pretty-printing takes into account the column width of the output
so as to avoid using more lines than needed.
</p>
      <p>Pretty-printing of standard sequences types such as lists and
vectors is done by default.  For example:
</p>
      <pre class="screen"><span class="prompt">#|kawa:11|# </span><strong class="userinput"><code>(set! *print-right-margin* 50)</code></strong>
<span class="prompt">#|kawa:12|# </span><strong class="userinput"><code>'(ABCDEF (aa bb cc dd) (x123456789</code></strong>
<span class="prompt">#|.....13|# </span><strong class="userinput"><code>y123456789 z123456789) ABCDEFG HIJKL)</code></strong>
(ABCDEF (aa bb cc dd)
 (x123456789 y123456789 z123456789) ABCDEFG HIJK)
</pre>
      <p>Setting <code class="literal">*print-right-margin*</code> to 50
causes output to be limited to 50 columns.
Notice the top-level list has to be split,
but sub-lists <code class="literal">(aa bb cc dd)</code>
and <code class="literal">(x123456789 y123456789 z123456789)</code>
don’t need to be split.
</p>
      <p>When outputting to a DomTerm REPL,
then <code class="literal">*print-right-margin*</code> is ignored,
and the line-breaking is actually handled by DomTerm.
If you change the window width, DomTerm will dynamically
re-calculate the line-breaks of previous pretten output.
This works even in the case of a session saved to an HTML
file, as long as JavaScript is enabled.
</p>
      <p>The concepts and terminology are
based on those of <a class="ulink" href="https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node253.html" target="_top">Common Lisp</a>.
</p>
      <section class="sect2" title="Pretty-printing Scheme forms" epub:type="division" id="idm139667872102416">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Pretty-printing Scheme forms</h3>
            </div>
          </div>
        </div>
        <p>Scheme and Lisp code is traditionally pretty-printed
slightly differently than plain lists.
The <code class="literal">pprint</code> procedure assumes the argument
is a Scheme form, and prints its accordingly.
For example the special form <code class="literal">(let ...)</code> is printed
differently from a regular function call <code class="literal">(list ...)</code>.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667872099392" class="indexterm"/> <code class="function">pprint</code> <em class="replaceable"><code>obj</code></em> [<em class="replaceable"><code>out</code></em>]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Assume <em class="replaceable"><code>obj</code></em> is a Scheme form, and pretty-print it
in traditional Scheme format.  For example:
</p>
            <pre class="screen"><span class="prompt">#|kawa:1|# </span><strong class="userinput"><code>(import (kawa pprint))</code></strong>
<span class="prompt">#|kawa:2|# </span><strong class="userinput"><code>(define fib-form</code></strong>
<span class="prompt">#|.....3|# </span><strong class="userinput"><code>  '(define (fibonacci n)</code></strong>
<span class="prompt">#|.....4|# </span><strong class="userinput"><code>     (let loop ((i0 0) (i1 1) (n n))</code></strong>
<span class="prompt">#|.....5|# </span><strong class="userinput"><code>       (if (&lt;= n 0) i0</code></strong>
<span class="prompt">#|.....6|# </span><strong class="userinput"><code>           (loop i1 (+ i0 i1) (- n 1))))))</code></strong>
<span class="prompt">#|kawa:7|# </span><strong class="userinput"><code>(set! *print-right-margin* 80)</code></strong>
<span class="prompt">#|kawa:8|# </span><strong class="userinput"><code>(pprint fib-form)</code></strong>
(define (fibonacci n)
  (let loop ((i0 0) (i1 1) (n n)) (if (&lt;= n 0) i0 (loop i1 (+ i0 i1) (- n 1)))))
<span class="prompt">#|kawa:9|# </span><strong class="userinput"><code>(set! *print-right-margin* 40)</code></strong>
<span class="prompt">#|kawa:10|# </span><strong class="userinput"><code>(pprint fib-form)</code></strong>
(define (fibonacci n)
  (let loop ((i0 0) (i1 1) (n n))
    (if (&lt;= n 0)
        i0
        (loop i1 (+ i0 i1) (- n 1)))))
</pre>
            <p>The <code class="literal">pprint</code> special-cases forms that start with
<code class="literal">define</code>, <code class="literal">if</code>, <code class="literal">lambda</code>, <code class="literal">let</code>,
and a few more, and formats them with “traditional” indentation.
However, it is not as complete or polished as it should be.
(It should also use a programmable dispatch table,
rather than having these special cases hard-wired.
That is an improvemet for another day.)
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Generic pretty-printing functions" epub:type="division" id="idm139667872084384">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Generic pretty-printing functions</h3>
            </div>
          </div>
        </div>
        <p>The following procedures are used to indicate logical blocks,
and optional newlines.
</p>
        <p>To access them do:
</p>
        <pre class="screen">(import (kawa pprint))
</pre>
        <p>In the following, <em class="replaceable"><code>out</code></em> is the output port, which
defaults to <code class="literal">(current-output-port)</code>.
</p>
        <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667872080848" class="indexterm"/> <code class="function">pprint-logical-block</code> <em class="replaceable"><code><em class="replaceable"><code>options</code></em></code></em> <em class="replaceable"><code><a class="link" href="Bodies.xhtml#meta-statement"><em class="replaceable"><code>statement</code></em></a></code></em><em class="replaceable"><code><sup>*</sup></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Evaluate the <em class="replaceable"><code>statement</code></em>s within the context of a new “logical block”.
</p>
            <p>The <em class="replaceable"><code>options</code></em> are one or more of the following:
</p>
            <div class="variablelist" epub:type="list">
              <dl class="variablelist">
                <dt class="term"><code class="literal"><span class="bold"><strong>prefix:</strong></span></code> <em class="replaceable"><code>prefix</code></em>
</dt>
                <dt class="term"><code class="literal"><span class="bold"><strong>per-line:</strong></span></code> <em class="replaceable"><code>per-line-prefix</code></em>
</dt>
                <dd>
                  <p>Emit <em class="replaceable"><code>prefix</code></em> or <em class="replaceable"><code>per-line-prefix</code></em> (only one of them can be specified) before the start of the logical block.
If <em class="replaceable"><code>per-line-prefix</code></em> is provided, it is also print for each
line within the logical block, indented the same.
These are strings and default to <code class="literal">""</code>.
</p>
                </dd>
                <dt class="term"><code class="literal"><span class="bold"><strong>suffix:</strong></span></code> <em class="replaceable"><code>suffix</code></em>
</dt>
                <dd>
                  <p>Emit <em class="replaceable"><code>suffix</code></em> after the end of the logical block.
</p>
                </dd>
                <dt class="term"><code class="literal"><span class="bold"><strong>out:</strong></span></code> <em class="replaceable"><code>out</code></em>
</dt>
                <dd>
                  <p>The output file.
</p>
                </dd>
              </dl>
            </div>
            <p>For example to print a list you might do:
</p>
            <pre class="screen">(pprint-logical-block prefix: "(" suffix: ")"
   <span class="emphasis"><em>print contents of list</em></span>)
</pre>
            <p>This macro is equivalent to:
</p>
            <pre class="screen">(pprint-start-logical-block <em class="replaceable"><code>prefix</code></em> <em class="replaceable"><code>is-per-line</code></em> <em class="replaceable"><code>suffix</code></em> <em class="replaceable"><code>out</code></em>)
(try-finally
  (begin <em class="replaceable"><code>statement</code></em><sup>*</sup>)
  (pprint-end-logical-block <em class="replaceable"><code>suffix</code></em> <em class="replaceable"><code>out</code></em>))
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667872059808" class="indexterm"/> <code class="function">pprint-start-logical-block</code> <em class="replaceable"><code>prefix</code></em> <em class="replaceable"><code>is-per-line</code></em> <em class="replaceable"><code>suffix</code></em> <em class="replaceable"><code>out</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Start a logical block.
The <em class="replaceable"><code>is-per-line</code></em> argument is a boolean to specifiy
of <em class="replaceable"><code>prefix</code></em> is a per-line-prefix or a plain prefix.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667872054352" class="indexterm"/> <code class="function">pprint-end-logical-block</code> <em class="replaceable"><code>suffix</code></em> <em class="replaceable"><code>out</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>End a logical block.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667872050560" class="indexterm"/> <code class="function">pprint-newline</code> <em class="replaceable"><code>kind</code></em> [<em class="replaceable"><code>out</code></em>]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Print a conditional newline, where <em class="replaceable"><code>kind</code></em> is one of the
symbols <code class="literal">'fill</code>, <code class="literal">'linear</code>, <code class="literal">'mandatory</code>,
or <code class="literal">'miser</code>.
Usually follows printing of a space, as nothing is printed
if the line is not broken here.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667872044400" class="indexterm"/> <code class="function">pprint-ident</code> <em class="replaceable"><code>mode</code></em> <em class="replaceable"><code>amount</code></em> [<em class="replaceable"><code>out</code></em>]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Change how much following lines are indented
(with the current logical block).
The <em class="replaceable"><code>amount</code></em> is the size of the indentation, in characters.
The <em class="replaceable"><code>mode</code></em> is either <code class="literal">'current</code> (if the
<em class="replaceable"><code>amount</code></em> is relative to the current position),
or <code class="literal">'block</code> (if the <em class="replaceable"><code>amount</code></em> is relative to the
start (after any <em class="replaceable"><code>prefix</code></em>) of the current logical block).
</p>
          </blockquote>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Pretty-printing.xhtml#idm139667872102416">Pretty-printing Scheme forms</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Pretty-printing.xhtml#idm139667872084384">Generic pretty-printing functions</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Input-Output.xhtml">Input, output, and file handling</a></p>
        <p>
        Previous: <a accesskey="p" href="Format.xhtml">Formatted Output (Common-Lisp-style)</a></p>
        <p>
        Next: <a accesskey="n" href="Resources.xhtml">Resources</a></p>
      </div>
    </footer>
  </body>
</html>