Skip to content

HORIZON HASKELL Docs lts/ghc-10.0.x04404a62026-10-19Search packagesCtrl K

Theme: |

GHC 10.0.0.20260917 · lts/ghc-10.0.x · 04404a6 · 2026-10-19

Modulepretty-1.1.3.6Haskell98

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 Text.PrettyPrint.Annotated.HughesPJ module. Both are equivalent though as this module simply re-exports the other.

Contents

The document type
Constructing documents
Converting values into documents
Simple derived documents
Wrapping documents in delimiters
Combining documents
Annotating documents
Predicates on documents
Rendering documents
Default rendering
Annotation rendering
Rendering with a particular style
General rendering

Synopsis

Packagepretty-1.1.3.6
Exports54
LanguageHaskell98
LicenceBSD-3-Clause
SourceAnnotated.hs

The document type

datadata 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.

Instances9Functor, Eq, Show, IsString, Generic, Semigroup, …

Functor DocDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Eq (Doc a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Show (Doc a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
IsString (Doc a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Generic (Doc a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Semigroup (Doc a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Monoid (Doc a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
NFData a => NFData (Doc a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
type Rep (Doc a) = D1 ('MetaData "Doc" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.6-874f" 'False) (((C1 ('MetaCons "Empty" 'PrefixI 'False) U1 :+: C1 ('MetaCons "NilAbove" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a)))) :+: (C1 ('MetaCons "TextBeside" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (AnnotDetails a)) :*: S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a))) :+: C1 ('MetaCons "Nest" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'SourceUnpack 'SourceStrict 'DecidedUnpack) (Rec0 Int) :*: S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a))))) :+: ((C1 ('MetaCons "Union" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a)) :*: S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a))) :+: C1 ('MetaCons "NoDoc" 'PrefixI 'False) U1) :+: (C1 ('MetaCons "Beside" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a)) :*: (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool) :*: S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a)))) :+: C1 ('MetaCons "Above" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a)) :*: (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool) :*: S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a)))))))Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ

Constructing documents

Converting values into documents

valuechar :: Char -> Doc a

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

valuetext :: 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.

valueptext :: String -> Doc a

Same as text. Used to be used for Bytestrings.

valuesizedText :: Int -> String -> Doc a

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

valuezeroWidthText :: String -> Doc a

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

valueint

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

valueinteger

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

valuefloat

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

valuedouble

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

valuerational

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

Simple derived documents

valuesemi

:: Doc a
A ';' character

valuecomma

:: Doc a
A ',' character

valuecolon

:: Doc a
A : character

valuespace

:: Doc a
A space character

valueequals

:: Doc a
A = character

valuelparen

:: Doc a
A '(' character

valuerparen

:: Doc a
A ')' character

valuelbrack

:: Doc a
A '[' character

valuerbrack

:: Doc a
A ']' character

valuelbrace

:: Doc a
A '{' character

valuerbrace

:: Doc a
A '}' character

Wrapping documents in delimiters

valueparens

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

valuebrackets

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

valuebraces

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

valuequotes

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

valuedoubleQuotes

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

Combining documents

valueempty :: 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.

value(<>) :: Doc a -> Doc a -> Doc a

Beside. <> is associative, with identity empty.

value(<+>) :: Doc a -> Doc a -> Doc a

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

valuehcat :: [Doc a] -> Doc a

List version of <>.

valuehsep :: [Doc a] -> Doc a

List version of <+>.

value($$) :: Doc a -> Doc a -> Doc a

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.

value($+$) :: Doc a -> Doc a -> Doc a

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

valuevcat :: [Doc a] -> Doc a

List version of $$.

valuesep :: [Doc a] -> Doc a

Either hsep or vcat.

valuecat :: [Doc a] -> Doc a

Either hcat or vcat.

valuefsep :: [Doc a] -> Doc a

"Paragraph fill" version of sep.

valuefcat :: [Doc a] -> Doc a

"Paragraph fill" version of cat.

valuenest :: 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 <>.

valuehang :: Doc a -> Int -> Doc a -> Doc a

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

valuepunctuate :: Doc a -> [Doc a] -> [Doc a]

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

Annotating documents

valueannotate :: a -> Doc a -> Doc a

Attach an annotation to a document.

Predicates on documents

valueisEmpty :: Doc a -> Bool

Returns True if the document is empty

Rendering documents

Default rendering

valuerender :: Doc a -> String

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

Annotation rendering

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

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

datadata 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
- spanStart :: !Int
- spanLength :: !Int
- spanAnnotation :: a

Instances3Functor, Eq, Show

Functor SpanDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Eq a => Eq (Span a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Show a => Show (Span a)Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ

Rendering with a particular style

datadata Style

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

Constructors

Style
- 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.

Instances4Eq, Show, Generic, Rep

Eq StyleDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Show StyleDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Generic StyleDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
type Rep Style = D1 ('MetaData "Style" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.6-874f" 'False) (C1 ('MetaCons "Style" 'PrefixI 'True) (S1 ('MetaSel ('Just "mode") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Mode) :*: (S1 ('MetaSel ('Just "lineLength") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int) :*: S1 ('MetaSel ('Just "ribbonsPerLine") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Float))))Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ

valuestyle :: Style

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

valuerenderStyle :: Style -> Doc a -> String

Render the Doc to a String using the given Style.

General rendering

valuefullRender

:: 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.

valuefullRenderAnn

:: 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.

datadata 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.

Instances4Eq, Show, Generic, Rep

Eq ModeDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Show ModeDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Generic ModeDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
type Rep Mode = D1 ('MetaData "Mode" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.6-874f" '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))Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ

datadata 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.

Instances5Eq, Show, Generic, NFData, Rep

Eq TextDetailsDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Show TextDetailsDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
Generic TextDetailsDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
NFData TextDetailsDefined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ
type Rep TextDetails = D1 ('MetaData "TextDetails" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.6-874f" 'False) (C1 ('MetaCons "Chr" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'SourceUnpack 'SourceStrict 'DecidedUnpack) (Rec0 Char)) :+: (C1 ('MetaCons "Str" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)) :+: C1 ('MetaCons "PStr" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String))))Defined in pretty-1.1.3.6 · Text.PrettyPrint.Annotated.HughesPJ