The pretty printer provided by the
Pp module is intended for tree-like
structures. Documents are represented by an abstract type
t. A document
can be printed to a file or a string and during this process the pretty
printer decides about the final outcome of the document. The only parameter
it takes into account is the total line width and the number of characters a
A document of type
t can be very small entity like a single word.
Functions combine small documents to larger ones which then can be pretty
val empty :
emptyis used in one branch of an
x $ yconcatenates two documents
yinto a larger one. It does not introduce any space or other separation between the two original documents.
val text :
string -> t
textfunction turns a string into a document. The pretty printed representation of the resulting document is exactly the string
textwas applied to.
val break :
breakcan be either represented by a single space or a newline followed by a number of spaces. The pretty printer makes this decision based on the available space. So think of a
breakas a space that might come out as a newline. To give the pretty printer enough flexibility documents must be joined with
x $ break $ y.
val break_null :
breakexcept it does not insert anything when no newline is inserted.
val break_with :
string -> t
breakmy be not always appropriate. The function
break_with sbehaves like
breakexcept that it uses a user supplied string
sinstead of the space.
breaks not one by one but looks at all
breaks of a sub-document. Documents are structured into sub-documents by group-operators. Different group operators exist to control the behavior of the pretty printer.
breakas a newline it also prints some spaces after it to indent the following line. The number of spaces is controlled by the
nestoperator that takes a document as argument:
nest n d. All breaks turned to newlines inside document
dare followed by
nestoperator nests properly such that it takes the spaces introduced by
nests on the outer level also into account.
hgrpoperator creates a horizontal group. Breaks inside a
hgrpare never turned into newlines but always come out as spaces. This group has a very limited usefulness because it easily overruns any given line length.
vgrpoperator creates a vertical group. All
breaks inside a
vgrpare represented as newlines followed by spaces. Although all
breaks come out as newlines the indentation of lines inside the group may differ: nesting is independent of grouping and thus different nesting levels can be active in the same group. Because of the fixed pretty printing strategy
vgrps are used mostly at the top level of documents only.
agrpis the most versatile. Breaks inside this group are either all turned into newlines (followed by spaces), or into spaces. Subgroups are, of course, not affected but considered individually.
agrpis fixed for all breaks of the group. Inside a flexible group
breakis considered individually: when the document up to the next
breakfits into the current line the
breakcomes out as space. Otherwise it comes out as newline followed by spaces.
val to_string :
?width:int -> t -> string
val to_file :
?width:int -> out_channel -> t -> unit
list sep ffunction takes care to insert the separator only between objects but not at the end of the list. It creates a
sepseparated list. Individual items are printed using
f. For the common case where commas are used for separating we also provide an extra definition
x $ break $ yto insert a
breakit is convenient to define an operator for this:
x ^/ yjoins
fand enclosed by curly braces. Its body will be indented in case it does not fit on a single line. The default indentation is 4
hlist [x1,..,xn] = hgrp [x1; break; x2; ...; break; xn)
vlist [x1,..,xn] = vgrp [x1; break; x2; ...; break; xn)