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-Inferred |
Language | Haskell2010 |
Text.PrettyPrint.Annotated.WL
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
. We cannot useempty
for compatibility with base. -
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 three renderers, 'renderPretty/renderPrettyDefault' and
renderSmart
for pretty printing andrenderCompact
for compact output. The pretty printing algorithm also uses a ribbon-width now for even prettier output. -
There are display routines
displayS
anddisplay
for strings,displayT
for lazy text,displayIO
for file based output. Generalized display routines for display with annotations are provided, i.e.,displayDecoratedA
anddisplayDecorated
. FurthermoredisplaySpans
exists which creates a monoid and a SpanList of the annotations. -
There is a
Pretty
class which creates documents without annotations. - The implementation uses optimised representations and strictness annotations.
- There is the wl-pprint-console package, based on this package, which provides additional display routines, e.g., colorful output using ANSI escape sequences.
Synopsis
- data Doc a
- putDoc :: Doc a -> IO ()
- hPutDoc :: Handle -> Doc a -> IO ()
- char :: Char -> Doc a
- text :: String -> Doc a
- nest :: Int -> Doc a -> Doc a
- line :: Doc a
- linebreak :: Doc a
- group :: Doc a -> Doc a
- softline :: Doc a
- softbreak :: Doc a
- hardline :: Doc a
- flatAlt :: Doc a -> Doc a -> Doc a
- flatten :: Doc a -> Doc a
- annotate :: a -> Doc a -> Doc a
- noAnnotate :: Doc a -> Doc a'
- docMapAnn :: (a -> Doc a' -> Doc a') -> Doc a -> Doc a'
- simpleDocMapAnn :: (r -> a -> r) -> (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 :: Doc a -> Doc a
- hang :: Int -> Doc a -> Doc a
- indent :: Int -> Doc a -> Doc a
- encloseSep :: Foldable f => Doc a -> Doc a -> Doc a -> f ( Doc a) -> Doc a
- list :: Foldable f => f ( Doc a) -> Doc a
- tupled :: Foldable f => f ( Doc a) -> Doc a
- semiBraces :: Foldable f => f ( Doc a) -> Doc a
- (<+>) :: Doc a -> Doc a -> Doc a
- (</>) :: Doc a -> Doc a -> Doc a
- (<//>) :: Doc a -> Doc a -> Doc a
- (<#>) :: Doc a -> Doc a -> Doc a
- (<##>) :: Doc a -> Doc a -> Doc a
- hsep :: Foldable f => f ( Doc a) -> Doc a
- vsep :: Foldable f => f ( Doc a) -> Doc a
- fillSep :: Foldable f => f ( Doc a) -> Doc a
- sep :: Foldable f => f ( Doc a) -> Doc a
- hcat :: Foldable f => f ( Doc a) -> Doc a
- vcat :: Foldable f => f ( Doc a) -> Doc a
- fillCat :: Foldable f => f ( Doc a) -> Doc a
- cat :: Foldable f => f ( Doc a) -> Doc a
- punctuate :: Traversable f => Doc a -> f ( Doc a) -> f ( Doc a)
- fill :: Int -> Doc a -> Doc a
- fillBreak :: Int -> Doc a -> Doc a
- enclose :: Doc a -> Doc a -> Doc a -> Doc a
- squotes :: Doc a -> Doc a
- dquotes :: Doc a -> Doc a
- parens :: Doc a -> Doc a
- angles :: Doc a -> Doc a
- braces :: Doc a -> Doc a
- brackets :: Doc a -> Doc a
- lparen :: Doc a
- rparen :: Doc a
- langle :: Doc a
- rangle :: Doc a
- lbrace :: Doc a
- rbrace :: Doc a
- lbracket :: Doc a
- rbracket :: Doc a
- squote :: Doc a
- dquote :: Doc a
- semi :: Doc a
- colon :: Doc a
- comma :: Doc a
- space :: Doc a
- dot :: Doc a
- backslash :: Doc a
- equals :: Doc a
-
class
Pretty
a
where
- pretty :: a -> Doc b
- prettyList :: [a] -> Doc b
- data SimpleDoc a
- renderPrettyDefault :: Doc a -> SimpleDoc a
- renderPretty :: Float -> Int -> Doc a -> SimpleDoc a
- renderCompact :: Doc a -> SimpleDoc a
- renderSmart :: Int -> Doc a -> SimpleDoc a
- display :: SimpleDoc a -> String
- displayS :: SimpleDoc a -> ShowS
- displayT :: 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 -> Doc a) -> Doc a
- nesting :: ( Int -> Doc a) -> Doc a
- width :: Doc a -> ( Int -> Doc a) -> Doc a
- columns :: ( Maybe Int -> Doc a) -> Doc a
- ribbon :: ( Maybe Int -> Doc a) -> Doc a
- mempty :: Monoid a => a
- (<>) :: Semigroup a => a -> a -> a
Documents
The 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
Constructors
Empty | |
Char ! Char | |
Text ! Int String | |
Line | |
FlatAlt ( Doc a) ( Doc a) | |
Cat ( Doc a) ( Doc a) | |
Nest ! Int ( Doc a) | |
Union ( Doc a) ( Doc a) | |
Annotate a ( Doc a) | |
Column ( Int -> Doc a) | |
Nesting ( Int -> Doc a) | |
Columns ( Maybe Int -> Doc a) | |
Ribbon ( Maybe Int -> Doc a) |
Instances
putDoc :: Doc 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 -> Doc 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 -> Doc 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 -> Doc 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 :: Doc a -> Doc 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 :: Doc a -> Doc a -> Doc 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 :: Doc a -> Doc a' Source #
Remove the annotations from a document.
Alignment
align :: Doc a -> Doc 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 -> Doc a -> Doc 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 -> Doc a -> Doc 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 => Doc a -> Doc a -> Doc a -> f ( Doc a) -> Doc 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 ( Doc a) -> Doc 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 ( Doc a) -> Doc 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 ( Doc a) -> Doc 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
(</>) :: Doc a -> Doc a -> Doc 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)
(<//>) :: Doc a -> Doc a -> Doc 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)
(<#>) :: Doc a -> Doc a -> Doc a infixr 5 Source #
The document
(x <#> y)
concatenates document
x
and
y
with a
line
in between. (infixr 5)
(<##>) :: Doc a -> Doc a -> Doc 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 ( Doc a) -> Doc a Source #
The document
(hsep xs)
concatenates all documents
xs
horizontally with
(<+>)
.
vsep :: Foldable f => f ( Doc a) -> Doc 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 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
fillSep :: Foldable f => f ( Doc a) -> Doc 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 ( Doc a) -> Doc 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 ( Doc a) -> Doc a Source #
The document
(hcat xs)
concatenates all documents
xs
horizontally with
(<>)
.
vcat :: Foldable f => f ( Doc a) -> Doc 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 ( Doc a) -> Doc 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 ( Doc a) -> Doc 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 => Doc a -> f ( Doc a) -> f ( Doc 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 -> Doc a -> Doc a Source #
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 = [("mempty","Doc a") ,("nest","Int -> Doc a -> Doc 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 :: Doc a nest :: Int -> Doc a -> Doc a linebreak :: Doc a
fillBreak :: Int -> Doc a -> Doc a Source #
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 mempty :: Doc a nest :: Int -> Doc a -> Doc a linebreak :: Doc a
Bracketing combinators
enclose :: Doc a -> Doc a -> Doc a -> Doc a Source #
The document
(enclose l r x)
encloses document
x
between
documents
l
and
r
using
(<>)
.
enclose l r x = l <> x <> r
parens :: Doc a -> Doc a Source #
Document
(parens x)
encloses document
x
in parenthesis, "("
and ")".
brackets :: Doc a -> Doc 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.
Minimal complete definition
Nothing
Methods
prettyList :: [a] -> Doc b Source #
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 Natural Source # | |
Pretty Rational Source # | |
Pretty Word Source # | |
Pretty Word8 Source # | |
Pretty Word16 Source # | |
Pretty Word32 Source # | |
Pretty Word64 Source # | |
Pretty () Source # | |
Defined in Text.PrettyPrint.Annotated.WL |
|
Pretty Text Source # | |
Pretty Text Source # | |
Pretty a => Pretty [a] Source # | |
Defined in Text.PrettyPrint.Annotated.WL |
|
Pretty a => Pretty ( Maybe a) Source # | |
Pretty a => Pretty ( NonEmpty a) Source # | |
Pretty a => Pretty ( Seq a) Source # | |
Pretty ( Doc a) Source # | |
( Pretty a, Pretty b) => Pretty (a, b) Source # | |
Defined in Text.PrettyPrint.Annotated.WL |
|
( Pretty a, Pretty b, Pretty c) => Pretty (a, b, c) Source # | |
Defined in Text.PrettyPrint.Annotated.WL |
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.
Constructors
SEmpty | |
SChar ! Char ( SimpleDoc a) | |
SText ! Int String ( SimpleDoc a) | |
SLine ! Int ( SimpleDoc a) | |
SPushAnn a ( SimpleDoc a) | |
SPopAnn a ( SimpleDoc a) |
Instances
renderPrettyDefault :: Doc a -> SimpleDoc a Source #
renderPretty :: Float -> Int -> Doc 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 :: Doc 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 -> Doc 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])
display :: SimpleDoc a -> String Source #
(display simpleDoc)
takes the output
simpleDoc
from a
rendering function and outputs a
String
. Along the way, all annotations are
discarded.
displayT :: SimpleDoc a -> Text Source #
(display simpleDoc)
takes the output
simpleDoc
from a
rendering function and outputs a
Text
. Along the way, all annotations are
discarded.
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 (renderPrettyDefault 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
.
Arguments
:: Monoid o | |
=> (a -> o) |
How to push an annotated region |
-> (a -> o) |
How to end an annotated region |
-> ( String -> o) |
How to display a string (from document or whitespace) |
-> SimpleDoc a | |
-> 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 to compute the output
o
.
type SpanList a = [( Int , Int , a)] Source #
The type alias
SpanList
is used by
displaySpan
First element is the starting position, second the length and third the annotation at the given range.
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