HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Modulepretty-1.1.3.6Haskell98

Text.PrettyPrint.Annotated.HughesPJ

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.

  • 6 types
  • 58 values
  • Packagepretty-1.1.3.6
  • Exports64
  • LanguageHaskell98
  • LicenceBSD-3-Clause
  • SourceHughesPJ.hs

The document type

3 declarations
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, …
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
datadata AnnotDetails a
#

An annotation (side-metadata) attached at a particular point in a Doc. Allows carrying non-pretty-printed data around in a Doc that is attached at particular points in the structure. Once the Doc is render to an output type (such as String), we can also retrieve where in the rendered document our annotations start and end (see Span and renderSpans).

Constructors

Instances4Functor, Eq, Show, NFData

Constructing documents

0 declarations

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:

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.

valuezeroWidthText :: String -> Doc a
#

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

valueint
  1. :: Int
  2. -> Doc a
    int n = text (show n)
#

Simple derived documents

Wrapping documents in delimiters

Combining documents

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

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

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.

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

1 declaration

Utility functions for documents

2 declarations
valuefirst :: Doc a -> Doc a -> Doc a
#

first returns its first argument if it is non-empty, otherwise its second.

valuereduceDoc :: Doc a -> RDoc a
#

Perform some simplification of a built up GDoc.

Rendering documents

0 declarations

Default rendering

Annotation rendering

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

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
valuerenderDecorated
  1. :: (ann -> String)

    Starting an annotation.

  2. -> (ann -> String)

    Ending an annotation.

  3. -> Doc ann
  4. -> String
#

Render out a String, interpreting the annotations as part of the resulting document.

IMPORTANT: the size of the annotation string does NOT figure into the layout of the document, so the document will lay out as though the annotations are not present.

valuerenderDecoratedM
  1. :: Monad m
  2. => (ann -> m r)

    Starting an annotation.

  3. -> (ann -> m r)

    Ending an annotation.

  4. -> (String -> m r)

    Text formatting.

  5. -> m r

    Document end.

  6. -> Doc ann
  7. -> m r
#

Render a document with annotations, by interpreting the start and end of the annotations, as well as the text details in the context of a monad.

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
valuestyle :: Style
#

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

datadata Mode
#

Rendering mode.

Constructors

Instances4Eq, Show, Generic, Rep

General rendering

valuefullRender
  1. :: Mode

    Rendering mode.

  2. -> Int

    Line length.

  3. -> Float

    Ribbons per line.

  4. -> (TextDetails -> a -> a)

    What to do with text.

  5. -> a

    What to do at the end.

  6. -> Doc b

    The document.

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

    Rendering mode.

  2. -> Int

    Line length.

  3. -> Float

    Ribbons per line.

  4. -> (AnnotDetails b -> a -> a)

    What to do with text.

  5. -> a

    What to do at the end.

  6. -> Doc b

    The document.

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