Portability | portable |
---|---|
Stability | provisional |
Maintainer | stefanor@cox.net |
Text.PrettyPrint.Leijen
Contents
Description
Pretty print module based on Philip Wadler's "prettier printer"
"A prettier printer" Draft paper, April 1997, revised March 1998. http://cm.bell-labs.com/cm/cs/who/wadler/papers/prettier/prettier.ps
PPrint is an implementation of the pretty printing combinators described by Philip Wadler (1997). In their bare essence, the combinators of Wadler are not expressive enough to describe some commonly occurring layouts. The PPrint library adds new primitives to describe these layouts and works well in practice.
The library is based on a single way to concatenate documents, which is associative and has both a left and right unit. This simple design leads to an efficient and short implementation. The simplicity is reflected in the predictable behaviour of the combinators which make them easy to use in practice.
A thorough description of the primitive combinators and their implementation can be found in Philip Wadler's paper (1997). Additions and the main differences with his original paper are:
- The nil document is called empty.
- The above combinator is called
<$>
. The operator</>
is used for soft line breaks. - There are three new primitives:
align
,fill
andfillBreak
. These are very useful in practice. - Lots of other useful combinators, like
fillSep
andlist
. - There are two renderers,
renderPretty
for pretty printing andrenderCompact
for compact output. The pretty printing algorithm also uses a ribbon-width now for even prettier output. - There are two displayers,
displayS
for strings anddisplayIO
for file based output. - There is a
Pretty
class. - The implementation uses optimised representations and strictness annotations.
Full documentation available at http://www.cs.uu.nl/~daan/download/pprint/pprint.html.
- data Doc
- putDoc :: Doc -> IO ()
- hPutDoc :: Handle -> Doc -> IO ()
- empty :: Doc
- char :: Char -> Doc
- text :: String -> Doc
- (<>) :: Doc -> Doc -> Doc
- nest :: Int -> Doc -> Doc
- line :: Doc
- linebreak :: Doc
- group :: Doc -> Doc
- softline :: Doc
- softbreak :: Doc
- align :: Doc -> Doc
- hang :: Int -> Doc -> Doc
- indent :: Int -> Doc -> Doc
- encloseSep :: Doc -> Doc -> Doc -> [Doc] -> Doc
- list :: [Doc] -> Doc
- tupled :: [Doc] -> Doc
- semiBraces :: [Doc] -> Doc
- (<+>) :: Doc -> Doc -> Doc
- (<$>) :: Doc -> Doc -> Doc
- (</>) :: Doc -> Doc -> Doc
- (<$$>) :: Doc -> Doc -> Doc
- (<//>) :: Doc -> Doc -> Doc
- hsep :: [Doc] -> Doc
- vsep :: [Doc] -> Doc
- fillSep :: [Doc] -> Doc
- sep :: [Doc] -> Doc
- hcat :: [Doc] -> Doc
- vcat :: [Doc] -> Doc
- fillCat :: [Doc] -> Doc
- cat :: [Doc] -> Doc
- punctuate :: Doc -> [Doc] -> [Doc]
- fill :: Int -> Doc -> Doc
- fillBreak :: Int -> Doc -> Doc
- enclose :: Doc -> Doc -> Doc -> Doc
- squotes :: Doc -> Doc
- dquotes :: Doc -> Doc
- parens :: Doc -> Doc
- angles :: Doc -> Doc
- braces :: Doc -> Doc
- brackets :: Doc -> Doc
- lparen :: Doc
- rparen :: Doc
- langle :: Doc
- rangle :: Doc
- lbrace :: Doc
- rbrace :: Doc
- lbracket :: Doc
- rbracket :: Doc
- squote :: Doc
- dquote :: Doc
- semi :: Doc
- colon :: Doc
- comma :: Doc
- space :: Doc
- dot :: Doc
- backslash :: Doc
- equals :: Doc
- string :: String -> Doc
- int :: Int -> Doc
- integer :: Integer -> Doc
- float :: Float -> Doc
- double :: Double -> Doc
- rational :: Rational -> Doc
- class Pretty a where
- pretty :: a -> Doc
- prettyList :: [a] -> Doc
- data SimpleDoc
- renderPretty :: Float -> Int -> Doc -> SimpleDoc
- renderCompact :: Doc -> SimpleDoc
- displayS :: SimpleDoc -> ShowS
- displayIO :: Handle -> SimpleDoc -> IO ()
- bool :: Bool -> Doc
- column :: (Int -> Doc) -> Doc
- nesting :: (Int -> Doc) -> Doc
- width :: Doc -> (Int -> Doc) -> Doc
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
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 ["vertical","text"])) ; hClose handle }
Basic combinators
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 <$>
).
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.
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.
(<>) :: Doc -> Doc -> 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)
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
.
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.
Alignment
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 layed out as:
hi nice world
hang :: Int -> Doc -> 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 :: Int -> Doc -> 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 :: Doc -> Doc -> Doc -> [Doc] -> 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 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]
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.
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 :: [Doc] -> 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
(<+>) :: Doc -> Doc -> DocSource
The document (x <+> y)
concatenates document x
and y
with a
space
in between. (infixr 6)
(<$>) :: Doc -> Doc -> DocSource
The document (x <$> y)
concatenates document x
and y
with a
line
in between. (infixr 5)
(</>) :: Doc -> Doc -> 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)
(<$$>) :: Doc -> Doc -> DocSource
The document (x <$$> y)
concatenates document x
and y
with
a linebreak
in between. (infixr 5)
(<//>) :: Doc -> Doc -> 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
The document (hsep xs)
concatenates all documents xs
horizontally with (<+>)
.
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 layed 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
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
The document (sep xs)
concatenates all documents xs
either
horizontally with (<+>)
, if it fits the page, or vertically with
(<$>)
.
sep xs = group (vsep xs)
The document (hcat xs)
concatenates all documents xs
horizontally with (<>)
.
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.
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
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 :: Doc -> [Doc] -> [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 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
.)
Fillers
fill :: Int -> Doc -> DocSource
The document (fill i x)
renders document x
. It than 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 layed out as:
let empty :: Doc nest :: Int -> Doc -> Doc linebreak :: Doc
fillBreak :: Int -> Doc -> DocSource
The document (fillBreak i x)
first renders document x
. It
than 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 :: Doc -> Doc -> Doc -> DocSource
The document (enclose l r x)
encloses document x
between
documents l
and r
using (<>)
.
enclose l r x = l <> x <> r
Document (brackets x)
encloses document x
in square brackets,
"[" and "]".
Character documents
Primitive type documents
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.
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.
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)