Text.PrettyPrint.ANSI.Leijen

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.