ErrUtils

ghc-8.10.1: 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]
- orValid :: Validity -> Validity -> Validity
- data Severity
  - = SevOutput
  - | SevFatal
  - | SevInteractive
  - | SevDump
  - | SevInfo
  - | SevWarning
  - | SevError
- data ErrMsg
- errMsgDoc :: ErrMsg -> ErrDoc
- errMsgSeverity :: ErrMsg -> Severity
- errMsgReason :: ErrMsg -> WarnReason
- 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 -> Maybe (Maybe WarningFlag)
- warningsToMessages :: DynFlags -> WarningMessages -> Messages
- 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
- 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 ()
- dumpSDocForUser :: DynFlags -> PrintUnqualified -> DumpFlag -> String -> SDoc -> IO ()
- dumpSDocWithStyle :: PprStyle -> DynFlags -> 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 => DynFlags -> SDoc -> (a -> ()) -> m a -> m a
- withTimingSilent :: MonadIO m => DynFlags -> SDoc -> (a -> ()) -> m a -> m a
- withTimingD :: (MonadIO m, HasDynFlags m) => SDoc -> (a -> ()) -> m a -> m a
- withTimingSilentD :: (MonadIO m, HasDynFlags m) => SDoc -> (a -> ()) -> m a -> m a
- debugTraceMsg :: DynFlags -> Int -> MsgDoc -> IO ()
- ghcExit :: DynFlags -> Int -> IO ()
- prettyPrintGhcErrors :: ExceptionMonad m => DynFlags -> m a -> m a
- traceCmd :: DynFlags -> String -> String -> IO a -> IO a

# Basic types

data Validity Source #

Constructors

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

andValid :: Validity -> Validity -> Validity Source #

allValid :: [Validity] -> Validity Source #

If they aren't all valid, return the first

isValid :: Validity -> Bool Source #

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

orValid :: Validity -> Validity -> Validity Source #

data Severity Source #

Constructors

SevOutput |
SevFatal |
SevInteractive |
SevDump | Log message 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

Instances details

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

# Messages

data ErrMsg Source #

#### Instances

Instances details

Show ErrMsg # |
Instance details Defined in ErrUtils Methods showsPrec :: Int -> ErrMsg -> ShowS Source # show :: ErrMsg -> String Source # showList :: [ErrMsg] -> ShowS Source #

errMsgDoc :: ErrMsg -> ErrDoc Source #

errMsgSeverity :: ErrMsg -> Severity Source #

errMsgReason :: ErrMsg -> WarnReason Source #

data ErrDoc Source #

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

errDocImportant :: ErrDoc -> [MsgDoc] Source #

Primary error msg.

errDocContext :: ErrDoc -> [MsgDoc] Source #

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

errDocSupplementary :: ErrDoc -> [MsgDoc] Source #

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

type WarnMsg = ErrMsg Source #

type MsgDoc = SDoc Source #

type Messages = (WarningMessages, ErrorMessages) Source #

type ErrorMessages = Bag ErrMsg Source #

type WarningMessages = Bag WarnMsg Source #

unionMessages :: Messages -> Messages -> Messages Source #

errMsgSpan :: ErrMsg -> SrcSpan Source #

errMsgContext :: ErrMsg -> PrintUnqualified Source #

errorsFound :: DynFlags -> Messages -> Bool Source #

isEmptyMessages :: Messages -> Bool Source #

isWarnMsgFatal :: DynFlags -> WarnMsg -> Maybe (Maybe WarningFlag) Source #

Checks if given `WarnMsg` is a fatal warning.

warningsToMessages :: DynFlags -> WarningMessages -> Messages Source #

## Formatting

pprMessageBag :: Bag MsgDoc -> SDoc Source #

pprErrMsgBagWithLoc :: Bag ErrMsg -> [SDoc] Source #

pprLocErrMsg :: ErrMsg -> SDoc Source #

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

formatErrDoc :: DynFlags -> ErrDoc -> SDoc Source #

## Construction

emptyMessages :: Messages Source #

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

Make an unannotated error message with location info.

mkLocMessageAnn Source #

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

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

A short (one-line) error message

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

Variant that doesn't care about qualified/unqualified names

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

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

A long (multi-line) error message

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

A short (one-line) error message

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

Variant that doesn't care about qualified/unqualified names

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

A long (multi-line) error message

# Utilities

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

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

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

# Dump files

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

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

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

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

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

A wrapper around `dumpSDocWithStyle` which uses `PprDump` style.

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

A wrapper around `dumpSDocWithStyle` which uses `PprUser` style.

dumpSDocWithStyle :: PprStyle -> DynFlags -> DumpFlag -> String -> SDoc -> IO () Source #

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

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

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

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

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

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

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

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

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

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

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

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

withTiming Source #

Arguments

:: MonadIO m |
=> DynFlags | DynFlags
-> 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 PrintTimings 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.

See Note [withTiming] for more.

withTimingSilent Source #

Arguments

:: MonadIO m |
=> DynFlags | DynFlags
-> 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 |

Same as `withTiming`, but doesn't print timings in the console (when given `-vN`, `N >= 2` or `-ddump-timings`).

See Note [withTiming] for more.

withTimingD Source #

Arguments

:: (MonadIO m, HasDynFlags m) |
=> 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 |

Like withTiming but get DynFlags from the Monad.

withTimingSilentD Source #

Arguments

:: (MonadIO m, HasDynFlags m) |
=> 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 |

Same as `withTiming`, but doesn't print timings in the console (when given `-vN`, `N >= 2` or `-ddump-timings`) and gets the DynFlags from the given Monad.

See Note [withTiming] for more.

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

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

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

traceCmd :: DynFlags -> String -> String -> IO a -> IO a Source #