pretty-1.1.1.0: Pretty-printing library

Portability | portable
Stability | stable
Maintainer | David Terei <dave.terei@gmail.com>
Safe Haskell | Safe

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

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 (December 1996).

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

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

Show Doc |
IsString Doc |
Monoid Doc |

data TextDetails

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.

# Constructing documents

## Converting values into documents

char :: Char -> Doc

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

text :: String -> Doc

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

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

sizedText :: Int -> String -> Doc

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

zeroWidthText :: String -> Doc

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

int

Arguments

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

integer

Arguments

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

float

Arguments

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

double

Arguments

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

rational

Arguments

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

## Simple derived documents

semi

Arguments

:: Doc | A ';' character

comma

Arguments

:: Doc | A ',' character

colon

Arguments

:: Doc | A `:` character

space

Arguments

:: Doc | A space character

equals

Arguments

:: Doc | A '=' character

lparen

Arguments

:: Doc | A '(' character

rparen

Arguments

:: Doc | A ')' character

lbrack

Arguments

:: Doc | A '[' character

rbrack

Arguments

:: Doc | A ']' character

lbrace

Arguments

:: Doc | A '{' character

rbrace

Arguments

:: Doc | A '}' character

## Wrapping documents in delimiters

parens

Arguments

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

brackets

Arguments

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

braces

Arguments

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

quotes

Arguments

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

doubleQuotes

Arguments

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

## Combining documents

empty :: Doc

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

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

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

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

hcat :: [Doc] -> Doc

List version of `<>`.

hsep :: [Doc] -> Doc

List version of `<+>`.

($$) :: Doc -> Doc -> Doc

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

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

vcat :: [Doc] -> Doc

List version of `$$`.

sep :: [Doc] -> Doc

Either `hsep` or `vcat`.

cat :: [Doc] -> Doc

Either `hcat` or `vcat`.

fsep :: [Doc] -> Doc

"Paragraph fill" version of `sep`.

fcat :: [Doc] -> Doc

"Paragraph fill" version of `cat`.

nest :: Int -> Doc -> Doc

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

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

punctuate :: Doc -> [Doc] -> [Doc]

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

# Predicates on documents

isEmpty :: Doc -> Bool

Returns `True` if the document is empty

# Utility functions for documents

first :: Doc -> Doc -> Doc

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

reduceDoc :: Doc -> RDoc a

Perform some simplification of a built up `GDoc`.

# Rendering documents

## Default rendering

render :: Doc -> String

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

## Rendering with a particular style

data Style

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

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

renderStyle :: Style -> Doc -> String

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

data Mode

Rendering mode.

Constructors

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

## General rendering

fullRender

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.