Text.PrettyPrint.Compact

Compact pretty-printer.

Examples

Assume that we want to pretty print S-Expressions, which can either be atom or a list of S-Expressions.

>>> data SExpr = SExpr [SExpr] | Atom String deriving Show
>>> let pretty :: SExpr -> Doc (); pretty (Atom s) = text s; pretty (SExpr xs) = text "(" <> (sep $ map pretty xs) <> text ")"

Using the above representation, the S-Expression (a b c d) has the following encoding:

>>> let abcd = SExpr [Atom "a",Atom "b",Atom "c",Atom "d"]

The legible layouts of the abcd S-Expression defined above would be either

>>> putStrLn $ render $ pretty abcd
(a b c d)

or

>>> putStrLn $ renderWith defaultOptions { optsPageWidth = 5 } $ pretty abcd
(a
 b
 c
 d)

The testData S-Expression is specially crafted to demonstrate general shortcomings of both Hughes and Wadler libraries.

>>> let abcd4 = SExpr [abcd,abcd,abcd,abcd]
>>> let testData = SExpr [ SExpr [Atom "abcde", abcd4], SExpr [Atom "abcdefgh", abcd4]]
>>> putStrLn $ render $ pretty testData
((abcde ((a b c d) (a b c d) (a b c d) (a b c d)))
 (abcdefgh ((a b c d) (a b c d) (a b c d) (a b c d))))

on 20-column-wide page

>>> putStrLn $ renderWith defaultOptions { optsPageWidth = 20 } $ pretty testData
((abcde ((a b c d)
         (a b c d)
         (a b c d)
         (a b c d)))
 (abcdefgh
  ((a b c d)
   (a b c d)
   (a b c d)
   (a b c d))))

Yet, neither Hughes' nor Wadler's library can deliver those results.

Annotations

For example we can annotate every car element of S-Expressions, and in the rendering phase emphasise them by rendering them in uppercase.

>>> let pretty' :: SExpr -> Doc Any; pretty' (Atom s) = text s; pretty' (SExpr []) = text "()"; pretty' (SExpr (x:xs)) = text "(" <> (sep $ annotate (Any True) (pretty' x) : map pretty' xs) <> text ")"
>>> let render' = renderWith defaultOptions { optsAnnotate  = \a x -> if a == Any True then map toUpper x else x }
>>> putStrLn $ render' $ pretty' testData
((ABCDE ((A B C D) (A B C D) (A B C D) (A B C D)))
 (ABCDEFGH ((A B C D) (A b c d) (A b c d) (A b c d))))

Documents

type Doc = DDoc

Basic combinators

module Data.Monoid

text :: (Layout d, Monoid a) => String -> d a

flush :: (Layout d, Monoid a) => d a -> d a

char :: Annotation a => Char -> Doc a

hang :: Annotation a => Int -> Doc a -> Doc a -> Doc a

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)

encloseSep :: Annotation a => Doc a -> Doc a -> Doc a -> [Doc a] -> Doc a

The document (enclosure 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 enclosure:

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

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

list [10,200,3000]

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

list [10
     ,200
     ,3000]

list :: Annotation a => [Doc a] -> Doc a

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 :: Annotation a => [Doc a] -> Doc a

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 :: Annotation a => [Doc a] -> Doc a

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

(<+>) :: Annotation a => Doc a -> Doc a -> Doc a

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

($$) :: Annotation a => Doc a -> Doc a -> Doc a

The document (x <$$> y) concatenates document x and y with a linebreak in between. (infixr 5)

(</>) :: Annotation a => Doc a -> Doc a -> Doc a

The document (x </> y) puts x and y either next to each other (with a space in between) if x fits on a single line, or underneath each other. (infixr 5)

(<//>) :: Annotation a => Doc a -> Doc a -> Doc a

The document (x <//> y) puts x and y either right next to each other (if x fits on a single line) or underneath each other. (infixr 5)

(<$$>) :: Annotation a => Doc a -> Doc a -> Doc a

The document (x <$$> y) concatenates document x and y with a linebreak in between. (infixr 5)

(<|>) :: (Document d, Eq a) => d a -> d a -> d a

List combinators

hsep :: Annotation a => [Doc a] -> Doc a

The document (hsep xs) concatenates all documents xs horizontally with (<+>).

sep :: Annotation a => [Doc a] -> Doc a

The document (sep xs) concatenates all documents xs either horizontally with (<+>), if it fits the page, or vertically with (<$>).

hcat :: Annotation a => [Doc a] -> Doc a

The document (hcat xs) concatenates all documents xs horizontally with (<->).

vcat :: Annotation a => [Doc a] -> Doc a

The document (vcat xs) concatenates all documents xs vertically with ($$).

cat :: Annotation a => [Doc a] -> Doc a

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 :: Annotation a => Doc a -> [Doc a] -> [Doc a]

(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 layed out on a page width of 20 as:

(words,in,a,tuple)

But when the page width is 15, it is layed 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.)

Fill combiantors

fillSep :: Annotation a => [Doc a] -> Doc a

The document (fillSep xs) concatenates documents xs horizontally with (<+>) as long as its fits the page, than inserts a line and continues doing that for all documents in xs.

fillSep xs  = foldr (\<\/\>) empty xs

fillCat :: Annotation a => [Doc a] -> Doc a

The document (fillCat xs) concatenates documents xs horizontally with (<>) as long as its fits the page, than inserts a linebreak and continues doing that for all documents in xs.

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

Bracketing combinators

enclose :: Annotation a => Doc a -> Doc a -> Doc a -> Doc a

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

squotes :: Annotation a => Doc a -> Doc a

Document (squotes x) encloses document x with single quotes "'".

dquotes :: Annotation a => Doc a -> Doc a

Document (dquotes x) encloses document x with double quotes '"'.

parens :: Annotation a => Doc a -> Doc a

Document (parens x) encloses document x in parenthesis, "(" and ")".

angles :: Annotation a => Doc a -> Doc a

Document (angles x) encloses document x in angles, "<" and ">".

braces :: Annotation a => Doc a -> Doc a

Document (braces x) encloses document x in braces, "{" and "}".

brackets :: Annotation a => Doc a -> Doc a

Document (brackets x) encloses document x in square brackets, "[" and "]".

Character documents

lparen :: Annotation a => Doc a

The document lparen contains a left parenthesis, "(".

rparen :: Annotation a => Doc a

The document rparen contains a right parenthesis, ")".

langle :: Annotation a => Doc a

The document langle contains a left angle, "<".

rangle :: Annotation a => Doc a

The document rangle contains a right angle, ">".

lbrace :: Annotation a => Doc a

The document lbrace contains a left brace, "{".

rbrace :: Annotation a => Doc a

The document rbrace contains a right brace, "}".

lbracket :: Annotation a => Doc a

The document lbracket contains a left square bracket, "[".

rbracket :: Annotation a => Doc a

The document rbracket contains a right square bracket, "]".

squote :: Annotation a => Doc a

The document squote contains a single quote, "'".

dquote :: Annotation a => Doc a

The document dquote contains a double quote, '"'.

semi :: Annotation a => Doc a

The document semi contains a semi colon, ";".

colon :: Annotation a => Doc a

The document colon contains a colon, ":".

comma :: Annotation a => Doc a

The document comma contains a comma, ",".

space :: Annotation a => Doc a

The document (nest i x) renders document x with the current indentation level increased by i (See also hang, align and indent).

nest 2 (text "hello" <$$$> text "world") <$$$> text "!"

outputs as:

hello
  world
!

dot :: Annotation a => Doc a

The document dot contains a single dot, ".".

backslash :: Annotation a => Doc a

The document backslash contains a back slash, "\".

equals :: Annotation a => Doc a

The document equals contains an equal sign, "=".

Primitive type documents

string :: Annotation a => String -> Doc a

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.

int :: Annotation a => Int -> Doc a

The document (int i) shows the literal integer i using text.

integer :: Annotation a => Integer -> Doc a

The document (integer i) shows the literal integer i using text.

float :: Annotation a => Float -> Doc a

The document (float f) shows the literal float f using text.

double :: Annotation a => Double -> Doc a

The document (double d) shows the literal double d using text.

rational :: Annotation a => Rational -> Doc a

The document (rational r) shows the literal rational r using text.

bool :: Annotation a => Bool -> Doc a

Rendering

renderWith

Arguments

:: (Monoid r, Monoid a, Eq a)

=> Options a r

rendering options

-> Doc a

renderable

-> r

render :: Annotation a => Doc a -> String

Render the Doc into String omitting all annotations.

data Options a r

Constructors

Options

Fields

• optsPageWidth :: !Int

  maximum page width

• optsAnnotate :: a -> String -> r

  how to annotate the string. Note: the annotation should preserve the visible length of the string.

defaultOptions :: Options a String

Annotations

annotate :: forall a. (Layout d, Monoid a) => a -> d a -> d a

<> new annotation to the Doc.

Example: 'Any True' annotation will transform the rendered Doc into uppercase:

>>> let r = putStrLn . renderWith defaultOptions { optsAnnotate = \a x -> if a == Any True then map toUpper x else x }
>>> r $ text "hello" <$$> annotate (Any True) (text "world")
hello
WORLD

Undocumented