| Copyright | Google Inc. (c) 2013 Edward Kmett (c) 2011 Daan Leijen (c) 2000 |
|---|---|
| License | BSD-style (see the file LICENSE) |
| Maintainer | mail@daniel-mendler.de |
| Stability | experimental |
| Portability | portable |
| Safe Haskell | Safe |
| Language | Haskell2010 |
Text.PrettyPrint.Annotated.WL
Contents
Description
Pretty print module based on Daan Leijen's implementation of Philip Wadler's "prettier printer"
"A prettier printer"
Draft paper, April 1997, revised March 1998.
http://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf
This 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 mempty.
- The operator
</>is used for soft line breaks. - There are three new primitives:
align,fillandfillBreak. These are very useful in practice. - Lots of other useful combinators, like
fillSepandlist. - There are two renderers,
renderPrettyfor pretty printing andrenderCompactfor compact output. The pretty printing algorithm also uses a ribbon-width now for even prettier output. - There are two display routines,
displaySfor strings anddisplayIOfor file based output. - There is a
Prettyclass. - The implementation uses optimised representations and strictness annotations.
- type Doc = ADoc Void
- data ADoc a
- putDoc :: ADoc a -> IO ()
- hPutDoc :: Handle -> ADoc a -> IO ()
- char :: Char -> ADoc a
- text :: String -> ADoc a
- nest :: Int -> ADoc a -> ADoc a
- line :: ADoc a
- linebreak :: ADoc a
- group :: ADoc a -> ADoc a
- softline :: ADoc a
- softbreak :: ADoc a
- hardline :: ADoc a
- flatAlt :: ADoc a -> ADoc a -> ADoc a
- flatten :: ADoc a -> ADoc a
- annotate :: a -> ADoc a -> ADoc a
- noAnnotate :: ADoc a -> ADoc a'
- docMapAnn :: (a -> ADoc a' -> ADoc a') -> ADoc a -> ADoc a'
- simpleDocMapAnn :: (r -> a -> r) -> (r -> SimpleDoc a' -> SimpleDoc a') -> (r -> SimpleDoc a' -> SimpleDoc a') -> r -> SimpleDoc a -> SimpleDoc a'
- simpleDocScanAnn :: (r -> a -> r) -> r -> SimpleDoc a -> SimpleDoc r
- align :: ADoc a -> ADoc a
- hang :: Int -> ADoc a -> ADoc a
- indent :: Int -> ADoc a -> ADoc a
- encloseSep :: Foldable f => ADoc a -> ADoc a -> ADoc a -> f (ADoc a) -> ADoc a
- list :: Foldable f => f (ADoc a) -> ADoc a
- tupled :: Foldable f => f (ADoc a) -> ADoc a
- semiBraces :: Foldable f => f (ADoc a) -> ADoc a
- (<+>) :: ADoc a -> ADoc a -> ADoc a
- (</>) :: ADoc a -> ADoc a -> ADoc a
- (<//>) :: ADoc a -> ADoc a -> ADoc a
- (<#>) :: ADoc a -> ADoc a -> ADoc a
- (<##>) :: ADoc a -> ADoc a -> ADoc a
- hsep :: Foldable f => f (ADoc a) -> ADoc a
- vsep :: Foldable f => f (ADoc a) -> ADoc a
- fillSep :: Foldable f => f (ADoc a) -> ADoc a
- sep :: Foldable f => f (ADoc a) -> ADoc a
- hcat :: Foldable f => f (ADoc a) -> ADoc a
- vcat :: Foldable f => f (ADoc a) -> ADoc a
- fillCat :: Foldable f => f (ADoc a) -> ADoc a
- cat :: Foldable f => f (ADoc a) -> ADoc a
- punctuate :: Traversable f => ADoc a -> f (ADoc a) -> f (ADoc a)
- fill :: Int -> ADoc a -> ADoc a
- fillBreak :: Int -> ADoc a -> ADoc a
- enclose :: ADoc a -> ADoc a -> ADoc a -> ADoc a
- squotes :: ADoc a -> ADoc a
- dquotes :: ADoc a -> ADoc a
- parens :: ADoc a -> ADoc a
- angles :: ADoc a -> ADoc a
- braces :: ADoc a -> ADoc a
- brackets :: ADoc a -> ADoc a
- lparen :: ADoc a
- rparen :: ADoc a
- langle :: ADoc a
- rangle :: ADoc a
- lbrace :: ADoc a
- rbrace :: ADoc a
- lbracket :: ADoc a
- rbracket :: ADoc a
- squote :: ADoc a
- dquote :: ADoc a
- semi :: ADoc a
- colon :: ADoc a
- comma :: ADoc a
- space :: ADoc a
- dot :: ADoc a
- backslash :: ADoc a
- equals :: ADoc a
- class Pretty a where
- data SimpleDoc a
- renderPretty :: Float -> Int -> ADoc a -> SimpleDoc a
- renderCompact :: ADoc a -> SimpleDoc a
- renderSmart :: Int -> ADoc a -> SimpleDoc a
- display :: SimpleDoc a -> String
- displayS :: SimpleDoc a -> ShowS
- displayLT :: SimpleDoc a -> Text
- displayIO :: Handle -> SimpleDoc a -> IO ()
- displayDecoratedA :: (Applicative f, Monoid o) => (a -> f o) -> (a -> f o) -> (String -> f o) -> SimpleDoc a -> f o
- displayDecorated :: Monoid o => (a -> o) -> (a -> o) -> (String -> o) -> SimpleDoc a -> o
- type SpanList a = [(Int, Int, a)]
- displaySpans :: Monoid o => (String -> o) -> SimpleDoc a -> (o, SpanList a)
- column :: (Int -> ADoc a) -> ADoc a
- nesting :: (Int -> ADoc a) -> ADoc a
- width :: ADoc a -> (Int -> ADoc a) -> ADoc a
- columns :: (Maybe Int -> ADoc a) -> ADoc a
- ribbon :: (Maybe Int -> ADoc a) -> ADoc a
- mempty :: Monoid a => a
- (<>) :: Semigroup a => a -> a -> a
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
putDoc :: ADoc a -> IO () Source #
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 -> ADoc a -> 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
char :: Char -> ADoc a Source #
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 :: String -> ADoc a Source #
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 pretty should be
used.
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.
group :: ADoc a -> ADoc a Source #
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.
A linebreak that can not be flattened; it is guaranteed to be rendered as a newline.
flatAlt :: ADoc a -> ADoc a -> ADoc a Source #
flatAlt creates a document that changes when flattened; normally
it is rendered as the first argument, but when flattened is rendered
as the second.
Annotations
noAnnotate :: ADoc a -> ADoc a' Source #
simpleDocScanAnn :: (r -> a -> r) -> r -> SimpleDoc a -> SimpleDoc r Source #
Alignment
align :: ADoc a -> ADoc a Source #
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 -> ADoc a -> ADoc a Source #
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 -> ADoc a -> ADoc a Source #
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 :: Foldable f => ADoc a -> ADoc a -> ADoc a -> f (ADoc a) -> ADoc a Source #
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 ]
list :: Foldable f => f (ADoc a) -> ADoc a Source #
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 :: Foldable f => f (ADoc a) -> ADoc a Source #
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 :: Foldable f => f (ADoc a) -> ADoc a Source #
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
(</>) :: ADoc a -> ADoc a -> ADoc a infixr 5 Source #
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)
(<//>) :: ADoc a -> ADoc a -> ADoc a infixr 5 Source #
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)
(<#>) :: ADoc a -> ADoc a -> ADoc a infixr 5 Source #
The document (x <#> y) concatenates document x and y with a
line in between. (infixr 5)
(<##>) :: ADoc a -> ADoc a -> ADoc a infixr 5 Source #
The document (x <##> y) concatenates document x and y with
a linebreak in between. (infixr 5)
List combinators
hsep :: Foldable f => f (ADoc a) -> ADoc a Source #
The document (hsep xs) concatenates all documents xs
horizontally with (<+>).
vsep :: Foldable f => f (ADoc a) -> ADoc a Source #
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 someTextThis 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
fillSep :: Foldable f => f (ADoc a) -> ADoc a Source #
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 (</>) mempty xs
sep :: Foldable f => f (ADoc a) -> ADoc a Source #
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 :: Foldable f => f (ADoc a) -> ADoc a Source #
The document (hcat xs) concatenates all documents xs
horizontally with (<>).
vcat :: Foldable f => f (ADoc a) -> ADoc a Source #
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 :: Foldable f => f (ADoc a) -> ADoc a Source #
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 (<//>) mempty xs
cat :: Foldable f => f (ADoc a) -> ADoc a Source #
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 :: Traversable f => ADoc a -> f (ADoc a) -> f (ADoc a) 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 -> ADoc a -> ADoc a Source #
The document (fill i x) renders 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 combinator is quite
useful in practice to output a list of bindings. The following
example demonstrates this.
types = [("mempty","Doc a")
,("nest","Int -> ADoc a -> ADoc a")
,("linebreak","Doc a")]
ptype (name,tp)
= fill 6 (text name) <+> text "::" <+> text tp
test = text "let" <+> align (vcat (map ptype types))Which is layed out as:
let mempty :: ADoc a
nest :: Int -> ADoc a -> ADoc a
linebreak :: ADoc a
fillBreak :: Int -> ADoc a -> ADoc a Source #
The document (fillBreak i x) first renders 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 previous example to use fillBreak, we get a useful
variation of the previous output:
ptype (name,tp)
= fillBreak 6 (text name) <+> text "::" <+> text tpThe output will now be:
let mempty :: ADoc a
nest :: Int -> ADoc a -> ADoc a
linebreak
:: ADoc a
Bracketing combinators
enclose :: ADoc a -> ADoc a -> ADoc a -> ADoc a Source #
The document (enclose l r x) encloses document x between
documents l and r using (<>).
enclose l r x = l <> x <> r
squotes :: ADoc a -> ADoc a Source #
Document (squotes x) encloses document x with single quotes
"'".
dquotes :: ADoc a -> ADoc a Source #
Document (dquotes x) encloses document x with double quotes
'"'.
parens :: ADoc a -> ADoc a Source #
Document (parens x) encloses document x in parenthesis, "("
and ")".
brackets :: ADoc a -> ADoc a Source #
Document (brackets x) encloses document x in square brackets,
"[" and "]".
Character documents
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.
Instances
| Pretty Bool Source # | |
| Pretty Char Source # | |
| Pretty Double Source # | |
| Pretty Float Source # | |
| Pretty Int Source # | |
| Pretty Int8 Source # | |
| Pretty Int16 Source # | |
| Pretty Int32 Source # | |
| Pretty Int64 Source # | |
| Pretty Integer Source # | |
| Pretty Rational Source # | |
| Pretty Word Source # | |
| Pretty Word8 Source # | |
| Pretty Word16 Source # | |
| Pretty Word32 Source # | |
| Pretty Word64 Source # | |
| Pretty () Source # | |
| Pretty Natural Source # | |
| Pretty Text Source # | |
| Pretty Text Source # | |
| Pretty a => Pretty [a] Source # | |
| Pretty a => Pretty (Maybe a) Source # | |
| Pretty a => Pretty (NonEmpty a) Source # | |
| Pretty a => Pretty (Seq a) Source # | |
| Pretty (ADoc a) Source # | |
| (Pretty a, Pretty b) => Pretty (a, b) Source # | |
| (Pretty a, Pretty b, Pretty c) => Pretty (a, b, c) Source # | |
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 -> ADoc a -> SimpleDoc a Source #
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 :: ADoc a -> SimpleDoc a Source #
(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.
renderSmart :: Int -> ADoc a -> SimpleDoc a Source #
A slightly smarter rendering algorithm with more lookahead. It provides
provide earlier breaking on deeply nested structures.
For example, consider this python-ish pseudocode:
fun(fun(fun(fun(fun([abcdefg, abcdefg])))))
If we put a softbreak (+ nesting 2) after each open parenthesis, and align
the elements of the list to match the opening brackets, this will render with
renderPretty and a page width of 20c as:
fun(fun(fun(fun(fun([
| abcdef,
| abcdef,
]
))))) |
Where the 20c. boundary has been marked with |. Because renderPretty only
uses one-line lookahead, it sees that the first line fits, and is stuck
putting the second and third lines after the 20c mark. In contrast,
renderSmart will continue to check the potential document up to the end of
the indentation level. Thus, it will format the document as:
fun( |
fun( |
fun( |
fun( |
fun([ |
abcdef,
abcdef,
] |
))))) |
Which fits within the 20c. mark.
In addition, renderSmart uses this lookahead to minimize the number of
lines printed, leading to more compact and visually appealing output.
Consider this example using the same syntax as above:
aaaaaaaaaaa([abc, def, ghi])
When rendered with renderPretty and a page width of 20c, we get:
aaaaaaaaaaa([ abc
, def
, ghi ])
Whereas when rendered with renderSmart and a page width of 20c, we get:
aaaaaaaaaaa(
[abc, def, ghi])
displayIO :: Handle -> SimpleDoc a -> IO () Source #
(displayIO handle simpleDoc) writes simpleDoc to the file
handle handle, discarding all annotations. This function
is used for example by hPutDoc:
hPutDoc handle doc = displayIO handle (renderPretty 0.4 100 doc)
Arguments
| :: (Applicative f, Monoid o) | |
| => (a -> f o) | How to push an annotated region |
| -> (a -> f o) | How to end an annotated region |
| -> (String -> f o) | How to display a string (from document or whitespace) |
| -> SimpleDoc a | |
| -> f o |
Display a rendered document.
This function takes a means of pushing an annotated region, a means of ending it,
and a means of displaying a string, with effects f to display or compute the output o.
displaySpans :: Monoid o => (String -> o) -> SimpleDoc a -> (o, SpanList a) Source #
Generate a pair of a string and a list of source span/annotation pairs