| 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 |
|