ghc-7.10.3: The GHC API

Safe HaskellNone
LanguageHaskell2010

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 Source

Class designating that some type has an SDoc representation

Minimal complete definition

Nothing

Methods

ppr :: a -> SDoc Source

pprPrec :: Rational -> a -> SDoc Source

Instances

Outputable Bool 
Outputable Char 
Outputable Int 
Outputable Int32 
Outputable Int64 
Outputable Word 
Outputable Word16 
Outputable Word32 
Outputable () 
Outputable Fingerprint 
Outputable PrimOp 
Outputable PackageKey 
Outputable ModuleName 
Outputable Module 
Outputable OccName 
Outputable FastString 
Outputable MetaDetails 
Outputable IdDetails 
Outputable Phase 
Outputable Name 
Outputable SrcSpan 
Outputable RealSrcSpan 
Outputable SrcLoc 
Outputable RealSrcLoc 
Outputable FractionalLit 
Outputable InlineSpec 
Outputable InlinePragma 
Outputable RuleMatchInfo 
Outputable Activation 
Outputable CompilerPhase 
Outputable SuccessFlag 
Outputable DefMethSpec 
Outputable OccInfo 
Outputable OverlapMode 
Outputable OverlapFlag 
Outputable Origin 
Outputable RecFlag 
Outputable TopLevelFlag 
Outputable FixityDirection 
Outputable Fixity 
Outputable WarningTxt 
Outputable FunctionOrData 
Outputable SwapFlag 
Outputable OneShotInfo 
Outputable Unique 
Outputable RegClass 
Outputable Reg

Print a reg in a generic manner If you want the architecture specific names, then use the pprReg function from the appropriate Ppr module.

Outputable RealReg 
Outputable VirtualReg 
Outputable ModLocation 
Outputable PackageName 
Outputable SourcePackageId 
Outputable InstalledPackageId 
Outputable Serialized 
Outputable CType 
Outputable Header 
Outputable CCallConv 
Outputable CCallSpec 
Outputable CExportSpec 
Outputable Safety 
Outputable ForeignCall 
Outputable HsDocString 
Outputable GhcMode 
Outputable SafeHaskellMode 
Outputable LlvmCastOp 
Outputable LlvmCmpOp 
Outputable LlvmMachOp 
Outputable LlvmLinkageType 
Outputable LlvmCallConvention 
Outputable LlvmFuncAttr 
Outputable LlvmParamAttr 
Outputable LlvmFunctionDecl 
Outputable LlvmStatic 
Outputable LlvmLit 
Outputable LlvmVar 
Outputable LlvmType 
Outputable MetaExpr 
Outputable ArgDescr 
Outputable ClosureTypeInfo 
Outputable SMRep 
Outputable StgHalfWord 
Outputable StgWord 
Outputable Width 
Outputable CmmType 
Outputable TyThing 
Outputable Type 
Outputable TyCon 
Outputable AvailInfo 
Outputable DataCon 
Outputable PatSyn 
Outputable ConLike 
Outputable ImportSpec 
Outputable Parent 
Outputable GlobalRdrElt 
Outputable LocalRdrEnv 
Outputable RdrName 
Outputable AnnotationComment 
Outputable AnnKeywordId 
Outputable Token 
Outputable ModuleOrigin 
Outputable Annotation 
Outputable Var 
Outputable CostCentreStack 
Outputable CostCentre 
Outputable DefMeth 
Outputable Class 
Outputable InScopeSet 
Outputable CoAxiomRule 
Outputable Role 
Outputable PrimElemRep 
Outputable PrimRep 
Outputable TyConParent 
Outputable EqRel 
Outputable CvSubst 
Outputable LeftOrRight 
Outputable Coercion 
Outputable OverLitVal 
Outputable HsLit 
Outputable StrictnessMark 
Outputable HsBang 
Outputable StrictSig 
Outputable DmdType 
Outputable CPRResult 
Outputable DmdResult 
Outputable TypeShape 
Outputable CleanDemand 
Outputable Count 
Outputable UseDmd 
Outputable StrDmd 
Outputable Literal 
Outputable AltCon 
Outputable TickBoxOp 
Outputable CafInfo 
Outputable UnVarGraph 
Outputable UnVarSet 
Outputable HsTyLit 
Outputable HsIPName 
Outputable PrimCall 
Outputable ForeignLabelSource 
Outputable CLabel 
Outputable CmmTickScope 
Outputable UnwindExpr 
Outputable DebugBlock 
Outputable ParamLocation 
Outputable LiveInfo 
Outputable Loc 
Outputable SpillStats 
Outputable TopSRT 
Outputable Status 
Outputable UpdateFlag 
Outputable AltType 
Outputable TcLevel 
Outputable CgLoc 
Outputable CgIdInfo 
Outputable ArgRep 
Outputable BreakInfo 
Outputable BCInstr 
Outputable UnlinkedBCO 
Outputable CompiledByteCode 
Outputable CoreStats 
Outputable ClsInst 
Outputable FDEq 
Outputable FamInstMatch 
Outputable FamInst 
Outputable IdSubstEnv 
Outputable Subst 
Outputable CallCtxt 
Outputable ArgSummary 
Outputable EvCallStack 
Outputable EvLit 
Outputable EvTypeable 
Outputable EvTerm 
Outputable EvBind 
Outputable EvBindsVar 
Outputable TcEvBinds 
Outputable HsWrapper 
Outputable TcCoercion 
Outputable TcSpecPrag 
Outputable DocDecl 
Outputable ForeignExport 
Outputable ForeignImport 
Outputable NewOrData 
Outputable PendingRnSplice 
Outputable IfaceCoercion 
Outputable IfaceTyCon 
Outputable IfaceTcArgs 
Outputable IfaceTyLit 
Outputable IfaceType 
Outputable IfaceBndr 
Outputable IfaceConAlt 
Outputable IfaceExpr 
Outputable IfaceIdDetails 
Outputable IfaceUnfolding 
Outputable IfaceInfoItem 
Outputable IfaceIdInfo 
Outputable IfaceAnnotation 
Outputable IfaceRule 
Outputable IfaceFamInst 
Outputable IfaceClsInst 
Outputable IfaceAT 
Outputable IfaceClassOp 
Outputable IfaceTyConParent 
Outputable IfaceDecl 
Outputable Unlinked 
Outputable Linkable 
Outputable IfaceTrustInfo 
Outputable IfaceVectInfo 
Outputable VectInfo 
Outputable ModSummary 
Outputable FixItem 
Outputable InteractiveImport 
Outputable TargetId 
Outputable Target 
Outputable PhasePlus 
Outputable SkolemInfo 
Outputable SubGoalDepth 
Outputable CtFlavour 
Outputable CtEvidence 
Outputable Implication 
Outputable WantedConstraints 
Outputable Ct 
Outputable WhereFrom 
Outputable PromotionErr 
Outputable TcTyThing 
Outputable ThStage 
Outputable FloatBind 
Outputable ClosureType 
Outputable Term 
Outputable Tick 
Outputable FloatOutSwitches 
Outputable SimplifierMode 
Outputable CoreToDo 
Outputable FloatSpec 
Outputable Level 
Outputable Floats 
Outputable SimplSR 
Outputable ArgSpec 
Outputable DupFlag 
Outputable SimplCont 
Outputable EquationInfo 
Outputable InertSet 
Outputable InertCans 
Outputable WorkList 
Outputable MetaTyCons 
Outputable TcPatSynInfo 
Outputable TcSigInfo 
Outputable CompRepr 
Outputable ProdRepr 
Outputable ConRepr 
Outputable SumRepr 
Outputable CoreModule 
Outputable a => Outputable [a] 
Outputable a => Outputable (Maybe a) 
Outputable elt => Outputable (IntMap elt) 
Outputable a => Outputable (Set a) 
Outputable a => Outputable (Pair a) 
Outputable a => Outputable (OrdList a) 
Outputable a => Outputable (Bag a) 
Outputable a => Outputable (SCC a) 
Outputable node => Outputable (Graph node) 
Outputable a => Outputable (UniqFM a) 
Outputable a => Outputable (BooleanFormula a) 
Outputable a => Outputable (OccEnv a) 
(HasOccName name, OutputableBndr name) => Outputable (IE name) 
(OutputableBndr name, HasOccName name) => Outputable (ImportDecl name) 
Outputable name => Outputable (AnnTarget name) 
Outputable (CoAxiom br) 
OutputableBndr name => Outputable (Pat name) 
OutputableBndr id => Outputable (HsSplice id) 
OutputableBndr id => Outputable (HsCmd id) 
OutputableBndr id => Outputable (HsExpr id) 
OutputableBndr id => Outputable (HsOverLit id) 
Outputable b => Outputable (TaggedBndr b) 
OutputableBndr name => Outputable (HsType name) 
OutputableBndr name => Outputable (HsTyVarBndr name) 
OutputableBndr name => Outputable (LHsTyVarBndrs name) 
OutputableBndr id => Outputable (HsQuasiQuote id) 
Outputable instr => Outputable (ListGraph instr) 
Outputable instr => Outputable (GenBasicBlock instr) 
Outputable instr => Outputable (LiveInstr instr) 
Outputable instr => Outputable (InstrSR instr) 
Outputable bdee => Outputable (GenStgArg bdee) 
Outputable a => Outputable (NonVoid a) 
Outputable a => Outputable (ProtoBCO a) 
Outputable a => Outputable (TypeMap a) 
Outputable a => Outputable (CoreMap a) 
OutputableBndr name => Outputable (FixitySig name) 
OutputableBndr name => Outputable (Sig name) 
OutputableBndr id => Outputable (IPBind id) 
OutputableBndr id => Outputable (HsIPBinds id) 
OutputableBndr id => Outputable (ABExport id) 
OutputableBndr name => Outputable (RoleAnnotDecl name) 
OutputableBndr name => Outputable (AnnDecl name) 
OutputableBndr name => Outputable (WarnDecl name) 
OutputableBndr name => Outputable (WarnDecls name) 
OutputableBndr name => Outputable (VectDecl name) 
OutputableBndr name => Outputable (RuleBndr name) 
OutputableBndr name => Outputable (RuleDecl name) 
OutputableBndr name => Outputable (RuleDecls name) 
OutputableBndr name => Outputable (ForeignDecl name) 
OutputableBndr name => Outputable (DefaultDecl name) 
OutputableBndr name => Outputable (DerivDecl name) 
OutputableBndr name => Outputable (InstDecl name) 
OutputableBndr name => Outputable (ClsInstDecl name) 
OutputableBndr name => Outputable (DataFamInstDecl name) 
OutputableBndr name => Outputable (TyFamInstDecl name) 
Outputable ty => Outputable (ResType ty) 
OutputableBndr name => Outputable (ConDecl name) 
OutputableBndr name => Outputable (HsDataDefn name) 
Outputable (FamilyInfo name) 
OutputableBndr name => Outputable (FamilyDecl name) 
OutputableBndr name => Outputable (TyClGroup 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 (PendingSplice id) 
OutputableBndr id => Outputable (HsCmdTop id) 
(OutputableBndr name, HasOccName name) => Outputable (HsModule name) 
OutputableBndr a => Outputable (InstInfo a) 
Outputable a => Outputable (StopOrContinue 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 l, Outputable e) => Outputable (GenLocated l e) 
Outputable a => Outputable (BranchList a br) 
Outputable thing => Outputable (HsWithBndrs name thing) 
(Outputable statics, Outputable instr) => Outputable (RegAllocStats statics instr) 
(OutputableBndr bndr, Outputable bdee, Ord bdee) => Outputable (GenStgRhs bndr bdee) 
(OutputableBndr bndr, Outputable bdee, Ord bdee) => Outputable (GenStgExpr bndr bdee) 
(OutputableBndr bndr, Outputable bdee, Ord bdee) => Outputable (GenStgBinding bndr bdee) 
(OutputableBndr idL, OutputableBndr idR) => Outputable (PatSynBind idL idR) 
(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 (ParStmtBlock idL idR) 
(Outputable a, Outputable b, Outputable c) => Outputable (a, b, c) 
(OutputableBndr idL, OutputableBndr idR, Outputable body) => Outputable (StmtLR idL idR body) 
(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) 
(Outputable a, Outputable b, Outputable c, Outputable d, Outputable e, Outputable f) => Outputable (a, b, c, d, e, f) 
(Outputable a, Outputable b, Outputable c, Outputable d, Outputable e, Outputable f, Outputable g) => Outputable (a, b, c, d, e, f, g) 

class Outputable a => OutputableBndr a where Source

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

Minimal complete definition

pprPrefixOcc, pprInfixOcc

Pretty printing combinators

runSDoc :: SDoc -> SDocContext -> Doc Source

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

Returns the separated concatenation of the pretty printed things.

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

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

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

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

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

pprWithCommas Source

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 Source

Indent SDoc some specified amount

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

Join two SDoc together horizontally without a gap

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

Join two SDoc together horizontally with a gap between them

hcat :: [SDoc] -> SDoc Source

Concatenate SDoc horizontally

hsep :: [SDoc] -> SDoc Source

Concatenate SDoc horizontally with a space between each one

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

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

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

Join two SDoc together vertically

vcat :: [SDoc] -> SDoc Source

Concatenate SDoc vertically with dovetailing

sep :: [SDoc] -> SDoc Source

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

cat :: [SDoc] -> SDoc Source

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

fsep :: [SDoc] -> SDoc Source

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 Source

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

hang Source

Arguments

:: SDoc

The header

-> Int

Amount to indent the hung body

-> SDoc

The hung body, indented and placed below the header

-> SDoc 

punctuate Source

Arguments

:: SDoc

The punctuation

-> [SDoc]

The list that will have punctuation added between every adjacent pair of elements

-> [SDoc]

Punctuated list

speakNth :: Int -> SDoc Source

Converts an integer to a verbal index:

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

speakNTimes :: Int -> SDoc Source

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 Source

Converts an integer to a verbal multiplicity:

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

speakNOf :: Int -> SDoc -> SDoc Source

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 Source

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

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

isOrAre :: [a] -> SDoc Source

Determines the form of to be appropriate for the length of a list:

isOrAre [] = ptext (sLit "are")
isOrAre ["Hello"] = ptext (sLit "is")
isOrAre ["Hello", "World"] = ptext (sLit "are")

coloured :: PprColour -> SDoc -> SDoc Source

Apply the given colour/style for the argument.

Only takes effect if colours are enabled.

data PprColour Source

A colour/style for use with coloured.

Converting SDoc into strings and outputing it

pprHsChar :: Char -> SDoc Source

Special combinator for showing character literals.

pprHsString :: FastString -> SDoc Source

Special combinator for showing string literals.

pprHsBytes :: ByteString -> SDoc Source

Special combinator for showing string literals.

Controlling the style in which output is printed

data BindingSite Source

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

Constructors

CStyle 
AsmStyle 

data PrintUnqualified Source

When printing code that contains original names, we need to map the original names back to something the user understands. This is the purpose of the triple of functions that gets passed around when rendering SDoc.

type QueryQualifyName = Module -> OccName -> QualifyName Source

given an original name, this function tells you which module name it should be qualified with when printing for the user, if any. For example, given Control.Exception.catch, which is in scope as Exception.catch, this fuction will return Just Exception. Note that the return value is a ModuleName, not a Module, because in source code, names are qualified by ModuleNames.

type QueryQualifyModule = Module -> Bool Source

For a given module, we need to know whether to print it with a package name to disambiguate it.

type QueryQualifyPackage = PackageKey -> Bool Source

For a given package, we need to know whether to print it with the package key to disambiguate it.

alwaysQualifyNames :: QueryQualifyName Source

NB: This won't ever show package IDs

mkErrStyle :: DynFlags -> PrintUnqualified -> PprStyle Source

Style for printing error messages

data Depth Source

Constructors

AllTheWay 
PartWay Int 

Error handling and debugging utilities

pprPanic :: String -> SDoc -> a Source

Throw an exception saying "bug in GHC"

pprSorry :: String -> SDoc -> a Source

Throw an exception saying "this isn't finished yet"

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

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 Source

Specialization of pprPanic that can be safely used with FastInt

pprPgmError :: String -> SDoc -> a Source

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

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

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

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

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

trace :: String -> a -> a Source

The trace function outputs the trace message given as its first argument, before returning the second argument as its result.

For example, this returns the value of f x but first outputs the message.

trace ("calling f with x = " ++ show x) (f x)

The trace function should only be used for debugging, or for monitoring execution. The function is not referentially transparent: its type indicates that it is a pure function but it has the side effect of outputting the trace message.

pgmError :: String -> a Source

Panics and asserts.

panic :: String -> a Source

Panics and asserts.

sorry :: String -> a Source

Panics and asserts.

panicFastInt :: String -> FastInt Source

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 Source

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

pprDebugAndThen :: DynFlags -> (String -> a) -> SDoc -> SDoc -> a Source