Debian Codegraph @

blog/billet.markdown

raw
1 <!-- :!pandoc -s % -c style.css -H header.html > billet.html -->
2
3 I am pleased to announce the first official release of _**PPrint**_, an OCaml
4 library for pretty-printing textual documents.
5
6 ## A taste of the layout language
7
8 At the heart of _**PPrint**_ is a little domain-specific language of
9 documents. This language has a well-defined semantics, which the printing
10 engine implements. This language rests upon a small number of fundamental
11 concepts.
12
13 There are combinators for creating atomic documents. For
14 instance,
15
16 ```ocaml
17 string "hello"
18 ```
19
20 is a simple, unbreakable document.
21
22 There is also a concatenation operator, which joins two documents.
23 For instance,
24
25 ```ocaml
26 string "hello" ^^ string "world"
27 ```
28
29 is a composite document. It is in fact equivalent to `string "helloworld"`.
30
31 So far, nothing very exciting. The next two combinators are more original and
32 interesting.
33
34 The first of these combinators, `break 1`, is a breakable space. If printed in
35 flat mode, it produces an ordinary space character; if printed in normal mode,
36 it produces a newline character.
37
38 Yes, there are two printing modes, namely flat mode and normal mode. The
39 printing engine goes back and forth between these two modes. Exactly where and
40 how the engine switches from one mode to the other is controlled by the next
41 combinator.
42
43 The second of these combinators, `group`, introduces a choice between flat
44 mode and normal mode. It is a document transformer: if `d` is a document, then
45 `group d` is a document. When the printing engine encounters `group d`, two
46 possibilities arise. The first possibility is to print all of `d` on a single
47 line. This is known as flat mode. The engine tries this first (ignoring any
48 `group` combinators inside `d`). If it succeeds, great. If it fails, by lack
49 of space on the current line, then the engine backtracks and reverts to the
50 second possibility, which is to simply ignore the `group` combinator, and just
51 print `d`. This has subtle consequences: there might be further groups inside
52 `d`, and each of these groups will give rise to further choices.
53
54 This gives rise to an interesting language, where `group` is used to indicate
55 a choice point, and the appearance of `break` is dependent upon the choice
56 point(s) that appear higher up in the hierarchical structure of the document.
57 For instance, the document:
58
59 ```ocaml
60 group (string "This" ^^ break 1 ^^ string "is" ^^ break 1 ^^ string "pretty.")
61 ```
62
63 will be printed either on a single line, if it fits, or on three lines. It
64 will not be printed on two lines: there is just one choice point, so either
65 the two breakable spaces will be broken, or none of them will. By the way,
66 this document can be abbreviated as follows:
67
68 ```ocaml
69 group (string "This" ^/^ string "is" ^/^ string "pretty.")
70 ```
71
72 On the other hand, the document:
73
74 ```ocaml
75 string "This" ^^
76 group (break 1 ^^ string "is") ^^
77 group (break 1 ^^ string "pretty.")
78 ```
79
80 could be printed on one, two, or three lines. There are two choice points,
81 each of which influences one of the two breakable spaces. The two choices are
82 independent of one another. Each of the words in the sentence `This is
83 pretty.` will be printed on the current line if it fits, and on a new line
84 otherwise. By the way, this document can be abbreviated as follows:
85
86 ```ocaml
87 flow (break 1) [
88 string "This" ;
89 string "is" ;
90 string "pretty."
91 ]
92 ```
93
94 There are more combinators, such as `nest`, which controls indentation, and
95 it is relatively easy to roll your own combinators on top of those that are
96 provided.
97
98 One limitation of the library is that the document must be entirely built in
99 memory before it is printed. So far, we have used the library in small- to
100 medium-scale applications, and this has not been a problem. In principle,
101 one could work around this limitation by adding a new document constructor
102 whose argument is a suspended document computation.
103
104 ## Acknowledgements
105
106 The document language and the printing engine are inspired by Daan Leijen's
107 [PPrint](http://www.cs.uu.nl/~daan/pprint.html)
108 library, which itself is based on the ideas developed by Philip
109 Wadler in the paper
110 [A Prettier Printer](http://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf).
111
112 _**PPrint**_ was written by François Pottier and Nicolas Pouillard, with
113 contributions by Yann Régis-Gianas, Gabriel Scherer, and Jonathan
114 Protzenko.
115
116
117 ## Installation
118
119 The library is available online
120 ([source code](http://gallium.inria.fr/~fpottier/pprint/pprint.tar.gz),
121 [documentation](http://gallium.inria.fr/~fpottier/pprint/doc/)),
122 and can also be installed via OPAM: just type `opam install pprint`
123 if you already have a working OPAM installation.
124
125 Have fun! Feel free to make comments, suggestions, and to let me know if
126 and how you are using this library.
127