pretty-1.0.1.2: Pretty-printing library

Portability | portable
Stability | provisional
Maintainer | libraries@haskell.org

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
- Rendering documents
  - Default rendering
  - Rendering with a particular style
  - General rendering

Description

John Hughes's and Simon Peyton Jones's Pretty Printer Combinators

Based on The Design of a Pretty-printing Library in Advanced Functional Programming, Johan Jeuring and Erik Meijer (eds), LNCS 925 http://www.cs.chalmers.se/~rjmh/Papers/pretty.ps

Heavily modified by Simon Peyton Jones, Dec 96

Synopsis

- data Doc
- char :: Char -> Doc
- text :: String -> Doc
- ptext :: 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
- 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
- render :: Doc -> String
- data Style = Style {
  - mode :: Mode
  - lineLength :: Int
  - ribbonsPerLine :: Float
  }
- style :: Style
- renderStyle :: Style -> Doc -> String
- fullRender :: Mode -> Int -> Float -> (TextDetails -> a -> a) -> a -> Doc -> a
- data Mode
  - = PageMode
  - | ZigZagMode
  - | LeftMode
  - | OneLineMode
- data TextDetails
  - = Chr Char
  - | Str String
  - | PStr String

# The document type

data Doc Source

The abstract type of documents. The `Show` instance is equivalent to using `render`.

Instances

Show Doc |

# 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

An obsolete function, now identical to `text`.

zeroWidthText :: String -> Doc Source

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

int :: Int -> Doc Source

    int n = text (show n)

integer :: Integer -> Doc Source

    integer n = text (show n)

float :: Float -> Doc Source

    float n = text (show n)

double :: Double -> Doc Source

    double n = text (show n)

rational :: Rational -> Doc Source

    rational n = text (show n)

## Simple derived documents

semi :: Doc Source

A ';' character

comma :: Doc Source

A ',' character

colon :: Doc Source

A `:` character

space :: Doc Source

A space character

equals :: Doc Source

A '=' character

lparen :: Doc Source

A '(' character

rparen :: Doc Source

A ')' character

lbrack :: Doc Source

A '[' character

rbrack :: Doc Source

A ']' character

lbrace :: Doc Source

A '{' character

rbrace :: Doc Source

A '}' character

## Wrapping documents in delimiters

parens :: Doc -> Doc Source

Wrap document in `(...)`

brackets :: Doc -> Doc Source

Wrap document in `[...]`

braces :: Doc -> Doc Source

Wrap document in `{...}`

quotes :: Doc -> Doc Source

Wrap document in `'...'`

doubleQuotes :: Doc -> Doc Source

Wrap document in `"..."`

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

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

(<+>) :: Doc -> Doc -> Doc 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 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 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

# Rendering documents

## Default rendering

render :: Doc -> String Source

Renders the document as 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 ribbon length to line length

style :: Style Source

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

renderStyle :: Style -> Doc -> String Source

Render the document as a string using a specified style.

## General rendering

fullRenderSource

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.

data Mode Source

Rendering mode.

Constructors

PageMode | Normal
ZigZagMode | With zig-zag cuts
LeftMode | No indentation, infinitely long lines
OneLineMode | All on one line

data TextDetails Source

Constructors

Chr Char |
Str String |
PStr String |