Text.PrettyPrint.HughesPJ

pretty-1.1.3.2: 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

Eq Doc |
Methods (==) :: Doc -> Doc -> Bool Source (/=) :: Doc -> Doc -> Bool Source
Show Doc |
Methods showsPrec :: Int -> Doc -> ShowS Source show :: Doc -> String Source showList :: [Doc] -> ShowS Source
IsString Doc |
Methods fromString :: String -> Doc Source
Generic Doc |
Associated Types type Rep Doc :: * -> * Source Methods from :: Doc -> Rep Doc x Source to :: Rep Doc x -> Doc Source
Monoid Doc |
Methods mempty :: Doc Source mappend :: Doc -> Doc -> Doc Source mconcat :: [Doc] -> Doc Source
NFData Doc |
Methods rnf :: Doc -> () Source
type Rep Doc = D1 (MetaData "Doc" "Text.PrettyPrint.HughesPJ" "pretty-1.1.3.2" True) (C1 (MetaCons "Doc" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Doc ())))) |

data TextDetails Source

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 |
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 = D1 (MetaData "TextDetails" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.2" 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))))) |

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

## Rendering with a particular style

data Style Source

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 |
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 = D1 (MetaData "Style" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.2" 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 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
ZigZagMode | With zig-zag cuts
LeftMode | No indentation, infinitely long lines
OneLineMode | All on one line

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 = D1 (MetaData "Mode" "Text.PrettyPrint.Annotated.HughesPJ" "pretty-1.1.3.2" 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))) |

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