Text.PrettyPrint.Annotated

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.

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

Eq (Doc a)

Show (Doc a)

IsString (Doc a)

Generic (Doc a)

Monoid (Doc a)

NFData a => NFData (Doc a)

type Rep (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.

Annotation rendering

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

data Span a

Constructors

Span

Fields

spanStart, spanLength :: !Int

spanAnnotation :: a

Instances

Functor Span

Eq a => Eq (Span a)

Show a => Show (Span a)

Rendering with a particular style

data Style

A rendering style.

Constructors

Style

Fields

mode :: Mode

The rendering mode

lineLength :: Int

Length of line, in chars

ribbonsPerLine :: Float

Ratio of line length to ribbon length

Instances

Eq Style

Show Style

Generic Style

type Rep Style

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.

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

data Mode

Rendering mode.

Constructors

PageMode

Normal

ZigZagMode

With zig-zag cuts

LeftMode

No indentation, infinitely long lines

OneLineMode

All on one line

Instances

Eq Mode

Show Mode

Generic Mode

type Rep Mode

data TextDetails

The TextDetails data type

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

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

Show TextDetails

Generic TextDetails

NFData TextDetails

type Rep TextDetails