GHC.Utils.Error

ghc-9.2.3: The GHC API

Safe Haskell | Safe-Inferred
Language | Haskell2010

GHC.Utils.Error

Contents

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

Synopsis

- data Validity
  - = IsValid
  - | NotValid SDoc
- andValid :: Validity -> Validity -> Validity
- allValid :: [Validity] -> Validity
- isValid :: Validity -> Bool
- getInvalids :: [Validity] -> [SDoc]
- orValid :: Validity -> Validity -> Validity
- data Severity
  - = SevOutput
  - | SevFatal
  - | SevInteractive
  - | SevDump
  - | SevInfo
  - | SevWarning
  - | SevError
- type WarnMsg = MsgEnvelope DecoratedSDoc
- data MsgEnvelope e = MsgEnvelope {
  - errMsgSpan :: SrcSpan
  - errMsgContext :: PrintUnqualified
  - errMsgDiagnostic :: e
  - errMsgSeverity :: Severity
  - errMsgReason :: WarnReason
  }
- data SDoc
- data DecoratedSDoc
- data Messages e
- type ErrorMessages = Bag (MsgEnvelope DecoratedSDoc)
- type WarningMessages = Bag (MsgEnvelope DecoratedSDoc)
- unionMessages :: Messages e -> Messages e -> Messages e
- errorsFound :: Messages e -> Bool
- isEmptyMessages :: Messages e -> Bool
- pprMessageBag :: Bag SDoc -> SDoc
- pprMsgEnvelopeBagWithLoc :: Bag (MsgEnvelope DecoratedSDoc) -> [SDoc]
- pprLocMsgEnvelope :: RenderableDiagnostic e => MsgEnvelope e -> SDoc
- formatBulleted :: SDocContext -> DecoratedSDoc -> SDoc
- emptyMessages :: Messages e
- mkDecorated :: [SDoc] -> DecoratedSDoc
- mkLocMessage :: Severity -> SrcSpan -> SDoc -> SDoc
- mkLocMessageAnn :: Maybe String -> Severity -> SrcSpan -> SDoc -> SDoc
- makeIntoWarning :: WarnReason -> MsgEnvelope e -> MsgEnvelope e
- mkMsgEnvelope :: SrcSpan -> PrintUnqualified -> SDoc -> MsgEnvelope DecoratedSDoc
- mkPlainMsgEnvelope :: SrcSpan -> SDoc -> MsgEnvelope DecoratedSDoc
- mkErr :: SrcSpan -> PrintUnqualified -> e -> MsgEnvelope e
- mkLongMsgEnvelope :: SrcSpan -> PrintUnqualified -> SDoc -> SDoc -> MsgEnvelope DecoratedSDoc
- mkWarnMsg :: SrcSpan -> PrintUnqualified -> SDoc -> MsgEnvelope DecoratedSDoc
- mkPlainWarnMsg :: SrcSpan -> SDoc -> MsgEnvelope DecoratedSDoc
- mkLongWarnMsg :: SrcSpan -> PrintUnqualified -> SDoc -> SDoc -> MsgEnvelope DecoratedSDoc
- doIfSet :: Bool -> IO () -> IO ()
- doIfSet_dyn :: DynFlags -> GeneralFlag -> IO () -> IO ()
- getCaretDiagnostic :: Severity -> SrcSpan -> IO SDoc
- putMsg :: Logger -> DynFlags -> SDoc -> IO ()
- printInfoForUser :: Logger -> DynFlags -> PrintUnqualified -> SDoc -> IO ()
- printOutputForUser :: Logger -> DynFlags -> PrintUnqualified -> SDoc -> IO ()
- logInfo :: Logger -> DynFlags -> SDoc -> IO ()
- logOutput :: Logger -> DynFlags -> SDoc -> IO ()
- errorMsg :: Logger -> DynFlags -> SDoc -> IO ()
- warningMsg :: Logger -> DynFlags -> SDoc -> IO ()
- fatalErrorMsg :: Logger -> DynFlags -> SDoc -> IO ()
- fatalErrorMsg'' :: FatalMessager -> String -> IO ()
- compilationProgressMsg :: Logger -> DynFlags -> SDoc -> IO ()
- showPass :: Logger -> DynFlags -> String -> IO ()
- withTiming :: MonadIO m => Logger -> DynFlags -> SDoc -> (a -> ()) -> m a -> m a
- withTimingSilent :: MonadIO m => Logger -> DynFlags -> SDoc -> (a -> ()) -> m a -> m a
- debugTraceMsg :: Logger -> DynFlags -> Int -> SDoc -> IO ()
- ghcExit :: Logger -> DynFlags -> Int -> IO ()
- prettyPrintGhcErrors :: ExceptionMonad m => DynFlags -> m a -> m a
- traceCmd :: Logger -> DynFlags -> String -> String -> IO a -> IO a
- sortMsgBag :: Maybe DynFlags -> Bag (MsgEnvelope e) -> [MsgEnvelope e]

# Basic types

data Validity Source #

Constructors

IsValid | Everything is fine
NotValid SDoc | 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] -> [SDoc] Source #

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

data Severity Source #

Constructors

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

#### Instances

Instances details

Show Severity Source # |
Instance details Defined in GHC.Types.Error Methods showsPrec :: Int -> Severity -> ShowS Source # show :: Severity -> String Source # showList :: [Severity] -> ShowS Source #
ToJson Severity Source # |
Instance details Defined in GHC.Types.Error Methods json :: Severity -> JsonDoc Source #
Eq Severity Source # |
Instance details Defined in GHC.Types.Error Methods (==) :: Severity -> Severity -> Bool # (/=) :: Severity -> Severity -> Bool #

# Messages

type WarnMsg = MsgEnvelope DecoratedSDoc Source #

data MsgEnvelope e Source #

An envelope for GHC's facts about a running program, parameterised over the domain-specific (i.e. parsing, typecheck-renaming, etc) diagnostics.

To say things differently, GHC emits diagnostics about the running program, each of which is wrapped into a `MsgEnvelope` that carries specific information like where the error happened, its severity, etc. Finally, multiple `MsgEnvelope`s are aggregated into `Messages` that are returned to the user.

Constructors

MsgEnvelope |
Fields errMsgSpan :: SrcSpan The SrcSpan is used for sorting errors into line-number order errMsgContext :: PrintUnqualified errMsgDiagnostic :: e errMsgSeverity :: Severity errMsgReason :: WarnReason

#### Instances

Instances details

Functor MsgEnvelope Source # |
Instance details Defined in GHC.Types.Error Methods fmap :: (a -> b) -> MsgEnvelope a -> MsgEnvelope b Source # (<$) :: a -> MsgEnvelope b -> MsgEnvelope a Source #
Show (MsgEnvelope DecoratedSDoc) Source # |
Instance details Defined in GHC.Types.Error Methods showsPrec :: Int -> MsgEnvelope DecoratedSDoc -> ShowS Source # show :: MsgEnvelope DecoratedSDoc -> String Source # showList :: [MsgEnvelope DecoratedSDoc] -> ShowS Source #

data SDoc Source #

Represents a pretty-printable document.

To display an `SDoc`, use `printSDoc`, `printSDocLn`, `bufLeftRenderSDoc`, or `renderWithContext`. Avoid calling `runSDoc` directly as it breaks the abstraction layer.

#### Instances

Instances details

IsString SDoc Source # |
Instance details Defined in GHC.Utils.Outputable Methods fromString :: String -> SDoc Source #
Show SDoc Source # |
Instance details Defined in GHC.CmmToAsm.AArch64.Regs Methods showsPrec :: Int -> SDoc -> ShowS Source # show :: SDoc -> String Source # showList :: [SDoc] -> ShowS Source #
Outputable SDoc Source # |
Instance details Defined in GHC.Utils.Outputable Methods ppr :: SDoc -> SDoc Source #
Eq SDoc Source # |
Instance details Defined in GHC.CmmToAsm.AArch64.Regs Methods (==) :: SDoc -> SDoc -> Bool # (/=) :: SDoc -> SDoc -> Bool #
OutputableP env SDoc Source # |
Instance details Defined in GHC.Utils.Outputable Methods pdoc :: env -> SDoc -> SDoc Source #

data DecoratedSDoc Source #

A `DecoratedSDoc` is isomorphic to a '[SDoc]' but it carries the invariant that the input '[SDoc]' needs to be rendered decorated into its final form, where the typical case would be adding bullets between each elements of the list. The type of decoration depends on the formatting function used, but in practice GHC uses the `formatBulleted`.

#### Instances

Instances details

RenderableDiagnostic DecoratedSDoc Source # |
Instance details Defined in GHC.Types.Error Methods renderDiagnostic :: DecoratedSDoc -> DecoratedSDoc Source #
Show (MsgEnvelope DecoratedSDoc) Source # |
Instance details Defined in GHC.Types.Error Methods showsPrec :: Int -> MsgEnvelope DecoratedSDoc -> ShowS Source # show :: MsgEnvelope DecoratedSDoc -> String Source # showList :: [MsgEnvelope DecoratedSDoc] -> ShowS Source #

data Messages e Source #

A collection of messages emitted by GHC during error reporting. A diagnostic message is typically a warning or an error. See Note [Messages].

#### Instances

Instances details

Functor Messages Source # |
Instance details Defined in GHC.Types.Error Methods fmap :: (a -> b) -> Messages a -> Messages b Source # (<$) :: a -> Messages b -> Messages a Source #

type ErrorMessages = Bag (MsgEnvelope DecoratedSDoc) Source #

type WarningMessages = Bag (MsgEnvelope DecoratedSDoc) Source #

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

Joins two collections of messages together.

errorsFound :: Messages e -> Bool Source #

isEmptyMessages :: Messages e -> Bool Source #

## Formatting

pprMessageBag :: Bag SDoc -> SDoc Source #

pprMsgEnvelopeBagWithLoc :: Bag (MsgEnvelope DecoratedSDoc) -> [SDoc] Source #

pprLocMsgEnvelope :: RenderableDiagnostic e => MsgEnvelope e -> SDoc Source #

formatBulleted :: SDocContext -> DecoratedSDoc -> SDoc Source #

Formats the input list of structured document, where each element of the list gets a bullet.

## Construction

emptyMessages :: Messages e Source #

mkDecorated :: [SDoc] -> DecoratedSDoc Source #

Creates a new `DecoratedSDoc` out of a list of `SDoc`.

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

Make an unannotated error message with location info.

mkLocMessageAnn Source #

Arguments

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

Make a possibly annotated error message with location info.

makeIntoWarning :: WarnReason -> MsgEnvelope e -> MsgEnvelope e Source #

mkMsgEnvelope :: SrcSpan -> PrintUnqualified -> SDoc -> MsgEnvelope DecoratedSDoc Source #

A short (one-line) error message

mkPlainMsgEnvelope :: SrcSpan -> SDoc -> MsgEnvelope DecoratedSDoc Source #

Variant that doesn't care about qualified/unqualified names

mkErr :: SrcSpan -> PrintUnqualified -> e -> MsgEnvelope e Source #

mkLongMsgEnvelope :: SrcSpan -> PrintUnqualified -> SDoc -> SDoc -> MsgEnvelope DecoratedSDoc Source #

A long (multi-line) error message

mkWarnMsg :: SrcSpan -> PrintUnqualified -> SDoc -> MsgEnvelope DecoratedSDoc Source #

A short (one-line) error message

mkPlainWarnMsg :: SrcSpan -> SDoc -> MsgEnvelope DecoratedSDoc Source #

Variant that doesn't care about qualified/unqualified names

mkLongWarnMsg :: SrcSpan -> PrintUnqualified -> SDoc -> SDoc -> MsgEnvelope DecoratedSDoc Source #

A long (multi-line) error message

# Utilities

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

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

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

# Issuing messages during compilation

putMsg :: Logger -> DynFlags -> SDoc -> IO () Source #

printInfoForUser :: Logger -> DynFlags -> PrintUnqualified -> SDoc -> IO () Source #

printOutputForUser :: Logger -> DynFlags -> PrintUnqualified -> SDoc -> IO () Source #

logInfo :: Logger -> DynFlags -> SDoc -> IO () Source #

logOutput :: Logger -> DynFlags -> SDoc -> IO () Source #

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

errorMsg :: Logger -> DynFlags -> SDoc -> IO () Source #

warningMsg :: Logger -> DynFlags -> SDoc -> IO () Source #

fatalErrorMsg :: Logger -> DynFlags -> SDoc -> IO () Source #

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

compilationProgressMsg :: Logger -> DynFlags -> SDoc -> IO () Source #

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

withTiming Source #

Arguments

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

debugTraceMsg :: Logger -> DynFlags -> Int -> SDoc -> IO () Source #

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

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

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

sortMsgBag :: Maybe DynFlags -> Bag (MsgEnvelope e) -> [MsgEnvelope e] Source #