The abstract data type Doc ann represents pretty documents that have been annotated with data of type ann.

More specifically, a value of type Doc represents a non-empty set of possible layouts of a document. The layout functions select one of these possibilities, taking into account things like the width of the output document.

The annotation is an arbitrary piece of data associated with (part of) a document. Annotations may be used by the rendering backends in order to display output differently, such as

• color information (e.g. when rendering to the terminal)
• mouseover text (e.g. when rendering to rich HTML)
• whether to show something or not (to allow simple or detailed versions)

The simplest way to display a Doc is via the Show class.

>>> putStrLn (show (vsep ["hello", "world"]))
hello
world

Overloaded conversion to Doc.

Laws:

1. output should be pretty. :-)

>>> parens "·"
(·)

>>> brackets "·"
[·]

>>> angles "·"
<·>

>>> braces "·"
{·}

(enclose l r x) encloses document x between documents l and r using <>.

>>> enclose "A" "Z" "·"
A·Z

enclose l r x = l <> x <> r

(encloseSep l r sep xs) concatenates the documents xs separated by sep, and encloses the resulting document by l and r.

The documents are laid out horizontally if that fits the page:

>>> let doc = "list" <+> align (encloseSep lbracket rbracket comma (map pretty [1,20,300,4000]))
>>> putDocW 80 doc
list [1,20,300,4000]

If there is not enough space, then the input is split into lines entry-wise therwise they are laid out vertically, with separators put in the front:

>>> putDocW 10 doc
list [1
     ,20
     ,300
     ,4000]

Note that doc contains an explicit call to align so that the list items are aligned vertically.

For putting separators at the end of entries instead, have a look at punctuate.

(punctuate p xs) appends p to all but the last document in xs.

>>> let docs = punctuate comma (Util.words "lorem ipsum dolor sit amet")
>>> putDocW 80 (hsep docs)
lorem, ipsum, dolor, sit, amet

The separators are put at the end of the entries, which we can see if we position the result vertically:

>>> putDocW 20 (vsep docs)
lorem,
ipsum,
dolor,
sit,
amet

If you want put the commas in front of their elements instead of at the end, you should use tupled or, in general, encloseSep.

>>> comma
,

(nest i x) lays out the document x with the current nesting level (indentation of the following lines) increased by i. Negative values are allowed, and decrease the nesting level accordingly.

>>> vsep [nest 4 (vsep ["lorem", "ipsum", "dolor"]), "sit", "amet"]
lorem
    ipsum
    dolor
sit
amet

See also

• hang (nest relative to current cursor position instead of current nesting level)
• align (set nesting level to current cursor position)
• indent (increase indentation on the spot, padding with spaces).

Haskell-inspired variant of encloseSep with braces and comma as separator.

>>> let doc = list (map pretty [1,20,300,4000])

>>> putDocW 80 doc
[1, 20, 300, 4000]

>>> putDocW 10 doc
[ 1
, 20
, 300
, 4000 ]

Haskell-inspired variant of encloseSep with parentheses and comma as separator.

>>> let doc = tupled (map pretty [1,20,300,4000])

>>> putDocW 80 doc
(1, 20, 300, 4000)

>>> putDocW 10 doc
( 1
, 20
, 300
, 4000 )

Identity of mappend

>>> "Hello world" <> mempty
"Hello world"

An associative operation.

>>> [1,2,3] <> [4,5,6]
[1,2,3,4,5,6]

(indent i x) indents document x by i columns, starting from the current cursor position.

>>> let doc = reflow "The indent function indents these words!"
>>> putDocW 24 ("prefix" <> indent 4 doc)
prefix    The indent
          function
          indents these
          words!

indent i d = hang i ({i spaces} <> d)

(nest i x) lays out the document x with the current nesting level (indentation of the following lines) increased by i. Negative values are allowed, and decrease the nesting level accordingly.

>>> vsep [nest 4 (vsep ["lorem", "ipsum", "dolor"]), "sit", "amet"]
lorem
    ipsum
    dolor
sit
amet

See also

• hang (nest relative to current cursor position instead of current nesting level)
• align (set nesting level to current cursor position)
• indent (increase indentation on the spot, padding with spaces).

(hang i x) lays out the document x with a nesting level set to the current column plus i. Negative values are allowed, and decrease the nesting level accordingly.

>>> let doc = reflow "Indenting these words with hang"
>>> putDocW 24 ("prefix" <+> hang 4 doc)
prefix Indenting these
           words with
           hang

This differs from nest, which is based on the current nesting level plus i. When you're not sure, try the more efficient nest first. In our example, this would yield

>>> let doc = reflow "Indenting these words with nest"
>>> putDocW 24 ("prefix" <+> nest 4 doc)
prefix Indenting these
    words with nest

hang i doc = align (nest i doc)