This module is an extended implementation of the functional pretty printer given by Philip Wadler (1997):

     "A prettier printer"
     Draft paper, April 1997, revised March 1998.
     https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf

In their bare essence, the combinators given by Wadler are not expressive enough to describe some commonly occurring layouts. This library adds new primitives to describe these layouts and works well in practice.

The library is based on a single way to concatenate documents, which is associative and has both a left and right unit. This simple design leads to an efficient and short implementation. The simplicity is reflected in the predictable behaviour of the combinators which make them easy to use in practice.

A thorough description of the primitive combinators and their implementation can be found in Philip Wadler's paper. The main differences with his original paper are:

• The nil document is called empty.
• The above combinator is called <$>. The operator </> is used for soft line breaks.
• There are three new primitives: align, fill and fillBreak. These are very useful in practice.
• There are many additional useful combinators, like fillSep and list.
• There are two renderers: renderPretty for pretty printing, and renderCompact for quickly rendered, compact output more suitable for generating input to other programs.
• The pretty printing algorithm used by renderPretty extends the algorithm given by Wadler to take into account a "ribbon width", i.e., a desired maximum number of non-indentation characters to output on any one line.
• There are two displayers, displayS for strings and displayIO for file-based output.
• There is a Pretty class.
• The implementation uses optimised representations and strictness annotations.
• The library has been extended to allow formatting text for output to ANSI style consoles. New combinators allow control of foreground and background color and the ability to make parts of the text bold or underlined.

The combinators in this library satisfy many algebraic laws.

The concatenation operator <> is associative and has empty as a left and right unit:

x <> (y <> z)           = (x <> y) <> z
x <> empty              = x
empty <> x              = x

The text combinator is a homomorphism from string concatenation to document concatenation:

text (s ++ t)           = text s <> text t
text ""                 = empty

The char combinator behaves like one-element text:

char c                  = text [c]

The nest combinator is a homomorphism from addition to document composition. nest also distributes through document concatenation and is absorbed by text and align:

nest (i + j) x          = nest i (nest j x)
nest 0 x                = x
nest i (x <> y)         = nest i x <> nest i y
nest i empty            = empty
nest i (text s)         = text s
nest i (align x)        = align x

The group combinator is absorbed by empty. group is commutative with nest and align:

group empty             = empty
group (text s <> x)     = text s <> group x
group (nest i x)        = nest i (group x)
group (align x)         = align (group x)

The align combinator is absorbed by empty and text. align is idempotent:

align empty             = empty
align (text s)          = text s
align (align x)         = align x

From the laws of the primitive combinators, we can derive many other laws for the derived combinators. For example, the above operator <$> is defined as:

x <$> y                 = x <> line <> y

It follows that <$> is associative and that <$> and <> associate with each other:

x <$> (y <$> z)         = (x <$> y) <$> z
x <> (y <$> z)          = (x <> y) <$> z
x <$> (y <> z)          = (x <$> y) <> z

Similar laws also hold for the other line break operators </>, <$$>, and <//>.

The combinators in this section cannot be described by Wadler's original combinators. They align their output relative to the current output position — in contrast to nest which always aligns to the current nesting level. This deprives these combinators from being `optimal'. In practice however they prove to be very useful. The combinators in this section should be used with care, since they are more expensive than the other combinators. For example, align shouldn't be used to pretty print all top-level declarations of a language, but using hang for let expressions is fine.

This terminal formatting functionality is, as far as possible, portable across platforms with their varying terminals. However, note that to display ANSI colors and formatting will only be displayed on Windows consoles if the Doc value is output using the putDoc function or one of its friends. Rendering the Doc to a String and then outputing that will only work on Unix-style operating systems.