ghc-7.0.4: The GHC API

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

Instances

Outputable Bool 
Outputable Char 
Outputable Int 
Outputable Word 
Outputable Word16 
Outputable Word32 
Outputable () 
Outputable OccName 
Outputable PackageId 
Outputable ModuleName 
Outputable Module 
Outputable FastString 
Outputable InlineSpec 
Outputable InlinePragma 
Outputable RuleMatchInfo 
Outputable Activation 
Outputable CompilerPhase 
Outputable SuccessFlag 
Outputable DefMethSpec 
Outputable StrictnessMark 
Outputable HsBang 
Outputable OccInfo 
Outputable OverlapFlag 
Outputable RecFlag 
Outputable TopLevelFlag 
Outputable FixityDirection 
Outputable Fixity 
Outputable WarningTxt 
Outputable FunctionOrData 
Outputable Unique 
Outputable IdDetails 
Outputable SrcSpan 
Outputable SrcLoc 
Outputable MetaDetails 
Outputable SlotSet 
Outputable StackPlacement 
Outputable SlotClass 
Outputable HsDocString 
Outputable Fingerprint 
Outputable Phase 
Outputable TyCon 
Outputable TyThing 
Outputable PredType 
Outputable Type 
Outputable Name 
Outputable ModLocation 
Outputable CCallConv 
Outputable CCallSpec 
Outputable CExportSpec 
Outputable Safety 
Outputable ForeignCall 
Outputable Serialized 
Outputable Var 
Outputable InScopeSet 
Outputable StrictSig 
Outputable DmdResult 
Outputable DmdType 
Outputable Demands 
Outputable Demand 
Outputable StableLoc 
Outputable VolatileLoc 
Outputable CgIdInfo 
Outputable DataCon 
Outputable DefMeth 
Outputable Class 
Outputable ImportSpec 
Outputable Parent 
Outputable GlobalRdrElt 
Outputable RdrName 
Outputable PrimRep 
Outputable CoTyConDesc 
Outputable TvSubst 
Outputable OverLitVal 
Outputable HsLit 
Outputable CoercionI 
Outputable Literal 
Outputable GhcMode 
Outputable CostCentre 
Outputable CostCentreStack 
Outputable UnfoldingGuidance 
Outputable UnfoldingSource 
Outputable Unfolding 
Outputable CoreRule 
Outputable AltCon 
Outputable PrimCall 
Outputable PrimOp 
Outputable TickBoxOp 
Outputable LBVarInfo 
Outputable CafInfo 
Outputable ForeignLabelSource 
Outputable CLabel 
Outputable BlockSet 
Outputable BlockId 
Outputable Width 
Outputable CmmCat 
Outputable CmmType 
Outputable GlobalReg 
Outputable LocalReg 
Outputable CmmLit 
Outputable Area 
Outputable CmmReg 
Outputable CmmExpr 
Outputable CgRep 
Outputable UpdateFlag 
Outputable AltType 
Outputable C_SRT 
Outputable CmmStatic 
Outputable ForeignHint 
Outputable CmmSafety 
Outputable CmmStmt 
Outputable CmmInfo 
Outputable ValueDirection 
Outputable ForeignConvention 
Outputable Convention 
Outputable Last 
Outputable Middle 
Outputable AvailRegs 
Outputable DualLive 
Outputable CgLoc 
Outputable CgIdInfo 
Outputable Protocol 
Outputable Status 
Outputable CmmTopForInfoTables 
Outputable TopSRT 
Outputable LRep 
Outputable OccEncl 
Outputable Subst 
Outputable EtaInfo 
Outputable ArgSummary 
Outputable CallCtxt 
Outputable ExprSize 
Outputable AnalEnv 
Outputable TcSpecPrag 
Outputable EvTerm 
Outputable EvBind 
Outputable EvBindsVar 
Outputable TcEvBinds 
Outputable HsWrapper 
Outputable DocDecl 
Outputable ForeignExport 
Outputable ForeignImport 
Outputable NewOrData 
Outputable Annotation 
Outputable IfaceTyCon 
Outputable IfacePredType 
Outputable IfaceType 
Outputable IfaceBndr 
Outputable IfaceConAlt 
Outputable IfaceNote 
Outputable IfaceExpr 
Outputable IfaceUnfolding 
Outputable IfaceInfoItem 
Outputable IfaceIdInfo 
Outputable IfaceIdDetails 
Outputable IfaceRule 
Outputable IfaceFamInst 
Outputable IfaceInst 
Outputable IfaceClassOp 
Outputable IfaceDecl 
Outputable ClsInstEnv 
Outputable Instance 
Outputable FamilyInstEnv 
Outputable FamInst 
Outputable Unlinked 
Outputable Linkable 
Outputable ModSummary 
Outputable FixItem 
Outputable Warnings 
Outputable CoreModule 
Outputable TargetId 
Outputable Target 
Outputable EqOrigin 
Outputable CtOrigin 
Outputable SkolemInfo 
Outputable CtFlavor 
Outputable Implication 
Outputable Untouchables 
Outputable WantedConstraints 
Outputable WhereFrom 
Outputable TcTyThing 
Outputable ThStage 
Outputable TcTyVarBind 
Outputable IfaceDeclExtras 
Outputable EquationInfo 
Outputable Tick 
Outputable FloatOutSwitches 
Outputable SimplifierMode 
Outputable CoreToDo 
Outputable OkToSpec 
Outputable Floats 
Outputable FloatingBind 
Outputable Level 
Outputable FloatFlag 
Outputable Floats 
Outputable SimplSR 
Outputable DupFlag 
Outputable SimplCont 
Outputable CallInfoSet 
Outputable CallKey 
Outputable UsageDetails 
Outputable ArgOcc 
Outputable HowBound 
Outputable Value 
Outputable SimplContext 
Outputable CanonicalCt 
Outputable SwapFlag 
Outputable TcSigInfo 
Outputable StageResult 
Outputable StopOrContinue 
Outputable InertSet 
Outputable GeneralisationPlan 
Outputable a => Outputable [a] 
Outputable a => Outputable (Maybe a) 
Outputable name => Outputable (IPName name) 
Outputable a => Outputable (UniqFM a) 
Outputable e => Outputable (Located e) 
OutputableBndr name => Outputable (Pat name) 
Outputable a => Outputable (SCC a) 
Outputable node => Outputable (Edge node) 
Outputable node => Outputable (Graph node) 
Outputable a => Outputable (Bag a) 
OutputableBndr id => Outputable (HsSplice id) 
OutputableBndr id => Outputable (HsExpr id) 
Outputable name => Outputable (IE name) 
Outputable name => Outputable (ImportDecl name) 
Outputable a => Outputable (OccEnv a) 
Outputable name => Outputable (HsTyVarBndr name) 
OutputableBndr name => Outputable (HsType name) 
OutputableBndr name => Outputable (HsPred name) 
OutputableBndr id => Outputable (HsQuasiQuote id) 
OutputableBndr id => Outputable (HsOverLit id) 
Outputable b => Outputable (TaggedBndr b) 
Outputable e => Outputable (DFunArg e) 
OutputableBndr b => Outputable (Bind b) 
OutputableBndr b => Outputable (Expr b) 
Outputable a => Outputable (BlockEnv a) 
Outputable bdee => Outputable (GenStgArg bdee) 
Outputable a => Outputable (CmmHinted a) 
Outputable instr => Outputable (GenBasicBlock instr) 
Outputable instr => Outputable (ListGraph instr) 
Outputable l => Outputable (ZLast l) 
Outputable a => Outputable (ParamLocation a) 
Outputable a => Outputable (NonVoid a) 
Outputable name => Outputable (FixitySig name) 
OutputableBndr name => Outputable (Sig name) 
OutputableBndr id => Outputable (IPBind id) 
OutputableBndr id => Outputable (HsIPBinds id) 
OutputableBndr name => Outputable (AnnDecl name) 
OutputableBndr name => Outputable (WarnDecl name) 
OutputableBndr name => Outputable (RuleBndr name) 
OutputableBndr name => Outputable (RuleDecl name) 
OutputableBndr name => Outputable (ForeignDecl name) 
OutputableBndr name => Outputable (DefaultDecl name) 
OutputableBndr name => Outputable (DerivDecl name) 
OutputableBndr name => Outputable (InstDecl name) 
OutputableBndr name => Outputable (ResType name) 
OutputableBndr name => Outputable (ConDecl name) 
OutputableBndr name => Outputable (TyClDecl name) 
OutputableBndr name => Outputable (SpliceDecl name) 
OutputableBndr name => Outputable (HsGroup name) 
OutputableBndr name => Outputable (HsDecl name) 
OutputableBndr id => Outputable (ArithSeqInfo id) 
OutputableBndr id => Outputable (HsBracket id) 
OutputableBndr id => Outputable (HsCmdTop id) 
Outputable name => Outputable (AnnTarget name) 
OutputableBndr name => Outputable (HsModule name) 
Outputable n => Outputable (GenAvailInfo n) 
Outputable (EvVarX a) 
(Outputable a, Outputable b) => Outputable (Either a b) 
(Outputable a, Outputable b) => Outputable (a, b) 
(Outputable key, Outputable elt) => Outputable (Map key elt) 
(Outputable bndr, Outputable bdee, Ord bdee) => Outputable (GenStgRhs bndr bdee) 
(Outputable bndr, Outputable bdee, Ord bdee) => Outputable (GenStgExpr bndr bdee) 
(Outputable bndr, Outputable bdee, Ord bdee) => Outputable (GenStgBinding bndr bdee) 
(Outputable m, Outputable l, LastNode l) => Outputable (LGraph m l) 
(Outputable m, Outputable l, LastNode l) => Outputable (Graph m l) 
(Outputable m, Outputable l, LastNode l) => Outputable (Block m l) 
(Outputable m, Outputable l) => Outputable (ZTail m l) 
(OutputableBndr idL, OutputableBndr idR) => Outputable (HsBindLR idL idR) 
(OutputableBndr idL, OutputableBndr idR) => Outputable (HsValBindsLR idL idR) 
(OutputableBndr idL, OutputableBndr idR) => Outputable (HsLocalBindsLR idL idR) 
(OutputableBndr id, Outputable arg) => Outputable (HsRecField id arg) 
(OutputableBndr id, Outputable arg) => Outputable (HsRecFields id arg) 
(OutputableBndr idL, OutputableBndr idR) => Outputable (StmtLR idL idR) 
(Outputable a, Outputable b, Outputable c) => Outputable (a, b, c) 
(Outputable d, Outputable info, Outputable i) => Outputable (GenCmmTop d info i) 
(Outputable d, Outputable info, Outputable g) => Outputable (GenCmm d info g) 
(Outputable a, Outputable b, Outputable c, Outputable d) => Outputable (a, b, c, d) 
(Outputable a, Outputable b, Outputable c, Outputable d, Outputable e) => Outputable (a, b, c, d, e) 

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

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.

nest :: Int -> SDoc -> SDoc

Indent SDoc some specified amount

char :: Char -> SDoc

int :: Int -> SDoc

cparen :: Bool -> SDoc -> 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

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

printErrs :: Doc -> IO ()

printOutput :: Doc -> IO ()

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

printDump :: SDoc -> IO ()

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

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

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)

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

qualName :: PprStyle -> QueryQualifyName

qualModule :: PprStyle -> QueryQualifyModule

mkErrStyle :: PrintUnqualified -> PprStyle

Style for printing error messages

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.

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.