ghc-8.2.2: The GHC API

Safe Haskell | None
Language | Haskell2010

ErrUtils

Contents

- Basic types
- Messages
  - Formatting
  - Construction
- Utilities
- Dump files
- Issuing messages during compilation

Synopsis

- data Validity
  - = IsValid
  - | NotValid MsgDoc
- andValid :: Validity -> Validity -> Validity
- allValid :: [Validity] -> Validity
- isValid :: Validity -> Bool
- getInvalids :: [Validity] -> [MsgDoc]
- data Severity
  - = SevOutput
  - | SevFatal
  - | SevInteractive
  - | SevDump
  - | SevInfo
  - | SevWarning
  - | SevError
- data ErrMsg
- errMsgDoc :: ErrMsg -> ErrDoc
- data ErrDoc
- errDoc :: [MsgDoc] -> [MsgDoc] -> [MsgDoc] -> ErrDoc
- errDocImportant :: ErrDoc -> [MsgDoc]
- errDocContext :: ErrDoc -> [MsgDoc]
- errDocSupplementary :: ErrDoc -> [MsgDoc]
- type WarnMsg = ErrMsg
- type MsgDoc = SDoc
- type Messages = (WarningMessages, ErrorMessages)
- type ErrorMessages = Bag ErrMsg
- type WarningMessages = Bag WarnMsg
- unionMessages :: Messages -> Messages -> Messages
- errMsgSpan :: ErrMsg -> SrcSpan
- errMsgContext :: ErrMsg -> PrintUnqualified
- errorsFound :: DynFlags -> Messages -> Bool
- isEmptyMessages :: Messages -> Bool
- isWarnMsgFatal :: DynFlags -> WarnMsg -> Bool
- pprMessageBag :: Bag MsgDoc -> SDoc
- pprErrMsgBagWithLoc :: Bag ErrMsg -> [SDoc]
- pprLocErrMsg :: ErrMsg -> SDoc
- printBagOfErrors :: DynFlags -> Bag ErrMsg -> IO ()
- formatErrDoc :: DynFlags -> ErrDoc -> SDoc
- emptyMessages :: Messages
- mkLocMessage :: Severity -> SrcSpan -> MsgDoc -> MsgDoc
- mkLocMessageAnn :: Maybe String -> Severity -> SrcSpan -> MsgDoc -> MsgDoc
- makeIntoWarning :: WarnReason -> ErrMsg -> ErrMsg
- mkErrMsg :: DynFlags -> SrcSpan -> PrintUnqualified -> MsgDoc -> ErrMsg
- mkPlainErrMsg :: DynFlags -> SrcSpan -> MsgDoc -> ErrMsg
- mkErrDoc :: DynFlags -> SrcSpan -> PrintUnqualified -> ErrDoc -> ErrMsg
- mkLongErrMsg :: DynFlags -> SrcSpan -> PrintUnqualified -> MsgDoc -> MsgDoc -> ErrMsg
- mkWarnMsg :: DynFlags -> SrcSpan -> PrintUnqualified -> MsgDoc -> ErrMsg
- mkPlainWarnMsg :: DynFlags -> SrcSpan -> MsgDoc -> ErrMsg
- warnIsErrorMsg :: DynFlags -> ErrMsg
- mkLongWarnMsg :: DynFlags -> SrcSpan -> PrintUnqualified -> MsgDoc -> MsgDoc -> ErrMsg
- doIfSet :: Bool -> IO () -> IO ()
- doIfSet_dyn :: DynFlags -> GeneralFlag -> IO () -> IO ()
- getCaretDiagnostic :: Severity -> SrcSpan -> IO MsgDoc
- dumpIfSet :: DynFlags -> Bool -> String -> SDoc -> IO ()
- dumpIfSet_dyn :: DynFlags -> DumpFlag -> String -> SDoc -> IO ()
- dumpIfSet_dyn_printer :: PrintUnqualified -> DynFlags -> DumpFlag -> SDoc -> IO ()
- mkDumpDoc :: String -> SDoc -> SDoc
- dumpSDoc :: DynFlags -> PrintUnqualified -> DumpFlag -> String -> SDoc -> IO ()
- putMsg :: DynFlags -> MsgDoc -> IO ()
- printInfoForUser :: DynFlags -> PrintUnqualified -> MsgDoc -> IO ()
- printOutputForUser :: DynFlags -> PrintUnqualified -> MsgDoc -> IO ()
- logInfo :: DynFlags -> PprStyle -> MsgDoc -> IO ()
- logOutput :: DynFlags -> PprStyle -> MsgDoc -> IO ()
- errorMsg :: DynFlags -> MsgDoc -> IO ()
- warningMsg :: DynFlags -> MsgDoc -> IO ()
- fatalErrorMsg :: DynFlags -> MsgDoc -> IO ()
- fatalErrorMsg'' :: FatalMessager -> String -> IO ()
- compilationProgressMsg :: DynFlags -> String -> IO ()
- showPass :: DynFlags -> String -> IO ()
- withTiming :: MonadIO m => m DynFlags -> SDoc -> (a -> ()) -> m a -> m a
- debugTraceMsg :: DynFlags -> Int -> MsgDoc -> IO ()
- ghcExit :: DynFlags -> Int -> IO ()
- prettyPrintGhcErrors :: ExceptionMonad m => DynFlags -> m a -> m a

# Basic types

data Validity #

Constructors

IsValid | Everything is fine
NotValid MsgDoc | A problem, and some indication of why

andValid :: Validity -> Validity -> Validity #

allValid :: [Validity] -> Validity #

If they aren't all valid, return the first

isValid :: Validity -> Bool #

getInvalids :: [Validity] -> [MsgDoc] #

data Severity #

Constructors

SevOutput |
SevFatal |
SevInteractive |
SevDump | Log messagse intended for compiler developers No filelinecolumn stuff
SevInfo | Log messages intended for end users. No filelinecolumn stuff.
SevWarning |
SevError | SevWarning and SevError are used for warnings and errors o The message has a filelinecolumn heading, plus "warning:" or "error:", added by mkLocMessags o Output is intended for end users

Instances

Show Severity # |
Methods showsPrec :: Int -> Severity -> ShowS Source # show :: Severity -> String Source # showList :: [Severity] -> ShowS Source #
ToJson Severity # |
Methods json :: Severity -> JsonDoc #

# Messages

data ErrMsg #

Instances

Show ErrMsg # |
Methods showsPrec :: Int -> ErrMsg -> ShowS Source # show :: ErrMsg -> String Source # showList :: [ErrMsg] -> ShowS Source #

errMsgDoc :: ErrMsg -> ErrDoc #

data ErrDoc #

Categorise error msgs by their importance. This is so each section can be rendered visually distinct. See Note [Error report] for where these come from.

errDoc :: [MsgDoc] -> [MsgDoc] -> [MsgDoc] -> ErrDoc #

errDocImportant :: ErrDoc -> [MsgDoc] #

Primary error msg.

errDocContext :: ErrDoc -> [MsgDoc] #

Context e.g. "In the second argument of ...".

errDocSupplementary :: ErrDoc -> [MsgDoc] #

Supplementary information, e.g. "Relevant bindings include ...".

type WarnMsg = ErrMsg #

type MsgDoc = SDoc #

type Messages = (WarningMessages, ErrorMessages) #

type ErrorMessages = Bag ErrMsg #

type WarningMessages = Bag WarnMsg #

unionMessages :: Messages -> Messages -> Messages #

errMsgSpan :: ErrMsg -> SrcSpan #

errMsgContext :: ErrMsg -> PrintUnqualified #

errorsFound :: DynFlags -> Messages -> Bool #

isEmptyMessages :: Messages -> Bool #

isWarnMsgFatal :: DynFlags -> WarnMsg -> Bool #

Checks if given `WarnMsg` is a fatal warning.

## Formatting

pprMessageBag :: Bag MsgDoc -> SDoc #

pprErrMsgBagWithLoc :: Bag ErrMsg -> [SDoc] #

pprLocErrMsg :: ErrMsg -> SDoc #

printBagOfErrors :: DynFlags -> Bag ErrMsg -> IO () #

formatErrDoc :: DynFlags -> ErrDoc -> SDoc #

## Construction

emptyMessages :: Messages #

mkLocMessage :: Severity -> SrcSpan -> MsgDoc -> MsgDoc #

Make an unannotated error message with location info.

mkLocMessageAnn #

Arguments

:: Maybe String | optional annotation
-> Severity | severity
-> SrcSpan | location
-> MsgDoc | message
-> MsgDoc |

Make a possibly annotated error message with location info.

makeIntoWarning :: WarnReason -> ErrMsg -> ErrMsg #

mkErrMsg :: DynFlags -> SrcSpan -> PrintUnqualified -> MsgDoc -> ErrMsg #

A short (one-line) error message

mkPlainErrMsg :: DynFlags -> SrcSpan -> MsgDoc -> ErrMsg #

Variant that doesn't care about qualified/unqualified names

mkErrDoc :: DynFlags -> SrcSpan -> PrintUnqualified -> ErrDoc -> ErrMsg #

mkLongErrMsg :: DynFlags -> SrcSpan -> PrintUnqualified -> MsgDoc -> MsgDoc -> ErrMsg #

A long (multi-line) error message

mkWarnMsg :: DynFlags -> SrcSpan -> PrintUnqualified -> MsgDoc -> ErrMsg #

A short (one-line) error message

mkPlainWarnMsg :: DynFlags -> SrcSpan -> MsgDoc -> ErrMsg #

Variant that doesn't care about qualified/unqualified names

warnIsErrorMsg :: DynFlags -> ErrMsg #

mkLongWarnMsg :: DynFlags -> SrcSpan -> PrintUnqualified -> MsgDoc -> MsgDoc -> ErrMsg #

A long (multi-line) error message

# Utilities

doIfSet :: Bool -> IO () -> IO () #

doIfSet_dyn :: DynFlags -> GeneralFlag -> IO () -> IO () #

getCaretDiagnostic :: Severity -> SrcSpan -> IO MsgDoc #

# Dump files

dumpIfSet :: DynFlags -> Bool -> String -> SDoc -> IO () #

dumpIfSet_dyn :: DynFlags -> DumpFlag -> String -> SDoc -> IO () #

a wrapper around `dumpSDoc`. First check whether the dump flag is set Do nothing if it is unset

dumpIfSet_dyn_printer :: PrintUnqualified -> DynFlags -> DumpFlag -> SDoc -> IO () #

a wrapper around `dumpSDoc`. First check whether the dump flag is set Do nothing if it is unset

Unlike `dumpIfSet_dyn`, has a printer argument but no header argument

mkDumpDoc :: String -> SDoc -> SDoc #

dumpSDoc :: DynFlags -> PrintUnqualified -> DumpFlag -> String -> SDoc -> IO () #

Write out a dump. If --dump-to-file is set then this goes to a file. otherwise emit to stdout.

When `hdr` is empty, we print in a more compact format (no separators and blank lines)

The `DumpFlag` is used only to choose the filename to use if `--dump-to-file` is used; it is not used to decide whether to dump the output

# Issuing messages during compilation

putMsg :: DynFlags -> MsgDoc -> IO () #

printInfoForUser :: DynFlags -> PrintUnqualified -> MsgDoc -> IO () #

printOutputForUser :: DynFlags -> PrintUnqualified -> MsgDoc -> IO () #

logInfo :: DynFlags -> PprStyle -> MsgDoc -> IO () #

logOutput :: DynFlags -> PprStyle -> MsgDoc -> IO () #

Like `logInfo` but with `SevOutput` rather then `SevInfo`

errorMsg :: DynFlags -> MsgDoc -> IO () #

warningMsg :: DynFlags -> MsgDoc -> IO () #

fatalErrorMsg :: DynFlags -> MsgDoc -> IO () #

fatalErrorMsg'' :: FatalMessager -> String -> IO () #

compilationProgressMsg :: DynFlags -> String -> IO () #

showPass :: DynFlags -> String -> IO () #

withTiming #

Arguments

:: MonadIO m |
=> m DynFlags | A means of getting a `DynFlags` (often `getDynFlags` will work here)
-> SDoc | The name of the phase
-> (a -> ()) | A function to force the result (often either `const ()` or `rnf`)
-> m a | The body of the phase to be timed
-> m a |

Time a compilation phase.

When timings are enabled (e.g. with the `-v2` flag), the allocations and CPU time used by the phase will be reported to stderr. Consider a typical usage: `withTiming getDynFlags (text "simplify") force pass`. When timings are enabled the following costs are included in the produced accounting,

- The cost of executing `pass` to a result `r` in WHNF
- The cost of evaluating `force r` to WHNF (e.g. `()`)

The choice of the `force` function depends upon the amount of forcing desired; the goal here is to ensure that the cost of evaluating the result is, to the greatest extent possible, included in the accounting provided by `withTiming`. Often the pass already sufficiently forces its result during construction; in this case `const ()` is a reasonable choice. In other cases, it is necessary to evaluate the result to normal form, in which case something like `Control.DeepSeq.rnf` is appropriate.

To avoid adversely affecting compiler performance when timings are not requested, the result is only forced when timings are enabled.

debugTraceMsg :: DynFlags -> Int -> MsgDoc -> IO () #

ghcExit :: DynFlags -> Int -> IO () #

prettyPrintGhcErrors :: ExceptionMonad m => DynFlags -> m a -> m a #