Prettyprinter

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"]))helloworld

Overloaded conversion to Doc.

Laws:

1. output should be pretty. :-)

Convenience function to convert a Showable value to a Doc. If the String does not contain newlines, consider using the more performant unsafeViaShow.

Convenience function to convert a Showable value /that must not contain newlines/ to a Doc. If there may be newlines, use viaShow instead.

The empty document behaves like (pretty ""), so it has a height of 1. This may lead to surprising behaviour if we expect it to bear no weight inside e.g. vcat, where we get an empty line of output from it (parens for visibility only):

>>> vsep ["hello", parens emptyDoc, "world"]hello()world

Together with <>, emptyDoc forms the Monoid Doc.

(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    dolorsitamet

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).

The line document advances to the next line and indents to the current nesting level.

>>> let doc = "lorem ipsum" <> line <> "dolor sit amet">>> doclorem ipsumdolor sit amet

line behaves like space if the line break is undone by group:

>>> group doclorem ipsum dolor sit amet

line' is like line, but behaves like mempty if the line break is undone by group (instead of space).

>>> let doc = "lorem ipsum" <> line' <> "dolor sit amet">>> doclorem ipsumdolor sit amet>>> group doclorem ipsumdolor sit amet

softline behaves like space if the resulting output fits the page, otherwise like line.

Here, we have enough space to put everything in one line:

>>> let doc = "lorem ipsum" <> softline <> "dolor sit amet">>> putDocW 80 doclorem ipsum dolor sit amet

If we narrow the page to width 10, the layouter produces a line break:

>>> putDocW 10 doclorem ipsumdolor sit amet

softline = group line

softline' is like softline, but behaves like mempty if the resulting output does not fit on the page (instead of space). In other words, line is to line' how softline is to softline'.

With enough space, we get direct concatenation:

>>> let doc = "ThisWord" <> softline' <> "IsWayTooLong">>> putDocW 80 docThisWordIsWayTooLong

If we narrow the page to width 10, the layouter produces a line break:

>>> putDocW 10 docThisWordIsWayTooLong

softline' = group line'

A hardline is always laid out as a line break, even when grouped or when there is plenty of space. Note that it might still be simply discarded if it is part of a flatAlt inside a group.

>>> let doc = "lorem ipsum" <> hardline <> "dolor sit amet">>> putDocW 1000 doclorem ipsumdolor sit amet

>>> group doclorem ipsumdolor sit amet

(align x) lays out the document x with the nesting level set to the current column. It is used for example to implement hang.

As an example, we will put a document right above another one, regardless of the current nesting level. Without alignment, the second line is put simply below everything we've had so far:

>>> "lorem" <+> vsep ["ipsum", "dolor"]lorem ipsumdolor

If we add an align to the mix, the vsep's contents all start in the same column:

>>> "lorem" <+> align (vsep ["ipsum", "dolor"])lorem ipsum      dolor

(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)

(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)

(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 doclist [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 doclist [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.

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 )

An associative operation.

Examples

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

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

>>> putStr "Hello, " <> putStrLn "World!"Hello, World!

(x <+> y) concatenates document x and y with a space in between.

>>> "hello" <+> "world"hello world

x <+> y = x <> space <> y

Concatenate all documents element-wise with a binary function.

concatWith _ [] = mempty
concatWith (**) [x,y,z] = x ** y ** z

Multiple convenience definitions based on concatWith are already predefined, for example:

hsep    = concatWith (<+>)
fillSep = concatWith (\x y -> x <> softline <> y)

This is also useful to define customized joiners:

>>> concatWith (surround dot) ["Prettyprinter", "Render", "Text"]Prettyprinter.Render.Text

Layout a document depending on which column it starts at. align is implemented in terms of column.

>>> column (\l -> "Columns are" <+> pretty l <> "-based.")Columns are 0-based.

>>> let doc = "prefix" <+> column (\l -> "| <- column" <+> pretty l)>>> vsep [indent n doc | n <- [0,4,8]]prefix | <- column 7    prefix | <- column 11        prefix | <- column 15

Layout a document depending on the current nesting level. align is implemented in terms of nesting.

>>> let doc = "prefix" <+> nesting (\l -> brackets ("Nested:" <+> pretty l))>>> vsep [indent n doc | n <- [0,4,8]]prefix [Nested: 0]    prefix [Nested: 4]        prefix [Nested: 8]

(width doc f) lays out the document doc, and makes the column width of it available to a function.

>>> let annotate doc = width (brackets doc) (\w -> " <- width:" <+> pretty w)>>> align (vsep (map annotate ["---", "------", indent 3 "---", vsep ["---", indent 4 "---"]]))[---] <- width: 5[------] <- width: 8[   ---] <- width: 8[---    ---] <- width: 8

Layout a document depending on the page width, if one has been specified.

>>> let prettyPageWidth (AvailablePerLine l r) = "Width:" <+> pretty l <> ", ribbon fraction:" <+> pretty r>>> let doc = "prefix" <+> pageWidth (brackets . prettyPageWidth)>>> putDocW 32 (vsep [indent n doc | n <- [0,4,8]])prefix [Width: 32, ribbon fraction: 1.0]    prefix [Width: 32, ribbon fraction: 1.0]        prefix [Width: 32, ribbon fraction: 1.0]

(fill i x) lays out the document x. It then appends spaces until the width is equal to i. If the width of x is already larger, nothing is appended.

This function is quite useful in practice to output a list of bindings:

>>> let types = [("empty","Doc"), ("nest","Int -> Doc -> Doc"), ("fillSep","[Doc] -> Doc")]>>> let ptype (name, tp) = fill 5 (pretty name) <+> "::" <+> pretty tp>>> "let" <+> align (vcat (map ptype types))let empty :: Doc    nest  :: Int -> Doc -> Doc    fillSep :: [Doc] -> Doc

(fillBreak i x) first lays out the document x. It then appends spaces until the width is equal to i. If the width of x is already larger than i, the nesting level is increased by i and a line is appended. When we redefine ptype in the example given in fill to use fillBreak, we get a useful variation of the output:

>>> let types = [("empty","Doc"), ("nest","Int -> Doc -> Doc"), ("fillSep","[Doc] -> Doc")]>>> let ptype (name, tp) = fillBreak 5 (pretty name) <+> "::" <+> pretty tp>>> "let" <+> align (vcat (map ptype types))let empty :: Doc    nest  :: Int -> Doc -> Doc    fillSep          :: [Doc] -> Doc

(plural n one many) is one if n is 1, and many otherwise. A typical use case is adding a plural "s".

>>> let things = [True]>>> let amount = length things>>> pretty things <+> "has" <+> pretty amount <+> plural "entry" "entries" amount[True] has 1 entry

(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

(surround x l r) surrounds document x with l and r.

>>> surround "·" "A" "Z"A·Z

This is merely an argument reordering of enclose, but allows for definitions like

>>> concatWith (surround dot) ["Prettyprinter", "Render", "Text"]Prettyprinter.Render.Text

>>> "a" <> space <> "b"a b

This is mostly used via <+>,

>>> "a" <+> "b"a b

(fuse depth doc) combines text nodes so they can be rendered more efficiently. A fused document is always laid out identical to its unfused version.

When laying a Document out to a SimpleDocStream, every component of the input is translated directly to the simpler output format. This sometimes yields undesirable chunking when many pieces have been concatenated together.

For example

>>> "a" <> "b" <> pretty 'c' <> "d"abcd

results in a chain of four entries in a SimpleDocStream, although this is fully equivalent to the tightly packed

>>> "abcd" :: Doc annabcd

which is only a single SimpleDocStream entry, and can be processed faster.

It is therefore a good idea to run fuse on concatenations of lots of small strings that are used many times:

>>> let oftenUsed = fuse Shallow ("a" <> "b" <> pretty 'c' <> "d")>>> hsep (replicate 5 oftenUsed)abcd abcd abcd abcd abcd

Fusion depth parameter, used by fuse.

The data type SimpleDocStream represents laid out documents and is used by the display functions.

A simplified view is that Doc = [SimpleDocStream], and the layout functions pick one of the SimpleDocStreams based on which one fits the layout constraints best. This means that SimpleDocStream has all complexity contained in Doc resolved, making it very easy to convert it to other formats, such as plain text or terminal output.

To write your own Doc to X converter, it is therefore sufficient to convert from SimpleDocStream. The »Render« submodules provide some built-in converters to do so, and helpers to create own ones.

Maximum number of characters that fit in one line. The layout algorithms will try not to exceed the set limit by inserting line breaks when applicable (e.g. via softline').

Options to influence the layout algorithms.

The default layout options, suitable when you just want some output, and don’t particularly care about the details. Used by the Show instance, for example.

>>> defaultLayoutOptionsLayoutOptions {layoutPageWidth = AvailablePerLine 80 1.0}

This is the default layout algorithm, and it is used by show, putDoc and hPutDoc.

layoutPretty commits to rendering something in a certain way if the next element fits the layout constraints; in other words, it has one SimpleDocStream element lookahead when rendering. Consider using the smarter, but a bit less performant, layoutSmart algorithm if the results seem to run off to the right before having lots of line breaks.

(layoutCompact x) lays out the document x without adding any indentation and without preserving annotations. Since no 'pretty' printing is involved, this layouter is very fast. The resulting output contains fewer characters than a prettyprinted version and can be used for output that is read by other programs.

>>> let doc = hang 4 (vsep ["lorem", "ipsum", hang 4 (vsep ["dolor", "sit"])])>>> doclorem    ipsum    dolor        sit

>>> let putDocCompact = renderIO System.IO.stdout . layoutCompact>>> putDocCompact docloremipsumdolorsit

A layout algorithm with more lookahead than layoutPretty, that introduces line breaks earlier if the content does not (or will not, rather) fit into one line.

Consider the following python-ish document,

>>> let fun x = hang 2 ("fun(" <> softline' <> x) <> ")">>> let doc = (fun . fun . fun . fun . fun) (align (list ["abcdef", "ghijklm"]))

which we’ll be rendering using the following pipeline (where the layout algorithm has been left open):

>>> import Data.Text.IO as T>>> import Prettyprinter.Render.Text>>> let hr = pipe <> pretty (replicate (26-2) '-') <> pipe>>> let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])

If we render this using layoutPretty with a page width of 26 characters per line, all the fun calls fit into the first line so they will be put there:

>>> go layoutPretty doc|------------------------|fun(fun(fun(fun(fun(                  [ abcdef                  , ghijklm ])))))|------------------------|

Note that this exceeds the desired 26 character page width. The same document, rendered with layoutSmart, fits the layout contstraints:

>>> go layoutSmart doc|------------------------|fun(  fun(    fun(      fun(        fun(          [ abcdef          , ghijklm ])))))|------------------------|

The key difference between layoutPretty and layoutSmart is that the latter will check the potential document until it encounters a line with the same indentation or less than the start of the document. Any line encountered earlier is assumed to belong to the same syntactic structure. layoutPretty checks only the first line.

Consider for example the question of whether the As fit into the document below:

1 A
2   A
3  A
4 B
5   B

layoutPretty will check only line 1, ignoring whether e.g. line 2 might already be too wide. By contrast, layoutSmart stops only once it reaches line 4, where the B has the same indentation as the first A.

Remove all trailing space characters.

This has some performance impact, because it does an entire additional pass over the SimpleDocStream.

No trimming will be done inside annotations, which are considered to contain no (trimmable) whitespace, since the annotation might actually be about the whitespace, for example a renderer that colors the background of trailing whitespace, as e.g. git diff can be configured to do.

Historical note: Since v1.7.0, layoutPretty and layoutSmart avoid producing the trailing whitespace that was the original motivation for creating removeTrailingWhitespace. See https://github.com/quchen/prettyprinter/pull/139 for some background info.