Outputable

Contents

Description

This module defines classes and functions for pretty-printing. It also exports a number of helpful debugging and other utilities such as trace and panic.

The interface to this module is very similar to the standard Hughes-PJ pretty printing module, except that it exports a number of additional functions that are rarely used, and works over the SDoc type.

Synopsis

Type classes

class Outputable a where

Class designating that some type has an SDoc representation

Methods

ppr :: a -> SDoc

class Outputable a => OutputableBndr a where

When we print a binder, we often want to print its type too. The OutputableBndr class encapsulates this idea.

Methods

pprBndr :: BindingSite -> a -> SDoc

Pretty printing combinators

type SDoc = PprStyle -> Doc

docToSDoc :: Doc -> SDoc

interppSP :: Outputable a => [a] -> SDoc

Returns the seperated concatenation of the pretty printed things.

interpp'SP :: Outputable a => [a] -> SDoc

Returns the comma-seperated concatenation of the pretty printed things.

pprQuotedList :: Outputable a => [a] -> SDoc

Returns the comma-seperated concatenation of the quoted pretty printed things.

 [x,y,z]  ==>  `x', `y', `z'

pprWithCommas

Arguments

:: (a -> SDoc)	The pretty printing function to use
-> [a]	The things to be pretty printed
-> SDoc	`SDoc` where the things have been pretty printed, comma-separated and finally packed into a paragraph.

quotedListWithOr :: [SDoc] -> SDoc

empty :: SDoc

nest :: Int -> SDoc -> SDoc

Indent SDoc some specified amount

char :: Char -> SDoc

text :: String -> SDoc

ftext :: FastString -> SDoc

ptext :: LitString -> SDoc

int :: Int -> SDoc

integer :: Integer -> SDoc

float :: Float -> SDoc

double :: Double -> SDoc

rational :: Rational -> SDoc

parens :: SDoc -> SDoc

cparen :: Bool -> SDoc -> SDoc

brackets :: SDoc -> SDoc

braces :: SDoc -> SDoc

quotes :: SDoc -> SDoc

doubleQuotes :: SDoc -> SDoc

angleBrackets :: SDoc -> SDoc

semi :: SDoc

comma :: SDoc

colon :: SDoc

dcolon :: SDoc

space :: SDoc

equals :: SDoc

dot :: SDoc

arrow :: SDoc

darrow :: SDoc

lparen :: SDoc

rparen :: SDoc

lbrack :: SDoc

rbrack :: SDoc

lbrace :: SDoc

rbrace :: SDoc

underscore :: SDoc

blankLine :: SDoc

(<>) :: SDoc -> SDoc -> SDoc

Join two SDoc together horizontally without a gap

(<+>) :: SDoc -> SDoc -> SDoc

Join two SDoc together horizontally with a gap between them

hcat :: [SDoc] -> SDoc

Concatenate SDoc horizontally

hsep :: [SDoc] -> SDoc

Concatenate SDoc horizontally with a space between each one

($$) :: SDoc -> SDoc -> SDoc

Join two SDoc together vertically; if there is no vertical overlap it dovetails the two onto one line

($+$) :: SDoc -> SDoc -> SDoc

Join two SDoc together vertically

vcat :: [SDoc] -> SDoc

Concatenate SDoc vertically with dovetailing

sep :: [SDoc] -> SDoc

Separate: is either like hsep or like vcat, depending on what fits

cat :: [SDoc] -> SDoc

Catenate: is either like hcat or like vcat, depending on what fits

fsep :: [SDoc] -> SDoc

A paragraph-fill combinator. It's much like sep, only it keeps fitting things on one line until it can't fit any more.

fcat :: [SDoc] -> SDoc

This behaves like fsep, but it uses <> for horizontal conposition rather than <+>

hang

Arguments

:: SDoc	The header
-> Int	Amount to indent the hung body
-> SDoc	The hung body, indented and placed below the header
-> SDoc

punctuate

Arguments

:: SDoc	The punctuation
-> [SDoc]	The list that will have punctuation added between every adjacent pair of elements
-> [SDoc]	Punctuated list

ppWhen :: Bool -> SDoc -> SDoc

ppUnless :: Bool -> SDoc -> SDoc

speakNth :: Int -> SDoc

Converts an integer to a verbal index:

 speakNth 1 = text "first"
 speakNth 5 = text "fifth"
 speakNth 21 = text "21st"

speakNTimes :: Int -> SDoc

Converts a strictly positive integer into a number of times:

 speakNTimes 1 = text "once"
 speakNTimes 2 = text "twice"
 speakNTimes 4 = text "4 times"

speakN :: Int -> SDoc

Converts an integer to a verbal multiplicity:

 speakN 0 = text "none"
 speakN 5 = text "five"
 speakN 10 = text "10"

speakNOf :: Int -> SDoc -> SDoc

Converts an integer and object description to a statement about the multiplicity of those objects:

 speakNOf 0 (text "melon") = text "no melons"
 speakNOf 1 (text "melon") = text "one melon"
 speakNOf 3 (text "melon") = text "three melons"

plural :: [a] -> SDoc

Determines the pluralisation suffix appropriate for the length of a list:

 plural [] = char 's'
 plural ["Hello"] = empty
 plural ["Hello", "World"] = char 's'

Converting `SDoc` into strings and outputing it

printSDoc :: SDoc -> PprStyle -> IO ()

printErrs :: Doc -> IO ()

printOutput :: Doc -> IO ()

hPrintDump :: Handle -> SDoc -> IO ()

printDump :: SDoc -> IO ()

printForC :: Handle -> SDoc -> IO ()

printForAsm :: Handle -> SDoc -> IO ()

printForUser :: Handle -> PrintUnqualified -> SDoc -> IO ()

printForUserPartWay :: Handle -> Int -> PrintUnqualified -> SDoc -> IO ()

pprCode :: CodeStyle -> SDoc -> SDoc

mkCodeStyle :: CodeStyle -> PprStyle

showSDoc :: SDoc -> String

showSDocOneLine :: SDoc -> String

showSDocForUser :: PrintUnqualified -> SDoc -> String

showSDocDebug :: SDoc -> String

showSDocDump :: SDoc -> String

showSDocDumpOneLine :: SDoc -> String

showPpr :: Outputable a => a -> String

showSDocUnqual :: SDoc -> String

showsPrecSDoc :: Int -> SDoc -> ShowS

pprInfixVar :: Bool -> SDoc -> SDoc

pprPrefixVar :: Bool -> SDoc -> SDoc

pprHsChar :: Char -> SDoc

Special combinator for showing character literals.

pprHsString :: FastString -> SDoc

Special combinator for showing string literals.

pprHsInfix :: Outputable name => name -> SDoc

pprHsVar :: Outputable name => name -> SDoc

pprFastFilePath :: FastString -> SDoc

Controlling the style in which output is printed

data BindingSite

BindingSite is used to tell the thing that prints binder what language construct is binding the identifier. This can be used to decide how much info to print.

Constructors

LambdaBind
CaseBind
LetBind

data PprStyle

data CodeStyle

Constructors

CStyle
AsmStyle

type PrintUnqualified = (QueryQualifyName, QueryQualifyModule)

alwaysQualify :: PrintUnqualified

neverQualify :: PrintUnqualified

data QualifyName

Constructors

NameUnqual
NameQual ModuleName
NameNotInScope1
NameNotInScope2

getPprStyle :: (PprStyle -> SDoc) -> SDoc

withPprStyle :: PprStyle -> SDoc -> SDoc

withPprStyleDoc :: PprStyle -> SDoc -> Doc

pprDeeper :: SDoc -> SDoc

pprDeeperList :: ([SDoc] -> SDoc) -> [SDoc] -> SDoc

pprSetDepth :: Depth -> SDoc -> SDoc

codeStyle :: PprStyle -> Bool

userStyle :: PprStyle -> Bool

debugStyle :: PprStyle -> Bool

dumpStyle :: PprStyle -> Bool

asmStyle :: PprStyle -> Bool

ifPprDebug :: SDoc -> SDoc

qualName :: PprStyle -> QueryQualifyName

qualModule :: PprStyle -> QueryQualifyModule

mkErrStyle :: PrintUnqualified -> PprStyle

Style for printing error messages

defaultErrStyle :: PprStyle

defaultDumpStyle :: PprStyle

defaultUserStyle :: PprStyle

mkUserStyle :: PrintUnqualified -> Depth -> PprStyle

cmdlineParserStyle :: PprStyle

data Depth

Constructors

AllTheWay
PartWay Int

Error handling and debugging utilities

pprPanic :: String -> SDoc -> a

Throw an exception saying bug in GHC

pprSorry :: String -> SDoc -> a

Throw an exceptio saying this isn't finished yet

assertPprPanic :: String -> Int -> SDoc -> a

Panic with an assertation failure, recording the given file and line number. Should typically be accessed with the ASSERT family of macros

pprPanicFastInt :: String -> SDoc -> FastInt

Specialization of pprPanic that can be safely used with FastInt

pprPgmError :: String -> SDoc -> a

Throw an exception saying bug in pgm being compiled (used for unusual program errors)

pprTrace :: String -> SDoc -> a -> a

If debug output is on, show some SDoc on the screen

warnPprTrace :: Bool -> String -> Int -> SDoc -> a -> a

Just warn about an assertion failure, recording the given file and line number. Should typically be accessed with the WARN macros

trace :: String -> a -> aSource

When called, trace outputs the string in its first argument, before returning the second argument as its result. The trace function is not referentially transparent, and should only be used for debugging, or for monitoring execution. Some implementations of trace may decorate the string that's output to indicate that you're tracing. The function is implemented on top of putTraceMsg.

pgmError :: String -> a

panic :: String -> a

sorry :: String -> a

Panics and asserts.

panicFastInt :: String -> FastInt

Panic while pretending to return an unboxed int. You can't use the regular panic functions in expressions producing unboxed ints because they have the wrong kind.

assertPanic :: String -> Int -> a

Throw an failed assertion exception for a given filename and line number.

Type classes

Pretty printing combinators

Converting SDoc into strings and outputing it

Controlling the style in which output is printed

Error handling and debugging utilities

Converting `SDoc` into strings and outputing it