Utility functions for pretty-printing. The major features provided by
this module are

An fprintf-style interface with support for user-defined printers

The printout is fit to a width by selecting some of the optional newlines

Constructs for alignment and indentation

Print ellipsis starting at a certain nesting depth

Constructs for printing lists and arrays

Pretty-printing occurs in two stages:

Construct a Pretty.doc object that encodes all of the elements to be
printed
along with alignment specifiers and optional and mandatory newlines

Format the Pretty.doc to a certain width and emit it as a string, to an
output stream or pass it to a user-defined function

The formatting algorithm is not optimal but it does a pretty good job while
still operating in linear time. The original version was based on a pretty
printer by Philip Wadler which turned out to not scale to large jobs.
API

typedoc

The type of unformated documents. Elements of this type can be
constructed in two ways. Either with a number of constructor shown below,
or using the Pretty.dprintf function with a printf-like interface.
The Pretty.dprintf method is slightly slower so we do not use it for
large jobs such as the output routines for a compiler. But we use it for
small jobs such as logging and error messages.

A document that consists of either a space or a line break. Also called
an optional line break. Such a break will be
taken only if necessary to fit the document in a given width. If the break
is not taken a space is printed instead.

An alternative function for printing a list. The unit argument is there
to make this function more easily usable with the Pretty.dprintf
interface. The first argument is a separator, by default a comma.

sm: Yet another list printer. This one accepts the same kind of
printing function that Pretty.dprintf does, and itself works
in the dprintf context. Also accepts
a string as the separator since that's by far the most common.

This function provides an alternative method for constructing
doc objects. The first argument for this function is a format string
argument (of type ('a, unit, doc) format; if you insist on
understanding what that means see the module Printf). The format string
is like that for the printf function in C, except that it understands a
few more formatting controls, all starting with the @ character.

See the gprintf function if you want to pipe the result of dprintf into
some other functions.

The following special formatting characters are understood (these do not
correspond to arguments of the function):

In addition to the usual printf % formatting characters the following two
new characters are supported:

%t Corresponds to an argument of type unit -> doc. This argument is
invoked to produce a document

%a Corresponds to two arguments. The first of type unit -> 'a -> doc
and the second of type 'a. (The extra unit is do to the
peculiarities of the built-in support for format strings in Ocaml. It
turns out that it is not a major problem.) Here is an example of how
you use this:

Like Pretty.dprintf but more general. It also takes a function that is
invoked on the constructed document but before any formatting is done. The
type of the format argument means that 'a is the type of the parameters of
this function, unit is the type of the first argument to %a and %t
formats, doc is the type of the intermediate result, and 'b is the type of
the result of gprintf.