ghc-lib-parser-9.10.1.20250103: The GHC API, decoupled from GHC versions

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 | Ignore
Language | GHC2021

GHC.Utils.Ppr

Contents

- The document type
- Constructing documents
  - Converting values into documents
  - Simple derived documents
  - Wrapping documents in delimiters
  - Combining documents
- Predicates on documents
- Rendering documents
  - Rendering with a particular style
  - General rendering
  - GHC-specific 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.cse.chalmers.se/~rjmh/Papers/pretty.ps

Synopsis

- data Doc
- data TextDetails
  - = Chr !Char
  - | Str String
  - | PStr FastString
  - | ZStr FastZString
  - | LStr !PtrString
  - | RStr !Int !Char
- char :: Char -> Doc
- text :: String -> Doc
- ftext :: FastString -> Doc
- ptext :: PtrString -> Doc
- ztext :: FastZString -> Doc
- sizedText :: Int -> String -> Doc
- zeroWidthText :: String -> Doc
- emptyText :: Doc
- int :: Int -> Doc
- integer :: Integer -> Doc
- float :: Float -> Doc
- double :: Double -> Doc
- rational :: Rational -> Doc
- hex :: Integer -> 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
- squotes :: Doc -> Doc
- quote :: Doc -> Doc
- doubleQuotes :: Doc -> Doc
- maybeParens :: 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
- hangNotEmpty :: Doc -> Int -> Doc -> Doc
- punctuate :: Doc -> [Doc] -> [Doc]
- isEmpty :: Doc -> Bool
- docHead :: Doc -> (Maybe Char, Doc)
- data Style = Style {
  - mode :: Mode
  - lineLength :: Int
  - ribbonsPerLine :: Float
  }
- style :: Style
- renderStyle :: Style -> Doc -> String
- data Mode
  - = PageMode {
    - asciiSpace :: Bool
    }
  - | ZigZagMode
  - | LeftMode
  - | OneLineMode
- fullRender :: Mode -> Int -> Float -> (TextDetails -> a -> a) -> a -> Doc -> a
- txtPrinter :: TextDetails -> String -> String
- printDoc :: Mode -> Int -> Handle -> Doc -> IO ()
- printDoc_ :: Mode -> Int -> Handle -> Doc -> IO ()
- bufLeftRender :: BufHandle -> Doc -> IO ()
- printLeftRender :: Handle -> Doc -> IO ()

# 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

Instances details

Show Doc # |
Instance details Defined in GHC.Utils.Ppr Methods showsPrec :: Int -> Doc -> ShowS # show :: Doc -> String # showList :: [Doc] -> ShowS #

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 FastString |
ZStr FastZString |
LStr !PtrString |
RStr !Int !Char |

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

ftext :: FastString -> Doc #

ptext :: PtrString -> Doc #

ztext :: FastZString -> Doc #

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

emptyText :: Doc #

Empty text (one line high but no width). (`emptyText = text ""`)

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)

hex #

Arguments

:: Integer |
-> Doc | See Note [Print Hexadecimal Literals]

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

squotes #

Arguments

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

quote :: Doc -> Doc #

doubleQuotes #

Arguments

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

maybeParens :: Bool -> Doc -> Doc #

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

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

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

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

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

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 #

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]

hangNotEmpty :: Doc -> Int -> Doc -> Doc #

Apply `hang` to the arguments if the first `Doc` is not empty.

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

docHead :: Doc -> (Maybe Char, Doc) #

Get the first character of a document. We also return a new document, equivalent to the original one but faster to render. Use it to avoid work duplication.

# Rendering documents

## 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 line length to ribbon length

style :: Style #

The default style (`mode=PageMode False, 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

Fields

- asciiSpace :: Bool

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.

txtPrinter :: TextDetails -> String -> String #

Default TextDetails printer

## GHC-specific rendering

printDoc :: Mode -> Int -> Handle -> Doc -> IO () #

printDoc_ :: Mode -> Int -> Handle -> Doc -> IO () #

bufLeftRender :: BufHandle -> Doc -> IO () #

printLeftRender :: Handle -> Doc -> IO () #