Portability | portable |
---|---|

Stability | provisional |

Maintainer | Ivan.Miljenovic@gmail.com |

Safe Haskell | None |

This module provides a version of
Text.PrettyPrint.Leijen.Text where the combinators have been
lifted into a `Monad`

. The main usage for this is for state-based
pretty-printing.

- data Doc
- empty :: Monad m => m Doc
- char :: Monad m => Char -> m Doc
- text :: Monad m => Text -> m Doc
- (<>) :: Monad m => m Doc -> m Doc -> m Doc
- nest :: Monad m => Int -> m Doc -> m Doc
- line :: Monad m => m Doc
- linebreak :: Monad m => m Doc
- group :: Monad m => m Doc -> m Doc
- softline :: Monad m => m Doc
- softbreak :: Monad m => m Doc
- spacebreak :: Monad m => m Doc
- align :: Monad m => m Doc -> m Doc
- hang :: Monad m => Int -> m Doc -> m Doc
- indent :: Monad m => Int -> m Doc -> m Doc
- encloseSep :: Monad m => m Doc -> m Doc -> m Doc -> m [Doc] -> m Doc
- list :: Monad m => m [Doc] -> m Doc
- tupled :: Monad m => m [Doc] -> m Doc
- semiBraces :: Monad m => m [Doc] -> m Doc
- (<+>) :: Monad m => m Doc -> m Doc -> m Doc
- (<++>) :: Monad m => m Doc -> m Doc -> m Doc
- (<$>) :: Monad m => m Doc -> m Doc -> m Doc
- (</>) :: Monad m => m Doc -> m Doc -> m Doc
- (<$$>) :: Monad m => m Doc -> m Doc -> m Doc
- (<//>) :: Monad m => m Doc -> m Doc -> m Doc
- hsep :: Monad m => m [Doc] -> m Doc
- vsep :: Monad m => m [Doc] -> m Doc
- fillSep :: Monad m => m [Doc] -> m Doc
- sep :: Monad m => m [Doc] -> m Doc
- hcat :: Monad m => m [Doc] -> m Doc
- vcat :: Monad m => m [Doc] -> m Doc
- fillCat :: Monad m => m [Doc] -> m Doc
- cat :: Monad m => m [Doc] -> m Doc
- punctuate :: Monad m => m Doc -> m [Doc] -> m [Doc]
- fill :: Monad m => Int -> m Doc -> m Doc
- fillBreak :: Monad m => Int -> m Doc -> m Doc
- enclose :: Monad m => m Doc -> m Doc -> m Doc -> m Doc
- squotes :: Monad m => m Doc -> m Doc
- dquotes :: Monad m => m Doc -> m Doc
- parens :: Monad m => m Doc -> m Doc
- angles :: Monad m => m Doc -> m Doc
- braces :: Monad m => m Doc -> m Doc
- brackets :: Monad m => m Doc -> m Doc
- lparen :: Monad m => m Doc
- rparen :: Monad m => m Doc
- langle :: Monad m => m Doc
- rangle :: Monad m => m Doc
- lbrace :: Monad m => m Doc
- rbrace :: Monad m => m Doc
- lbracket :: Monad m => m Doc
- rbracket :: Monad m => m Doc
- squote :: Monad m => m Doc
- dquote :: Monad m => m Doc
- semi :: Monad m => m Doc
- colon :: Monad m => m Doc
- comma :: Monad m => m Doc
- space :: Monad m => m Doc
- dot :: Monad m => m Doc
- backslash :: Monad m => m Doc
- equals :: Monad m => m Doc
- string :: Monad m => Text -> m Doc
- int :: Monad m => Int -> m Doc
- integer :: Monad m => Integer -> m Doc
- float :: Monad m => Float -> m Doc
- double :: Monad m => Double -> m Doc
- rational :: Monad m => Rational -> m Doc
- bool :: Monad m => Bool -> m Doc
- column :: Monad m => m (Int -> Doc) -> m Doc
- nesting :: Monad m => m (Int -> Doc) -> m Doc
- width :: Monad m => m Doc -> m (Int -> Doc) -> m Doc
- class Pretty a where
- pretty :: a -> Doc
- prettyList :: [a] -> Doc

- prettyM :: (Pretty a, Monad m) => a -> m Doc
- data SimpleDoc
- renderPretty :: Float -> Int -> Doc -> SimpleDoc
- renderCompact :: Doc -> SimpleDoc
- renderOneLine :: Doc -> SimpleDoc
- displayB :: SimpleDoc -> Builder
- displayT :: SimpleDoc -> Text
- displayIO :: Handle -> SimpleDoc -> IO ()
- putDoc :: Doc -> IO ()
- hPutDoc :: Handle -> Doc -> IO ()

# Documents

The abstract data type `Doc`

represents pretty documents.

`Doc`

is an instance of the `Show`

class. `(show doc)`

pretty
prints document `doc`

with a page width of 100 characters and a
ribbon width of 40 characters.

show (text "hello" <$> text "world")

Which would return the string "hello\nworld", i.e.

hello world

# Basic combinators

empty :: Monad m => m DocSource

The empty document is, indeed, empty. Although `empty`

has no
content, it does have a 'height' of 1 and behaves exactly like
`(text "")`

(and is therefore not a unit of `<$>`

).

char :: Monad m => Char -> m DocSource

The document `(char c)`

contains the literal character `c`

. The
character shouldn't be a newline (`'\n'`

), the function `line`

should be used for line breaks.

text :: Monad m => Text -> m DocSource

The document `(text s)`

contains the literal string `s`

. The
string shouldn't contain any newline (`'\n'`

) characters. If the
string contains newline characters, the function `string`

should
be used.

(<>) :: Monad m => m Doc -> m Doc -> m DocSource

The document `(x <> y)`

concatenates document `x`

and document
`y`

. It is an associative operation having `empty`

as a left and
right unit. (infixr 6)

line :: Monad m => m DocSource

The `line`

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

behaves like ```
(text "
")
```

if the line break is undone by `group`

or if rendered with
`renderOneLine`

.

group :: Monad m => m Doc -> m DocSource

The `group`

combinator is used to specify alternative
layouts. The document `(group x)`

undoes all line breaks in
document `x`

. The resulting line is added to the current line if
that fits the page. Otherwise, the document `x`

is rendered
without any changes.

spacebreak :: Monad m => m DocSource

The document `spacebreak`

behaves like `space`

when rendered normally
but like `empty`

when using `renderCompact`

or `renderOneLine`

.

# Alignment

The combinators in this section can not 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.

align :: Monad m => m Doc -> m DocSource

The document `(align x)`

renders 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:

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

test = text "hi" <+> (text "nice" $$ text "world")

which will be laid out as:

hi nice world

hang :: Monad m => Int -> m Doc -> m DocSource

The hang combinator implements hanging indentation. The document
`(hang i x)`

renders document `x`

with a nesting level set to the
current column plus `i`

. The following example uses hanging
indentation for some text:

test = hang 4 (fillSep (map text (words "the hang combinator indents these words !")))

Which lays out on a page with a width of 20 characters as:

the hang combinator indents these words !

The `hang`

combinator is implemented as:

hang i x = align (nest i x)

indent :: Monad m => Int -> m Doc -> m DocSource

The document `(indent i x)`

indents document `x`

with `i`

spaces.

test = indent 4 (fillSep (map text (words "the indent combinator indents these words !")))

Which lays out with a page width of 20 as:

the indent combinator indents these words !

encloseSep :: Monad m => m Doc -> m Doc -> m Doc -> m [Doc] -> m DocSource

The document `(encloseSep l r sep xs)`

concatenates the documents
`xs`

separated by `sep`

and encloses the resulting document by
`l`

and `r`

. The documents are rendered horizontally if that fits
the page. Otherwise they are aligned vertically. All separators
are put in front of the elements. For example, the combinator
`list`

can be defined with `encloseSep`

:

list xs = encloseSep lbracket rbracket comma xs test = text "list" <+> (list (map int [10,200,3000]))

Which is laid out with a page width of 20 as:

list [10,200,3000]

But when the page width is 15, it is laid out as:

list [10 ,200 ,3000]

list :: Monad m => m [Doc] -> m DocSource

The document `(list xs)`

comma separates the documents `xs`

and
encloses them in square brackets. The documents are rendered
horizontally if that fits the page. Otherwise they are aligned
vertically. All comma separators are put in front of the
elements.

tupled :: Monad m => m [Doc] -> m DocSource

The document `(tupled xs)`

comma separates the documents `xs`

and
encloses them in parenthesis. The documents are rendered
horizontally if that fits the page. Otherwise they are aligned
vertically. All comma separators are put in front of the
elements.

semiBraces :: Monad m => m [Doc] -> m DocSource

The document `(semiBraces xs)`

separates the documents `xs`

with
semi colons and encloses them in braces. The documents are
rendered horizontally if that fits the page. Otherwise they are
aligned vertically. All semi colons are put in front of the
elements.

# Operators

(<+>) :: Monad m => m Doc -> m Doc -> m DocSource

The document `(x <+> y)`

concatenates document `x`

and `y`

with
a `space`

in between. (infixr 6)

(<++>) :: Monad m => m Doc -> m Doc -> m DocSource

The document `(x <++> y)`

concatenates document `x`

and `y`

with
a `spacebreak`

in between. (infixr 6)

(<$>) :: Monad m => m Doc -> m Doc -> m DocSource

The document `(x <$> y)`

concatenates document `x`

and `y`

with
a `line`

in between. (infixr 5)

(</>) :: Monad m => m Doc -> m Doc -> m DocSource

The document `(x </> y)`

concatenates document `x`

and `y`

with a `softline`

in between. This effectively puts `x`

and `y`

either next to each other (with a `space`

in between) or
underneath each other. (infixr 5)

(<$$>) :: Monad m => m Doc -> m Doc -> m DocSource

The document `(x <$$> y)`

concatenates document `x`

and `y`

with a `linebreak`

in between. (infixr 5)

(<//>) :: Monad m => m Doc -> m Doc -> m DocSource

The document `(x <//> y)`

concatenates document `x`

and `y`

with a `softbreak`

in between. This effectively puts `x`

and `y`

either right next to each other or underneath each other. (infixr
5)

# List combinators

hsep :: Monad m => m [Doc] -> m DocSource

The document `(hsep xs)`

concatenates all documents `xs`

horizontally with `(<+>)`

.

vsep :: Monad m => m [Doc] -> m DocSource

The document `(vsep xs)`

concatenates all documents `xs`

vertically with `(<$>)`

. If a `group`

undoes the line breaks
inserted by `vsep`

, all documents are separated with a space.

someText = map text (words ("text to lay out")) test = text "some" <+> vsep someText

This is laid out as:

some text to lay out

The `align`

combinator can be used to align the documents under
their first element

test = text "some" <+> align (vsep someText)

Which is printed as:

some text to lay out

fillSep :: Monad m => m [Doc] -> m DocSource

The document `(fillSep xs)`

concatenates documents `xs`

horizontally with `(<+>)`

as long as its fits the page, then
inserts a `line`

and continues doing that for all documents in
`xs`

.

fillSep xs = foldr (</>) empty xs

sep :: Monad m => m [Doc] -> m DocSource

The document `(sep xs)`

concatenates all documents `xs`

either
horizontally with `(<+>)`

, if it fits the page, or vertically
with `(<$>)`

.

sep xs = group (vsep xs)

hcat :: Monad m => m [Doc] -> m DocSource

The document `(hcat xs)`

concatenates all documents `xs`

horizontally with `(<>)`

.

vcat :: Monad m => m [Doc] -> m DocSource

The document `(vcat xs)`

concatenates all documents `xs`

vertically with `(<$$>)`

. If a `group`

undoes the line breaks
inserted by `vcat`

, all documents are directly concatenated.

fillCat :: Monad m => m [Doc] -> m DocSource

The document `(fillCat xs)`

concatenates documents `xs`

horizontally with `(<>)`

as long as its fits the page, then
inserts a `linebreak`

and continues doing that for all documents
in `xs`

.

fillCat xs = foldr (<//>) empty xs

cat :: Monad m => m [Doc] -> m DocSource

The document `(cat xs)`

concatenates all documents `xs`

either
horizontally with `(<>)`

, if it fits the page, or vertically
with `(<$$>)`

.

cat xs = group (vcat xs)

punctuate :: Monad m => m Doc -> m [Doc] -> m [Doc]Source

`(punctuate p xs)`

concatenates all documents in `xs`

with
document `p`

except for the last document.

someText = map text ["words","in","a","tuple"] test = parens (align (cat (punctuate comma someText)))

This is laid out on a page width of 20 as:

(words,in,a,tuple)

But when the page width is 15, it is laid out as:

(words, in, a, tuple)

(If you want put the commas in front of their elements instead of
at the end, you should use `tupled`

or, in general, `encloseSep`

.)

# Fillers

fill :: Monad m => Int -> m Doc -> m DocSource

The document `(fill i x)`

renders document `x`

. It then appends
`space`

s until the width is equal to `i`

. If the width of `x`

is
already larger, nothing is appended. This combinator is quite
useful in practice to output a list of bindings. The following
example demonstrates this.

types = [("empty","Doc") ,("nest","Int -> Doc -> Doc") ,("linebreak","Doc")] ptype (name,tp) = fill 6 (text name) <+> text "::" <+> text tp test = text "let" <+> align (vcat (map ptype types))

Which is laid out as:

let empty :: Doc nest :: Int -> Doc -> Doc linebreak :: Doc

fillBreak :: Monad m => Int -> m Doc -> m DocSource

The document `(fillBreak i x)`

first renders document `x`

. It
then appends `space`

s 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 previous example to use `fillBreak`

, we get a
useful variation of the previous output:

ptype (name,tp) = fillBreak 6 (text name) <+> text "::" <+> text tp

The output will now be:

let empty :: Doc nest :: Int -> Doc -> Doc linebreak :: Doc

# Bracketing combinators

enclose :: Monad m => m Doc -> m Doc -> m Doc -> m DocSource

The document `(enclose l r x)`

encloses document `x`

between
documents `l`

and `r`

using `(<>)`

.

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

squotes :: Monad m => m Doc -> m DocSource

Document `(squotes x)`

encloses document `x`

with single quotes
"'".

dquotes :: Monad m => m Doc -> m DocSource

Document `(dquotes x)`

encloses document `x`

with double quotes
'"'.

parens :: Monad m => m Doc -> m DocSource

Document `(parens x)`

encloses document `x`

in parenthesis, "("
and ")".

angles :: Monad m => m Doc -> m DocSource

Document `(angles x)`

encloses document `x`

in angles, "<" and
">".

braces :: Monad m => m Doc -> m DocSource

Document `(braces x)`

encloses document `x`

in braces, "{" and
"}".

brackets :: Monad m => m Doc -> m DocSource

Document `(brackets x)`

encloses document `x`

in square brackets,
"[" and "]".

# Character documents

space :: Monad m => m DocSource

The document `space`

contains a single space, " ".

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

# Primitive type documents

string :: Monad m => Text -> m DocSource

The document `(string s)`

concatenates all characters in `s`

using `line`

for newline characters and `char`

for all other
characters. It is used instead of `text`

whenever the text
contains newline characters.

integer :: Monad m => Integer -> m DocSource

The document `(integer i)`

shows the literal integer `i`

using
`text`

.

float :: Monad m => Float -> m DocSource

The document `(float f)`

shows the literal float `f`

using
`text`

.

double :: Monad m => Double -> m DocSource

The document `(double d)`

shows the literal double `d`

using
`text`

.

rational :: Monad m => Rational -> m DocSource

The document `(rational r)`

shows the literal rational `r`

using
`text`

.

# Position-based combinators

column :: Monad m => m (Int -> Doc) -> m DocSource

Specifies how to create the document based upon which column it is in.

nesting :: Monad m => m (Int -> Doc) -> m DocSource

Specifies how to nest the document based upon which column it is being nested in.

# Pretty class

The member `prettyList`

is only used to define the ```
instance
Pretty a => Pretty [a]
```

. In normal circumstances only the
`pretty`

function is used.

# Rendering

The data type `SimpleDoc`

represents rendered documents and is
used by the display functions.

The `Int`

in `SText`

contains the length of the string. The `Int`

in `SLine`

contains the indentation for that line. The library
provides two default display functions `displayS`

and
`displayIO`

. You can provide your own display function by writing
a function from a `SimpleDoc`

to your own output format.

renderPretty :: Float -> Int -> Doc -> SimpleDocSource

This is the default pretty printer which is used by `show`

,
`putDoc`

and `hPutDoc`

. `(renderPretty ribbonfrac width x)`

renders document `x`

with a page width of `width`

and a ribbon
width of `(ribbonfrac * width)`

characters. The ribbon width is
the maximal amount of non-indentation characters on a line. The
parameter `ribbonfrac`

should be between `0.0`

and `1.0`

. If it
is lower or higher, the ribbon width will be 0 or `width`

respectively.

renderCompact :: Doc -> SimpleDocSource

`(renderCompact x)`

renders document `x`

without adding any
indentation. Since no 'pretty' printing is involved, this
renderer is very fast. The resulting output contains fewer
characters than a pretty printed version and can be used for
output that is read by other programs.

renderOneLine :: Doc -> SimpleDocSource

`(renderOneLine x)`

renders document `x`

without adding any
indentation or newlines.

displayT :: SimpleDoc -> TextSource

`(displayT simpleDoc)`

takes the output `simpleDoc`

from a
rendering function and transforms it to a lazy `Text`

value.

showWidth :: Int -> Doc -> Text showWidth w x = displayT (renderPretty 0.4 w x)

displayIO :: Handle -> SimpleDoc -> IO ()Source

`(displayIO handle simpleDoc)`

writes `simpleDoc`

to the
file handle `handle`

. This function is used for example by
`hPutDoc`

:

hPutDoc handle doc = displayIO handle (renderPretty 0.4 100 doc)

The action `(putDoc doc)`

pretty prints document `doc`

to the
standard output, with a page width of 100 characters and a ribbon
width of 40 characters.

main :: IO () main = do{ putDoc (text "hello" <+> text "world") }

Which would output

hello world

hPutDoc :: Handle -> Doc -> IO ()Source

`(hPutDoc handle doc)`

pretty prints document `doc`

to the file
handle `handle`

with a page width of 100 characters and a ribbon
width of 40 characters.

main = do handle <- 'openFile' "MyFile" 'WriteMode' 'hPutDoc' handle ('vcat' ('map' 'text' ['T.pack' "vertical", 'T.pack' "text"])) 'hClose' handle