Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell98 |
Options.Applicative.Help.Pretty
Synopsis
- data SimpleDoc
- class Pretty a where
- pretty :: a -> Doc
- prettyList :: [a] -> Doc
- text :: String -> Doc
- list :: [Doc] -> Doc
- tupled :: [Doc] -> Doc
- semiBraces :: [Doc] -> Doc
- encloseSep :: Doc -> Doc -> Doc -> [Doc] -> Doc
- punctuate :: Doc -> [Doc] -> [Doc]
- sep :: [Doc] -> Doc
- fillSep :: [Doc] -> Doc
- hsep :: [Doc] -> Doc
- vsep :: [Doc] -> Doc
- cat :: [Doc] -> Doc
- fillCat :: [Doc] -> Doc
- hcat :: [Doc] -> Doc
- vcat :: [Doc] -> Doc
- (<+>) :: Doc -> Doc -> Doc
- (</>) :: Doc -> Doc -> Doc
- (<//>) :: Doc -> Doc -> Doc
- (<$$>) :: Doc -> Doc -> Doc
- softline :: Doc
- softbreak :: Doc
- squotes :: Doc -> Doc
- dquotes :: Doc -> Doc
- braces :: Doc -> Doc
- parens :: Doc -> Doc
- angles :: Doc -> Doc
- brackets :: Doc -> Doc
- enclose :: Doc -> Doc -> 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
- bool :: Bool -> Doc
- int :: Int -> Doc
- integer :: Integer -> Doc
- float :: Float -> Doc
- double :: Double -> Doc
- rational :: Rational -> Doc
- fillBreak :: Int -> Doc -> Doc
- fill :: Int -> Doc -> Doc
- width :: Doc -> (Int -> Doc) -> Doc
- hang :: Int -> Doc -> Doc
- align :: Doc -> Doc
- empty :: Doc
- char :: Char -> Doc
- line :: Doc
- linebreak :: Doc
- hardline :: Doc
- nest :: Int -> Doc -> Doc
- column :: (Int -> Doc) -> Doc
- nesting :: (Int -> Doc) -> Doc
- group :: Doc -> Doc
- flatAlt :: Doc -> Doc -> Doc
- black :: Doc -> Doc
- dullblack :: Doc -> Doc
- red :: Doc -> Doc
- dullred :: Doc -> Doc
- green :: Doc -> Doc
- dullgreen :: Doc -> Doc
- yellow :: Doc -> Doc
- dullyellow :: Doc -> Doc
- blue :: Doc -> Doc
- dullblue :: Doc -> Doc
- magenta :: Doc -> Doc
- dullmagenta :: Doc -> Doc
- cyan :: Doc -> Doc
- dullcyan :: Doc -> Doc
- white :: Doc -> Doc
- dullwhite :: Doc -> Doc
- onblack :: Doc -> Doc
- ondullblack :: Doc -> Doc
- onred :: Doc -> Doc
- ondullred :: Doc -> Doc
- ongreen :: Doc -> Doc
- ondullgreen :: Doc -> Doc
- onyellow :: Doc -> Doc
- ondullyellow :: Doc -> Doc
- onblue :: Doc -> Doc
- ondullblue :: Doc -> Doc
- onmagenta :: Doc -> Doc
- ondullmagenta :: Doc -> Doc
- oncyan :: Doc -> Doc
- ondullcyan :: Doc -> Doc
- onwhite :: Doc -> Doc
- ondullwhite :: Doc -> Doc
- bold :: Doc -> Doc
- debold :: Doc -> Doc
- underline :: Doc -> Doc
- deunderline :: Doc -> Doc
- plain :: Doc -> Doc
- renderSmart :: Float -> Int -> Doc -> SimpleDoc
- renderCompact :: Doc -> SimpleDoc
- displayIO :: Handle -> SimpleDoc -> IO ()
- putDoc :: Doc -> IO ()
- hPutDoc :: Handle -> Doc -> IO ()
- type Doc = Doc
- indent :: Int -> Doc -> Doc
- renderPretty :: Float -> Int -> Doc -> SimpleDoc
- displayS :: SimpleDoc -> ShowS
- (.$.) :: Doc -> Doc -> Doc
- groupOrNestLine :: Doc -> Doc
- altSep :: Doc -> Doc -> Doc
- hangAtIfOver :: Int -> Int -> Doc -> Doc
Documentation
The data type SimpleDoc
represents rendered documents and is
used by the display functions.
Whereas values of the data type Doc
represent non-empty sets of possible
renderings of a document, values of the data type SimpleDoc
represent
single renderings of a document.
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.
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
Instances
Pretty Doc | |
Pretty Integer | |
Pretty () | |
Defined in Text.PrettyPrint.ANSI.Leijen.Internal | |
Pretty Bool | |
Pretty Char | |
Pretty Double | |
Pretty Float | |
Pretty Int | |
Pretty a => Pretty (Maybe a) | |
Pretty a => Pretty [a] | |
Defined in Text.PrettyPrint.ANSI.Leijen.Internal | |
(Pretty a, Pretty b) => Pretty (a, b) | |
Defined in Text.PrettyPrint.ANSI.Leijen.Internal | |
(Pretty a, Pretty b, Pretty c) => Pretty (a, b, c) | |
Defined in Text.PrettyPrint.ANSI.Leijen.Internal |
text :: String -> Doc 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 string
should be
used.
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 :: [Doc] -> Doc 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 :: [Doc] -> Doc Source #
The document (semiBraces xs)
separates the documents xs
with
semicolons and encloses them in braces. The documents are rendered
horizontally if that fits the page. Otherwise they are aligned
vertically. All semicolons are put in front of the elements.
encloseSep :: Doc -> Doc -> Doc -> [Doc] -> Doc 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]
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
.)
The document (sep xs)
concatenates all documents xs
either
horizontally with (<+>)
, if it fits the page, or vertically with
(<$>)
.
sep xs = group (vsep xs)
fillSep :: [Doc] -> Doc Source #
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 (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 (cat xs)
concatenates all documents xs
either
horizontally with (<>)
, if it fits the page, or vertically with
(<$$>)
.
cat xs = group (vcat xs)
fillCat :: [Doc] -> Doc Source #
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 (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.
(<+>) :: Doc -> Doc -> Doc infixr 6 Source #
The document (x <+> y)
concatenates document x
and y
with a
space
in between. (infixr 6)
(</>) :: Doc -> Doc -> Doc 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 -> Doc -> Doc 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 -> Doc -> Doc infixr 5 Source #
The document (x <$$> y)
concatenates document x
and y
with
a linebreak
in between. (infixr 5)
brackets :: Doc -> Doc Source #
Document (brackets x)
encloses document x
in square brackets,
"[" and "]".
enclose :: Doc -> Doc -> Doc -> Doc Source #
The document (enclose l r x)
encloses document x
between
documents l
and r
using (<>)
.
enclose l r x = l <> x <> r
string :: String -> Doc Source #
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.
rational :: Rational -> Doc Source #
The document (rational r)
shows the literal rational r
using text
.
fillBreak :: Int -> Doc -> Doc Source #
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
fill :: Int -> Doc -> Doc Source #
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
hang :: Int -> Doc -> Doc 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)
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
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 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
.
A linebreak that will never be flattened; it is guaranteed to render as a newline.
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.
flatAlt :: Doc -> Doc -> Doc Source #
A document that is normally rendered as the first argument, but when flattened, is rendered as the second document.
dullyellow :: Doc -> Doc Source #
Displays a document with the dull yellow forecolor
dullmagenta :: Doc -> Doc Source #
Displays a document with the dull magenta forecolor
ondullblack :: Doc -> Doc Source #
Displays a document with the dull black backcolor
ondullgreen :: Doc -> Doc Source #
Displays a document with the dull green backcolor
ondullyellow :: Doc -> Doc Source #
Displays a document with the dull yellow backcolor
ondullblue :: Doc -> Doc Source #
Displays a document with the dull blue backcolor
ondullmagenta :: Doc -> Doc Source #
Displays a document with the dull magenta backcolor
ondullcyan :: Doc -> Doc Source #
Displays a document with the dull cyan backcolor
ondullwhite :: Doc -> Doc Source #
Displays a document with the dull white backcolor
deunderline :: Doc -> Doc Source #
Displays a document with no underlining
renderSmart :: Float -> Int -> Doc -> SimpleDoc 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 20 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 20-c
mark. In contrast, renderSmart
will continue to check that 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. boundary.
renderCompact :: Doc -> SimpleDoc 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.
This rendering function does not add any colorisation information.
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 80 doc)
Any ANSI colorisation in simpleDoc
will be output.
putDoc :: Doc -> IO () Source #
The action (putDoc doc)
pretty prints document doc
to the
standard output, with a page width of 80 characters and a ribbon
width of 32 characters.
main :: IO () main = do{ putDoc (text "hello" <+> text "world") }
Which would output
hello world
Any ANSI colorisation in doc
will be output.
hPutDoc :: Handle -> Doc -> IO () Source #
(hPutDoc handle doc)
pretty prints document doc
to the file
handle handle
with a page width of 80 characters and a ribbon
width of 32 characters.
main = do{ handle <- openFile "MyFile" WriteMode ; hPutDoc handle (vcat (map text ["vertical","text"])) ; hClose handle }
Any ANSI colorisation in doc
will be output.
groupOrNestLine :: Doc -> Doc Source #
Render flattened text on this line, or start a new line before rendering any text.
This will also nest subsequent lines in the group.
altSep :: Doc -> Doc -> Doc Source #
Separate items in an alternative with a pipe.
If the first document and the pipe don't fit on the line, then mandatorily flow the next entry onto the following line.
The (//) softbreak ensures that if the document does fit on the line, there is at least a space, but it's possible for y to still appear on the next line.
hangAtIfOver :: Int -> Int -> Doc -> Doc Source #
Printer hacks to get nice indentation for long commands and subcommands.
If we're starting this section over the desired width (usually 1/3 of the ribbon), then we will make a line break, indent all of the usage, and go.
The ifAtRoot is an interesting clause. If this whole
operation is put under a group
then the linebreak
will disappear; then item d will therefore not be at
the starting column, and it won't be indented more.