pretty-1.1.3.6: Pretty-printing library

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file LICENSE)
Maintainer | David Terei <code@davidterei.com>
Stability | stable
Portability | portable
Safe Haskell | Safe
Language | Haskell98

Text.PrettyPrint.HughesPJ

Contents

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

Description

Provides a collection of pretty printer combinators, a set of API's that provides a way to easily print out text in a consistent format of your choosing.

Originally designed by John Hughes's and Simon Peyton Jones's.

For more information you can refer to the original paper that serves as the basis for this libraries design: /The Design of a Pretty-printing Library/ by John Hughes, in Advanced Functional Programming, 1995.

Synopsis

- data Doc
- data TextDetails
  - = Chr !Char
  - | Str String
  - | PStr String
- char :: Char -> Doc
- text :: String -> Doc
- ptext :: String -> Doc
- sizedText :: Int -> String -> Doc
- zeroWidthText :: String -> Doc
- int :: Int -> Doc
- integer :: Integer -> Doc
- float :: Float -> Doc
- double :: Double -> Doc
- rational :: Rational -> Doc
- semi :: Doc
- comma :: Doc
- colon :: Doc
- space :: Doc
- equals :: Doc
- lparen :: Doc
- rparen :: Doc
- lbrack :: Doc
- rbrack :: Doc
- lbrace :: Doc
- rbrace :: Doc
- parens :: Doc -> Doc
- brackets :: Doc -> Doc
- braces :: Doc -> Doc
- quotes :: Doc -> Doc
- doubleQuotes :: Doc -> Doc
- maybeParens :: Bool -> Doc -> Doc
- maybeBrackets :: Bool -> Doc -> Doc
- maybeBraces :: Bool -> Doc -> Doc
- maybeQuotes :: Bool -> Doc -> Doc
- maybeDoubleQuotes :: Bool -> Doc -> Doc
- empty :: Doc
- (<>) :: Doc -> Doc -> Doc
- (<+>) :: Doc -> Doc -> Doc
- hcat :: [Doc] -> Doc
- hsep :: [Doc] -> Doc
- ($$) :: Doc -> Doc -> Doc
- ($+$) :: Doc -> Doc -> Doc
- vcat :: [Doc] -> Doc
- sep :: [Doc] -> Doc
- cat :: [Doc] -> Doc
- fsep :: [Doc] -> Doc
- fcat :: [Doc] -> Doc
- nest :: Int -> Doc -> Doc
- hang :: Doc -> Int -> Doc -> Doc
- punctuate :: Doc -> [Doc] -> [Doc]
- isEmpty :: Doc -> Bool
- first :: Doc -> Doc -> Doc
- reduceDoc :: Doc -> RDoc
- render :: Doc -> String
- data Style = Style {
  - mode :: Mode
  - lineLength :: Int
  - ribbonsPerLine :: Float
  }
- style :: Style
- renderStyle :: Style -> Doc -> String
- data Mode
  - = PageMode
  - | ZigZagMode
  - | LeftMode
  - | OneLineMode
- fullRender :: Mode -> Int -> Float -> (TextDetails -> a -> a) -> a -> Doc -> a

# The document type

data Doc Source #

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

Instances details

IsString Doc Source # |
Instance details Defined in Text.PrettyPrint.HughesPJ Methods fromString :: String -> Doc Source #
Monoid Doc Source # |
Instance details Defined in Text.PrettyPrint.HughesPJ Methods mempty :: Doc Source # mappend :: Doc -> Doc -> Doc Source # mconcat :: [Doc] -> Doc Source #
Semigroup Doc Source # |
Instance details Defined in Text.PrettyPrint.HughesPJ Methods (<>) :: Doc -> Doc -> Doc Source # sconcat :: NonEmpty Doc -> Doc Source # stimes :: Integral b => b -> Doc -> Doc Source #
Generic Doc Source # |
Instance details Defined in Text.PrettyPrint.HughesPJ Associated Types type Rep Doc :: Type -> Type Source # Methods from :: Doc -> Rep Doc x Source # to :: Rep Doc x -> Doc Source #
Show Doc Source # |
Instance details Defined in Text.PrettyPrint.HughesPJ Methods showsPrec :: Int -> Doc -> ShowS Source # show :: Doc -> String Source # showList :: [Doc] -> ShowS Source #
NFData Doc Source # |
Instance details Defined in Text.PrettyPrint.HughesPJ Methods rnf :: Doc -> () Source #
Eq Doc Source # |
Instance details Defined in Text.PrettyPrint.HughesPJ Methods (==) :: Doc -> Doc -> Bool Source # (/=) :: Doc -> Doc -> Bool Source #
type Rep Doc Source # |
Instance details Defined in Text.PrettyPrint.HughesPJ type Rep Doc = D1 ('MetaData "Doc" "Text.PrettyPrint.HughesPJ" "pretty-1.1.3.6" 'True) (C1 ('MetaCons "Doc" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc ()))))

data TextDetails Source #

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

Instances details

Generic TextDetails Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Associated Types type Rep TextDetails :: Type -> Type Source # Methods from :: TextDetails -> Rep TextDetails x Source # to :: Rep TextDetails x -> TextDetails Source #
Show TextDetails Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Methods showsPrec :: Int -> TextDetails -> ShowS Source # show :: TextDetails -> String Source # showList :: [TextDetails] -> ShowS Source #
NFData TextDetails Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Methods rnf :: TextDetails -> () Source #
Eq TextDetails Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Methods (==) :: TextDetails -> TextDetails -> Bool Source # (/=) :: TextDetails -> TextDetails -> Bool Source #
type Rep TextDetails Source # |

Instance details

Defined in Text.PrettyPrint.Annotated.HughesPJ

type Rep TextDetails = D1 ('MetaData "TextDetails" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.6" 'False) (C1 ('MetaCons "Chr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Char)) :+: (C1 ('MetaCons "Str" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)) :+: C1 ('MetaCons "PStr" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String))))

# Constructing documents

## Converting values into documents

char :: Char -> Doc Source #

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

text :: String -> Doc Source #

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 Source #

Same as `text`. Used to be used for Bytestrings.

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

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

zeroWidthText :: String -> Doc Source #

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

int Source #

Arguments

:: Int |

-> Doc

    int n = text (show n)

integer Source #

Arguments

:: Integer |

-> Doc

    integer n = text (show n)

float Source #

Arguments

:: Float |

-> Doc

    float n = text (show n)

double Source #

Arguments

:: Double |

-> Doc

    double n = text (show n)

rational Source #

Arguments

:: Rational |

-> Doc

    rational n = text (show n)

## Simple derived documents

semi Source #

Arguments

:: Doc | A ';' character

comma Source #

Arguments

:: Doc | A ',' character

colon Source #

Arguments

:: Doc | A `:` character

space Source #

Arguments

:: Doc | A space character

equals Source #

Arguments

:: Doc | A '=' character

lparen Source #

Arguments

:: Doc | A '(' character

rparen Source #

Arguments

:: Doc | A ')' character

lbrack Source #

Arguments

:: Doc | A '[' character

rbrack Source #

Arguments

:: Doc | A ']' character

lbrace Source #

Arguments

:: Doc | A '{' character

rbrace Source #

Arguments

:: Doc | A '}' character

## Wrapping documents in delimiters

parens Source #

Arguments

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

brackets Source #

Arguments

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

braces Source #

Arguments

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

quotes Source #

Arguments

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

doubleQuotes Source #

Arguments

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

maybeParens :: Bool -> Doc -> Doc Source #

Apply `parens` to `Doc` if boolean is true.

maybeBrackets :: Bool -> Doc -> Doc Source #

Apply `brackets` to `Doc` if boolean is true.

maybeBraces :: Bool -> Doc -> Doc Source #

Apply `braces` to `Doc` if boolean is true.

maybeQuotes :: Bool -> Doc -> Doc Source #

Apply `quotes` to `Doc` if boolean is true.

maybeDoubleQuotes :: Bool -> Doc -> Doc Source #

Apply `doubleQuotes` to `Doc` if boolean is true.

## Combining documents

empty :: Doc Source #

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 -> Doc -> Doc infixl 6 Source #

Beside. `<>` is associative, with identity `empty`.

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

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

hcat :: [Doc] -> Doc Source #

List version of `<>`.

hsep :: [Doc] -> Doc Source #

List version of `<+>`.

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

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 -> Doc -> Doc infixl 5 Source #

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

vcat :: [Doc] -> Doc Source #

List version of `$$`.

sep :: [Doc] -> Doc Source #

Either `hsep` or `vcat`.

cat :: [Doc] -> Doc Source #

Either `hcat` or `vcat`.

fsep :: [Doc] -> Doc Source #

"Paragraph fill" version of `sep`.

fcat :: [Doc] -> Doc Source #

"Paragraph fill" version of `cat`.

nest :: Int -> Doc -> Doc Source #

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 x <> 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 -> Int -> Doc -> Doc Source #

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

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

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

# Predicates on documents

isEmpty :: Doc -> Bool Source #

Returns `True` if the document is empty

# Utility functions for documents

first :: Doc -> Doc -> Doc Source #

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

reduceDoc :: Doc -> RDoc Source #

Perform some simplification of a built up `GDoc`.

# Rendering documents

## Default rendering

render :: Doc -> String Source #

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

## Rendering with a particular style

data Style Source #

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

Instances details

Generic Style Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Associated Types type Rep Style :: Type -> Type Source # Methods from :: Style -> Rep Style x Source # to :: Rep Style x -> Style Source #
Show Style Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Methods showsPrec :: Int -> Style -> ShowS Source # show :: Style -> String Source # showList :: [Style] -> ShowS Source #
Eq Style Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Methods (==) :: Style -> Style -> Bool Source # (/=) :: Style -> Style -> Bool Source #
type Rep Style Source # |

Instance details

Defined in Text.PrettyPrint.Annotated.HughesPJ

type Rep Style = D1 ('MetaData "Style" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.6" '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))))

style :: Style Source #

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

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

Render the `Doc` to a String using the given `Style`.

data Mode Source #

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

Instances details

Generic Mode Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Associated Types type Rep Mode :: Type -> Type Source # Methods from :: Mode -> Rep Mode x Source # to :: Rep Mode x -> Mode Source #
Show Mode Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Methods showsPrec :: Int -> Mode -> ShowS Source # show :: Mode -> String Source # showList :: [Mode] -> ShowS Source #
Eq Mode Source # |
Instance details Defined in Text.PrettyPrint.Annotated.HughesPJ Methods (==) :: Mode -> Mode -> Bool Source # (/=) :: Mode -> Mode -> Bool Source #
type Rep Mode Source # |

Instance details

Defined in Text.PrettyPrint.Annotated.HughesPJ

type Rep Mode = D1 ('MetaData "Mode" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.6" 'False) ((C1 ('MetaCons "PageMode" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ZigZagMode" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "LeftMode" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "OneLineMode" 'PrefixI 'False) (U1 :: Type -> Type)))

## General rendering

fullRender Source #

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