ghc-9.12.0.20241128: The GHC API
Copyright(c) The University of Glasgow 2001
LicenseBSD-style (see the file LICENSE)
MaintainerDavid Terei <code@davidterei.com>
Stabilitystable
Portabilityportable
Safe HaskellNone
LanguageGHC2021

GHC.Utils.Ppr

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

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
Show Doc Source # 
Instance details

Defined in GHC.Utils.Ppr

Methods

showsPrec :: Int -> Doc -> ShowS #

show :: Doc -> String #

showList :: [Doc] -> ShowS #

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

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:

The side condition on the last law is necessary because text "" has height 1, while empty has no height.

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

emptyText :: Doc Source #

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

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)

hex Source #

Arguments

:: Integer 
-> Doc

See Note [Print Hexadecimal Literals]

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

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

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:

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]

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

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

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

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

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

A rendering style.

Constructors

Style 

Fields

style :: Style Source #

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

Fields

ZigZagMode

With zig-zag cuts

LeftMode

No indentation, infinitely long lines

OneLineMode

All on one line

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.

txtPrinter :: TextDetails -> String -> String Source #

Default TextDetails printer

GHC-specific rendering

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

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