Copyright	(c) Trevor Elliott <revor@galois.com> 2015
License	BSD-style (see the file LICENSE)
Maintainer	David Terei <code@davidterei.com>
Stability	stable
Portability	portable
Safe Haskell	Safe
Language	Haskell98

Text.PrettyPrint.Annotated

Contents

The document type
Constructing documents
Predicates on documents
Rendering documents

Description

This module provides a version of pretty that allows for annotations to be attached to documents. Annotations are arbitrary pieces of metadata that can be attached to sub-documents.

This module should be used as opposed to the HughesPJ module. Both are equivalent though as this module simply re-exports the other.

Synopsis

The document type

data Doc a #

The abstract type of documents. A Doc represents a set of layouts. A Doc with no occurrences of Union or NoDoc represents just one layout.

Instances

Functor Doc #
Methods fmap :: (a -> b) -> Doc a -> Doc b Source # (<$) :: a -> Doc b -> Doc a Source #
Eq (Doc a) #
Methods (==) :: Doc a -> Doc a -> Bool Source # (/=) :: Doc a -> Doc a -> Bool Source #
Show (Doc a) #
Methods showsPrec :: Int -> Doc a -> ShowS Source # show :: Doc a -> String Source # showList :: [Doc a] -> ShowS Source #
IsString (Doc a) #
Methods fromString :: String -> Doc a Source #
Generic (Doc a) #
Associated Types type Rep (Doc a) :: * -> * Source # Methods from :: Doc a -> Rep (Doc a) x Source # to :: Rep (Doc a) x -> Doc a Source #
Semigroup (Doc a) #
Methods (<>) :: Doc a -> Doc a -> Doc a Source # sconcat :: NonEmpty (Doc a) -> Doc a Source # stimes :: Integral b => b -> Doc a -> Doc a Source #
Monoid (Doc a) #
Methods mempty :: Doc a Source # mappend :: Doc a -> Doc a -> Doc a Source # mconcat :: [Doc a] -> Doc a Source #
NFData a => NFData (Doc a) #
Methods rnf :: Doc a -> () Source #
type Rep (Doc a) #
type Rep (Doc a) = D1 (MetaData "Doc" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.3" False) ((:+:) ((:+:) ((:+:) (C1 (MetaCons "Empty" PrefixI False) U1) (C1 (MetaCons "NilAbove" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a))))) ((:+:) (C1 (MetaCons "TextBeside" PrefixI False) ((::) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (AnnotDetails a))) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a))))) (C1 (MetaCons "Nest" PrefixI False) ((::) (S1 (MetaSel (Nothing Symbol) SourceUnpack SourceStrict DecidedUnpack) (Rec0 Int)) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a))))))) ((:+:) ((:+:) (C1 (MetaCons "Union" PrefixI False) ((::) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a))) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a))))) (C1 (MetaCons "NoDoc" PrefixI False) U1)) ((:+:) (C1 (MetaCons "Beside" PrefixI False) ((::) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a))) ((::) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Bool)) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a)))))) (C1 (MetaCons "Above" PrefixI False) ((::) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a))) ((:*:) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Bool)) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc a)))))))))

Constructing documents

Converting values into documents

char :: Char -> Doc a #

A document of height and width 1, containing a literal character.

text :: String -> Doc a #

A document of height 1 containing a literal string. text satisfies the following laws:

```
text s <> text t = text (s++t)
```
text "" <> x = x, if x non-empty

The side condition on the last law is necessary because text "" has height 1, while empty has no height.

ptext :: String -> Doc a #

Same as text. Used to be used for Bytestrings.

sizedText :: Int -> String -> Doc a #

Some text with any width. (text s = sizedText (length s) s)

zeroWidthText :: String -> Doc a #

Some text, but without any width. Use for non-printing text such as a HTML or Latex tags

int #

Arguments

:: Int
-> Doc a	int n = text (show n)

integer #

Arguments

:: Integer
-> Doc a	integer n = text (show n)

float #

Arguments

:: Float
-> Doc a	float n = text (show n)

double #

Arguments

:: Double
-> Doc a	double n = text (show n)

rational #

Arguments

:: Rational
-> Doc a	rational n = text (show n)

Simple derived documents

semi #

Arguments

:: Doc a

A ';' character

comma #

Arguments

:: Doc a

A ',' character

colon #

Arguments

:: Doc a

A : character

space #

Arguments

:: Doc a

A space character

equals #

Arguments

:: Doc a

A '=' character

lparen #

Arguments

:: Doc a

A '(' character

rparen #

Arguments

:: Doc a

A ')' character

lbrack #

Arguments

:: Doc a

A '[' character

rbrack #

Arguments

:: Doc a

A ']' character

lbrace #

Arguments

:: Doc a

A '{' character

rbrace #

Arguments

:: Doc a

A '}' character

Wrapping documents in delimiters

parens #

Arguments

:: Doc a
-> Doc a	Wrap document in `(...)`

brackets #

Arguments

:: Doc a
-> Doc a	Wrap document in `[...]`

braces #

Arguments

:: Doc a
-> Doc a	Wrap document in `{...}`

quotes #

Arguments

:: Doc a
-> Doc a	Wrap document in `'...'`

doubleQuotes #

Arguments

:: Doc a
-> Doc a	Wrap document in `"..."`

Combining documents

empty :: Doc a #

The empty document, with no height and no width. empty is the identity for <>, <+>, $$ and $+$ , and anywhere in the argument list for sep, hcat, hsep, vcat, fcat etc.

(<>) :: Doc a -> Doc a -> Doc a infixl 6 #

Beside. <> is associative, with identity empty.

(<+>) :: Doc a -> Doc a -> Doc a infixl 6 #

Beside, separated by space, unless one of the arguments is empty. <+> is associative, with identity empty.

hcat :: [Doc a] -> Doc a #

List version of <>.

hsep :: [Doc a] -> Doc a #

List version of <+>.

($$) :: Doc a -> Doc a -> Doc a infixl 5 #

Above, except that if the last line of the first argument stops at least one position before the first line of the second begins, these two lines are overlapped. For example:

   text "hi" $$ nest 5 (text "there")

lays out as

   hi   there

rather than

   hi
        there

$$ is associative, with identity empty, and also satisfies

(x $$ y) <> z = x $$ (y <> z), if y non-empty.

($+$) :: Doc a -> Doc a -> Doc a infixl 5 #

Above, with no overlapping. $+$ is associative, with identity empty.

vcat :: [Doc a] -> Doc a #

List version of $$.

sep :: [Doc a] -> Doc a #

Either hsep or vcat.

cat :: [Doc a] -> Doc a #

Either hcat or vcat.

fsep :: [Doc a] -> Doc a #

"Paragraph fill" version of sep.

fcat :: [Doc a] -> Doc a #

"Paragraph fill" version of cat.

nest :: Int -> Doc a -> Doc a #

Nest (or indent) a document by a given number of positions (which may also be negative). nest satisfies the laws:

```
nest 0 x = x
```
```
nest k (nest k' x) = nest (k+k') x
```
```
nest k (x <> y) = nest k z <> nest k y
```
```
nest k (x $$ y) = nest k x $$ nest k y
```
```
nest k empty = empty
```
x <> nest k y = x <> y, if x non-empty

The side condition on the last law is needed because empty is a left identity for <>.

hang :: Doc a -> Int -> Doc a -> Doc a #

hang d1 n d2 = sep [d1, nest n d2]

punctuate :: Doc a -> [Doc a] -> [Doc a] #

punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]

Annotating documents

annotate :: a -> Doc a -> Doc a #

Attach an annotation to a document.

Predicates on documents

isEmpty :: Doc a -> Bool #

Returns True if the document is empty

Rendering documents

Default rendering

render :: Doc a -> String #

Render the Doc to a String using the default Style (see style).

Annotation rendering

renderSpans :: Doc ann -> (String, [Span ann]) #

Render an annotated Doc to a String and list of annotations (see Span) using the default Style (see style).

data Span a #

A Span represents the result of an annotation after a Doc has been rendered, capturing where the annotation now starts and ends in the rendered output.

Constructors

Span
Fields spanStart :: !Int spanLength :: !Int spanAnnotation :: a

Instances

Functor Span #
Methods fmap :: (a -> b) -> Span a -> Span b Source # (<$) :: a -> Span b -> Span a Source #
Eq a => Eq (Span a) #
Methods (==) :: Span a -> Span a -> Bool Source # (/=) :: Span a -> Span a -> Bool Source #
Show a => Show (Span a) #
Methods showsPrec :: Int -> Span a -> ShowS Source # show :: Span a -> String Source # showList :: [Span a] -> ShowS Source #

Rendering with a particular style

data Style #

A rendering style. Allows us to specify constraints to choose among the many different rendering options.

Constructors

Style

Fields

mode :: Mode
The rendering mode.
lineLength :: Int
Maximum length of a line, in characters.
ribbonsPerLine :: Float
Ratio of line length to ribbon length. A ribbon refers to the characters on a line excluding indentation. So a lineLength of 100, with a ribbonsPerLine of 2.0 would only allow up to 50 characters of ribbon to be displayed on a line, while allowing it to be indented up to 50 characters.

Instances

Eq Style #
Methods (==) :: Style -> Style -> Bool Source # (/=) :: Style -> Style -> Bool Source #
Show Style #
Methods showsPrec :: Int -> Style -> ShowS Source # show :: Style -> String Source # showList :: [Style] -> ShowS Source #
Generic Style #
Associated Types type Rep Style :: * -> * Source # Methods from :: Style -> Rep Style x Source # to :: Rep Style x -> Style Source #
type Rep Style #
type Rep Style = D1 (MetaData "Style" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.3" False) (C1 (MetaCons "Style" PrefixI True) ((::) (S1 (MetaSel (Just Symbol "mode") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Mode)) ((::) (S1 (MetaSel (Just Symbol "lineLength") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Int)) (S1 (MetaSel (Just Symbol "ribbonsPerLine") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Float)))))

style :: Style #

The default style (mode=PageMode, lineLength=100, ribbonsPerLine=1.5).

renderStyle :: Style -> Doc a -> String #

Render the Doc to a String using the given Style.

General rendering

fullRender #

Arguments

:: Mode	Rendering mode.
-> Int	Line length.
-> Float	Ribbons per line.
-> (TextDetails -> a -> a)	What to do with text.
-> a	What to do at the end.
-> Doc b	The document.
-> a	Result.

The general rendering interface. Please refer to the Style and Mode types for a description of rendering mode, line length and ribbons.

fullRenderAnn #

Arguments

:: Mode	Rendering mode.
-> Int	Line length.
-> Float	Ribbons per line.
-> (AnnotDetails b -> a -> a)	What to do with text.
-> a	What to do at the end.
-> Doc b	The document.
-> a	Result.

The general rendering interface, supporting annotations. Please refer to the Style and Mode types for a description of rendering mode, line length and ribbons.

data Mode #

Rendering mode.

Constructors

PageMode	Normal rendering (`lineLength` and `ribbonsPerLine` respected').
ZigZagMode	With zig-zag cuts.
LeftMode	No indentation, infinitely long lines (`lineLength` ignored), but explicit new lines, i.e., `text "one" $$ text "two"`, are respected.
OneLineMode	All on one line, `lineLength` ignored and explicit new lines (`$$`) are turned into spaces.

Instances

Eq Mode #
Methods (==) :: Mode -> Mode -> Bool Source # (/=) :: Mode -> Mode -> Bool Source #
Show Mode #
Methods showsPrec :: Int -> Mode -> ShowS Source # show :: Mode -> String Source # showList :: [Mode] -> ShowS Source #
Generic Mode #
Associated Types type Rep Mode :: * -> * Source # Methods from :: Mode -> Rep Mode x Source # to :: Rep Mode x -> Mode Source #
type Rep Mode #
type Rep Mode = D1 (MetaData "Mode" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.3" False) ((:+:) ((:+:) (C1 (MetaCons "PageMode" PrefixI False) U1) (C1 (MetaCons "ZigZagMode" PrefixI False) U1)) ((:+:) (C1 (MetaCons "LeftMode" PrefixI False) U1) (C1 (MetaCons "OneLineMode" PrefixI False) U1)))

data TextDetails #

A TextDetails represents a fragment of text that will be output at some point in a Doc.

Constructors

Chr !Char	A single Char fragment
Str String	A whole String fragment
PStr String	Used to represent a Fast String fragment but now deprecated and identical to the Str constructor.

Instances

Eq TextDetails #
Methods (==) :: TextDetails -> TextDetails -> Bool Source # (/=) :: TextDetails -> TextDetails -> Bool Source #
Show TextDetails #
Methods showsPrec :: Int -> TextDetails -> ShowS Source # show :: TextDetails -> String Source # showList :: [TextDetails] -> ShowS Source #
Generic TextDetails #
Associated Types type Rep TextDetails :: * -> * Source # Methods from :: TextDetails -> Rep TextDetails x Source # to :: Rep TextDetails x -> TextDetails Source #
NFData TextDetails #
Methods rnf :: TextDetails -> () Source #
type Rep TextDetails #
type Rep TextDetails = D1 (MetaData "TextDetails" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.3" False) ((:+:) (C1 (MetaCons "Chr" PrefixI False) (S1 (MetaSel (Nothing Symbol) SourceUnpack SourceStrict DecidedUnpack) (Rec0 Char))) ((:+:) (C1 (MetaCons "Str" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String))) (C1 (MetaCons "PStr" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String)))))