ghc-lib-parser-9.10.1.20250103: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Utils.Error

Contents

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

Synopsis

- data Validity' a
  - = IsValid
  - | NotValid a
- type Validity = Validity' SDoc
- andValid :: Validity' a -> Validity' a -> Validity' a
- allValid :: [Validity' a] -> Validity' a
- getInvalids :: [Validity' a] -> [a]
- data Severity
  - = SevIgnore
  - | SevWarning
  - | SevError
- class HasDefaultDiagnosticOpts (DiagnosticOpts a) => Diagnostic a where
  - type DiagnosticOpts a
  - diagnosticMessage :: DiagnosticOpts a -> a -> DecoratedSDoc
  - diagnosticReason :: a -> DiagnosticReason
  - diagnosticHints :: a -> [GhcHint]
  - diagnosticCode :: a -> Maybe DiagnosticCode
- data MsgEnvelope e = MsgEnvelope {
  - errMsgSpan :: SrcSpan
  - errMsgContext :: NamePprCtx
  - errMsgDiagnostic :: e
  - errMsgSeverity :: Severity
  - errMsgReason :: ResolvedDiagnosticReason
  }
- data MessageClass
  - = MCOutput
  - | MCFatal
  - | MCInteractive
  - | MCDump
  - | MCInfo
  - | MCDiagnostic Severity ResolvedDiagnosticReason (Maybe DiagnosticCode)
- data SDoc
- data DecoratedSDoc
- data Messages e
- mkMessages :: Bag (MsgEnvelope e) -> Messages e
- unionMessages :: Messages e -> Messages e -> Messages e
- errorsFound :: Diagnostic e => Messages e -> Bool
- isEmptyMessages :: Messages e -> Bool
- pprMessageBag :: Bag SDoc -> SDoc
- pprMsgEnvelopeBagWithLoc :: Diagnostic e => DiagnosticOpts e -> Bag (MsgEnvelope e) -> [SDoc]
- pprMsgEnvelopeBagWithLocDefault :: Diagnostic e => Bag (MsgEnvelope e) -> [SDoc]
- pprMessages :: Diagnostic e => DiagnosticOpts e -> Messages e -> SDoc
- pprLocMsgEnvelope :: Diagnostic e => DiagnosticOpts e -> MsgEnvelope e -> SDoc
- pprLocMsgEnvelopeDefault :: Diagnostic e => MsgEnvelope e -> SDoc
- formatBulleted :: DecoratedSDoc -> SDoc
- data DiagOpts = DiagOpts {
  - diag_warning_flags :: !(EnumSet WarningFlag)
  - diag_fatal_warning_flags :: !(EnumSet WarningFlag)
  - diag_custom_warning_categories :: !WarningCategorySet
  - diag_fatal_custom_warning_categories :: !WarningCategorySet
  - diag_warn_is_error :: !Bool
  - diag_reverse_errors :: !Bool
  - diag_max_errors :: !(Maybe Int)
  - diag_ppr_ctx :: !SDocContext
  }
- emptyDiagOpts :: DiagOpts
- diag_wopt :: WarningFlag -> DiagOpts -> Bool
- diag_fatal_wopt :: WarningFlag -> DiagOpts -> Bool
- emptyMessages :: Messages e
- mkDecorated :: [SDoc] -> DecoratedSDoc
- mkLocMessage :: MessageClass -> SrcSpan -> SDoc -> SDoc
- mkMsgEnvelope :: Diagnostic e => DiagOpts -> SrcSpan -> NamePprCtx -> e -> MsgEnvelope e
- mkPlainMsgEnvelope :: Diagnostic e => DiagOpts -> SrcSpan -> e -> MsgEnvelope e
- mkPlainErrorMsgEnvelope :: Diagnostic e => SrcSpan -> e -> MsgEnvelope e
- mkErrorMsgEnvelope :: Diagnostic e => SrcSpan -> NamePprCtx -> e -> MsgEnvelope e
- mkMCDiagnostic :: DiagOpts -> DiagnosticReason -> Maybe DiagnosticCode -> MessageClass
- errorDiagnostic :: MessageClass
- diagReasonSeverity :: DiagOpts -> DiagnosticReason -> Severity
- mkPlainError :: [GhcHint] -> SDoc -> DiagnosticMessage
- mkPlainDiagnostic :: DiagnosticReason -> [GhcHint] -> SDoc -> DiagnosticMessage
- mkDecoratedError :: [GhcHint] -> [SDoc] -> DiagnosticMessage
- mkDecoratedDiagnostic :: DiagnosticReason -> [GhcHint] -> [SDoc] -> DiagnosticMessage
- noHints :: [GhcHint]
- getCaretDiagnostic :: MessageClass -> SrcSpan -> IO SDoc
- putMsg :: Logger -> SDoc -> IO ()
- printInfoForUser :: Logger -> NamePprCtx -> SDoc -> IO ()
- printOutputForUser :: Logger -> NamePprCtx -> SDoc -> IO ()
- logInfo :: Logger -> SDoc -> IO ()
- logOutput :: Logger -> SDoc -> IO ()
- errorMsg :: Logger -> SDoc -> IO ()
- fatalErrorMsg :: Logger -> SDoc -> IO ()
- compilationProgressMsg :: Logger -> SDoc -> IO ()
- showPass :: Logger -> String -> IO ()
- withTiming :: MonadIO m => Logger -> SDoc -> (a -> ()) -> m a -> m a
- withTimingSilent :: MonadIO m => Logger -> SDoc -> (a -> ()) -> m a -> m a
- debugTraceMsg :: Logger -> Int -> SDoc -> IO ()
- ghcExit :: Logger -> Int -> IO ()
- prettyPrintGhcErrors :: ExceptionMonad m => Logger -> m a -> m a
- traceCmd :: Logger -> String -> String -> IO a -> IO a
- traceSystoolCommand :: Logger -> String -> IO a -> IO a
- sortMsgBag :: Maybe DiagOpts -> Bag (MsgEnvelope e) -> [MsgEnvelope e]

# Basic types

data Validity' a #

Constructors

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

#### Instances

Instances details

Functor Validity' # |
Instance details Defined in GHC.Utils.Error Methods fmap :: (a -> b) -> Validity' a -> Validity' b # (<$) :: a -> Validity' b -> Validity' a #

type Validity = Validity' SDoc #

Monomorphic version of `Validity'` specialised for `SDoc`s.

andValid :: Validity' a -> Validity' a -> Validity' a #

allValid :: [Validity' a] -> Validity' a #

If they aren't all valid, return the first

getInvalids :: [Validity' a] -> [a] #

data Severity #

Used to describe warnings and errors o The message has a file/line/column heading, plus "warning:" or "error:", added by mkLocMessage o With `SevIgnore` the message is suppressed o Output is intended for end users

Constructors

SevIgnore | Ignore this message, for example in case of suppression of warnings users don't want to see. See Note [Suppressing Messages]
SevWarning |
SevError |

#### Instances

Instances details

Show Severity # |
Instance details Defined in GHC.Types.Error Methods showsPrec :: Int -> Severity -> ShowS # show :: Severity -> String # showList :: [Severity] -> ShowS #
ToJson Severity # |
Instance details Defined in GHC.Types.Error Methods json :: Severity -> JsonDoc #
Outputable Severity # |
Instance details Defined in GHC.Types.Error Methods ppr :: Severity -> SDoc #
Eq Severity # |
Instance details Defined in GHC.Types.Error Methods (==) :: Severity -> Severity -> Bool # (/=) :: Severity -> Severity -> Bool #
Ord Severity # |
Instance details Defined in GHC.Types.Error Methods compare :: Severity -> Severity -> Ordering # (<) :: Severity -> Severity -> Bool # (<=) :: Severity -> Severity -> Bool # (>) :: Severity -> Severity -> Bool # (>=) :: Severity -> Severity -> Bool # max :: Severity -> Severity -> Severity # min :: Severity -> Severity -> Severity #

# Messages

class HasDefaultDiagnosticOpts (DiagnosticOpts a) => Diagnostic a where #

A class identifying a diagnostic. Dictionary.com defines a diagnostic as:

"a message output by a computer diagnosing an error in a computer program, computer system, or component device".

A `Diagnostic` carries the actual description of the message (which, in GHC's case, it can be an error or a warning) and the reason why such message was generated in the first place.

Associated Types

type DiagnosticOpts a #

Type of configuration options for the diagnostic.

Methods

diagnosticMessage :: DiagnosticOpts a -> a -> DecoratedSDoc #

Extract the error message text from a `Diagnostic`.

diagnosticReason :: a -> DiagnosticReason #

Extract the reason for this diagnostic. For warnings, a `DiagnosticReason` includes the warning flag.

diagnosticHints :: a -> [GhcHint] #

Extract any hints a user might use to repair their code to avoid this diagnostic.

diagnosticCode :: a -> Maybe DiagnosticCode #

Get the `DiagnosticCode` associated with this `Diagnostic`. This can return `Nothing` for at least two reasons:

1. The message might be from a plugin that does not supply codes.
2. The message might not yet have been assigned a code. See the `Diagnostic` instance for `DiagnosticMessage`.

Ideally, case (2) would not happen, but because some errors in GHC still use the old system of just writing the error message in-place (instead of using a dedicated error type and constructor), we do not have error codes for all errors. #18516 tracks our progress toward this goal.

#### Instances

Instances details

Diagnostic DriverMessage # |

Instance details

Defined in GHC.Driver.Errors.Ppr

Associated Types

type DiagnosticOpts DriverMessage |
Instance details Defined in GHC.Driver.Errors.Ppr type DiagnosticOpts DriverMessage = DriverMessageOpts

Methods

diagnosticMessage :: DiagnosticOpts DriverMessage -> DriverMessage -> DecoratedSDoc #

diagnosticReason :: DriverMessage -> DiagnosticReason #

diagnosticHints :: DriverMessage -> [GhcHint] #

diagnosticCode :: DriverMessage -> Maybe DiagnosticCode #

Diagnostic GhcMessage # |

Instance details

Defined in GHC.Driver.Errors.Ppr

Associated Types

type DiagnosticOpts GhcMessage |
Instance details Defined in GHC.Driver.Errors.Ppr type DiagnosticOpts GhcMessage = GhcMessageOpts

Methods

diagnosticMessage :: DiagnosticOpts GhcMessage -> GhcMessage -> DecoratedSDoc #

diagnosticReason :: GhcMessage -> DiagnosticReason #

diagnosticHints :: GhcMessage -> [GhcHint] #

diagnosticCode :: GhcMessage -> Maybe DiagnosticCode #

Diagnostic DsMessage # |

Instance details

Defined in GHC.HsToCore.Errors.Ppr

Associated Types

type DiagnosticOpts DsMessage |
Instance details Defined in GHC.HsToCore.Errors.Ppr type DiagnosticOpts DsMessage = NoDiagnosticOpts

Methods

diagnosticMessage :: DiagnosticOpts DsMessage -> DsMessage -> DecoratedSDoc #

diagnosticReason :: DsMessage -> DiagnosticReason #

diagnosticHints :: DsMessage -> [GhcHint] #

diagnosticCode :: DsMessage -> Maybe DiagnosticCode #

Diagnostic IfaceMessage # |

Instance details

Defined in GHC.Iface.Errors.Ppr

Associated Types

type DiagnosticOpts IfaceMessage |
Instance details Defined in GHC.Iface.Errors.Ppr type DiagnosticOpts IfaceMessage = IfaceMessageOpts

Methods

diagnosticMessage :: DiagnosticOpts IfaceMessage -> IfaceMessage -> DecoratedSDoc #

diagnosticReason :: IfaceMessage -> DiagnosticReason #

diagnosticHints :: IfaceMessage -> [GhcHint] #

diagnosticCode :: IfaceMessage -> Maybe DiagnosticCode #

Diagnostic PsMessage # |

Instance details

Defined in GHC.Parser.Errors.Ppr

Associated Types

type DiagnosticOpts PsMessage |
Instance details Defined in GHC.Parser.Errors.Ppr type DiagnosticOpts PsMessage = NoDiagnosticOpts

Methods

diagnosticMessage :: DiagnosticOpts PsMessage -> PsMessage -> DecoratedSDoc #

diagnosticReason :: PsMessage -> DiagnosticReason #

diagnosticHints :: PsMessage -> [GhcHint] #

diagnosticCode :: PsMessage -> Maybe DiagnosticCode #

Diagnostic TcRnMessage # |

Instance details

Defined in GHC.Tc.Errors.Ppr

Associated Types

type DiagnosticOpts TcRnMessage |
Instance details Defined in GHC.Tc.Errors.Ppr type DiagnosticOpts TcRnMessage = TcRnMessageOpts

Methods

diagnosticMessage :: DiagnosticOpts TcRnMessage -> TcRnMessage -> DecoratedSDoc #

diagnosticReason :: TcRnMessage -> DiagnosticReason #

diagnosticHints :: TcRnMessage -> [GhcHint] #

diagnosticCode :: TcRnMessage -> Maybe DiagnosticCode #

Diagnostic DiagnosticMessage # |

Instance details

Defined in GHC.Types.Error

Associated Types

type DiagnosticOpts DiagnosticMessage |
Instance details Defined in GHC.Types.Error type DiagnosticOpts DiagnosticMessage = NoDiagnosticOpts

Methods

diagnosticMessage :: DiagnosticOpts DiagnosticMessage -> DiagnosticMessage -> DecoratedSDoc #

diagnosticReason :: DiagnosticMessage -> DiagnosticReason #

diagnosticHints :: DiagnosticMessage -> [GhcHint] #

diagnosticCode :: DiagnosticMessage -> Maybe DiagnosticCode #

HasDefaultDiagnosticOpts opts => Diagnostic (UnknownDiagnostic opts) # |

Instance details

Defined in GHC.Types.Error

Associated Types

type DiagnosticOpts (UnknownDiagnostic opts) |
Instance details Defined in GHC.Types.Error type DiagnosticOpts (UnknownDiagnostic opts) = opts

Methods

diagnosticMessage :: DiagnosticOpts (UnknownDiagnostic opts) -> UnknownDiagnostic opts -> DecoratedSDoc #

diagnosticReason :: UnknownDiagnostic opts -> DiagnosticReason #

diagnosticHints :: UnknownDiagnostic opts -> [GhcHint] #

diagnosticCode :: UnknownDiagnostic opts -> Maybe DiagnosticCode #

data MsgEnvelope e #

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, 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 :: NamePprCtx
- errMsgDiagnostic :: e
- errMsgSeverity :: Severity
- errMsgReason :: ResolvedDiagnosticReason

  The actual reason caused this message

  See Note [Warnings controlled by multiple flags]

#### Instances

Instances details

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

Instance details

Defined in GHC.Types.Error

Methods

fold :: Monoid m => MsgEnvelope m -> m #

foldMap :: Monoid m => (a -> m) -> MsgEnvelope a -> m #

foldMap' :: Monoid m => (a -> m) -> MsgEnvelope a -> m #

foldr :: (a -> b -> b) -> b -> MsgEnvelope a -> b #

foldr' :: (a -> b -> b) -> b -> MsgEnvelope a -> b #

foldl :: (b -> a -> b) -> b -> MsgEnvelope a -> b #

foldl' :: (b -> a -> b) -> b -> MsgEnvelope a -> b #

foldr1 :: (a -> a -> a) -> MsgEnvelope a -> a #

foldl1 :: (a -> a -> a) -> MsgEnvelope a -> a #

toList :: MsgEnvelope a -> [a] #

null :: MsgEnvelope a -> Bool #

length :: MsgEnvelope a -> Int #

elem :: Eq a => a -> MsgEnvelope a -> Bool #

maximum :: Ord a => MsgEnvelope a -> a #

minimum :: Ord a => MsgEnvelope a -> a #

sum :: Num a => MsgEnvelope a -> a #

product :: Num a => MsgEnvelope a -> a #

Traversable MsgEnvelope # |
Instance details Defined in GHC.Types.Error Methods traverse :: Applicative f => (a -> f b) -> MsgEnvelope a -> f (MsgEnvelope b) # sequenceA :: Applicative f => MsgEnvelope (f a) -> f (MsgEnvelope a) # mapM :: Monad m => (a -> m b) -> MsgEnvelope a -> m (MsgEnvelope b) # sequence :: Monad m => MsgEnvelope (m a) -> m (MsgEnvelope a) #
Show (MsgEnvelope DiagnosticMessage) # |
Instance details Defined in GHC.Types.Error Methods showsPrec :: Int -> MsgEnvelope DiagnosticMessage -> ShowS # show :: MsgEnvelope DiagnosticMessage -> String # showList :: [MsgEnvelope DiagnosticMessage] -> ShowS #
Diagnostic e => ToJson (MsgEnvelope e) # |
Instance details Defined in GHC.Types.Error Methods json :: MsgEnvelope e -> JsonDoc #

data MessageClass #

The class for a diagnostic message. The main purpose is to classify a message within GHC, to distinguish it from a debug/dump message vs a proper diagnostic, for which we include a `DiagnosticReason`.

Constructors

MCOutput |
MCFatal |
MCInteractive |
MCDump | Log message intended for compiler developers No file/line/column stuff
MCInfo | Log messages intended for end users. No file/line/column stuff.

MCDiagnostic Severity ResolvedDiagnosticReason (Maybe DiagnosticCode)

Diagnostics from the compiler. This constructor is very powerful as it allows the construction of a `MessageClass` with a completely arbitrary permutation of `Severity` and `DiagnosticReason`. As such, users are encouraged to use the `mkMCDiagnostic` smart constructor instead. Use this constructor directly only if you need to construct and manipulate diagnostic messages directly, for example inside `Error`. In all the other circumstances, especially when emitting compiler diagnostics, use the smart constructor.

The `Maybe `DiagnosticCode`` field carries a code (if available) for this diagnostic. If you are creating a message not tied to any error-message type, then use Nothing. In the long run, this really should always have a `DiagnosticCode`. See Note [Diagnostic codes].

#### Instances

Instances details

ToJson MessageClass # |
Instance details Defined in GHC.Types.Error Methods json :: MessageClass -> JsonDoc #

data SDoc #

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 # |
Instance details Defined in GHC.Utils.Outputable Methods fromString :: String -> SDoc #
JsRender SDoc # |
Instance details Defined in GHC.JS.Ppr Methods (<+?>) :: SDoc -> SDoc -> SDoc # ($$$) :: SDoc -> SDoc -> SDoc # jcat :: [SDoc] -> SDoc # jnest :: SDoc -> SDoc # addSemi :: SDoc -> SDoc #
IsDoc SDoc # |

Instance details

Defined in GHC.Utils.Outputable

Associated Types

type Line SDoc |
Instance details Defined in GHC.Utils.Outputable type Line SDoc = SDoc

Methods

line :: Line SDoc -> SDoc #

($$) :: SDoc -> SDoc -> SDoc #

lines_ :: [Line SDoc] -> SDoc #

vcat :: [SDoc] -> SDoc #

dualDoc :: SDoc -> HDoc -> SDoc #

IsLine SDoc # |
Instance details Defined in GHC.Utils.Outputable Methods char :: Char -> SDoc # text :: String -> SDoc # ftext :: FastString -> SDoc # ztext :: FastZString -> SDoc # (<>) :: SDoc -> SDoc -> SDoc # (<+>) :: SDoc -> SDoc -> SDoc # sep :: [SDoc] -> SDoc # fsep :: [SDoc] -> SDoc # hcat :: [SDoc] -> SDoc # hsep :: [SDoc] -> SDoc # dualLine :: SDoc -> HLine -> SDoc #
IsOutput SDoc # |
Instance details Defined in GHC.Utils.Outputable Methods empty :: SDoc # docWithContext :: (SDocContext -> SDoc) -> SDoc # docWithStyle :: SDoc -> (PprStyle -> SDoc) -> SDoc #
Outputable SDoc # |
Instance details Defined in GHC.Utils.Outputable Methods ppr :: SDoc -> SDoc #
OutputableP env SDoc # |
Instance details Defined in GHC.Utils.Outputable Methods pdoc :: env -> SDoc -> SDoc #
type Line SDoc # |
Instance details Defined in GHC.Utils.Outputable type Line SDoc = SDoc

data DecoratedSDoc #

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`.

data Messages e #

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

INVARIANT: All the messages in this collection must be relevant, i.e. their `Severity` should not be `SevIgnore`. The smart constructor `mkMessages` will filter out any message which `Severity` is `SevIgnore`.

#### Instances

Instances details

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

Instance details

Defined in GHC.Types.Error

Methods

fold :: Monoid m => Messages m -> m #

foldMap :: Monoid m => (a -> m) -> Messages a -> m #

foldMap' :: Monoid m => (a -> m) -> Messages a -> m #

foldr :: (a -> b -> b) -> b -> Messages a -> b #

foldr' :: (a -> b -> b) -> b -> Messages a -> b #

foldl :: (b -> a -> b) -> b -> Messages a -> b #

foldl' :: (b -> a -> b) -> b -> Messages a -> b #

foldr1 :: (a -> a -> a) -> Messages a -> a #

foldl1 :: (a -> a -> a) -> Messages a -> a #

toList :: Messages a -> [a] #

null :: Messages a -> Bool #

length :: Messages a -> Int #

elem :: Eq a => a -> Messages a -> Bool #

maximum :: Ord a => Messages a -> a #

minimum :: Ord a => Messages a -> a #

sum :: Num a => Messages a -> a #

product :: Num a => Messages a -> a #

Traversable Messages # |
Instance details Defined in GHC.Types.Error Methods traverse :: Applicative f => (a -> f b) -> Messages a -> f (Messages b) # sequenceA :: Applicative f => Messages (f a) -> f (Messages a) # mapM :: Monad m => (a -> m b) -> Messages a -> m (Messages b) # sequence :: Monad m => Messages (m a) -> m (Messages a) #
Monoid (Messages e) # |
Instance details Defined in GHC.Types.Error Methods mempty :: Messages e # mappend :: Messages e -> Messages e -> Messages e # mconcat :: [Messages e] -> Messages e #
Semigroup (Messages e) # |
Instance details Defined in GHC.Types.Error Methods (<>) :: Messages e -> Messages e -> Messages e # sconcat :: NonEmpty (Messages e) -> Messages e # stimes :: Integral b => b -> Messages e -> Messages e #
Diagnostic e => ToJson (Messages e) # |
Instance details Defined in GHC.Types.Error Methods json :: Messages e -> JsonDoc #
Diagnostic e => Outputable (Messages e) # |
Instance details Defined in GHC.Types.Error Methods ppr :: Messages e -> SDoc #

mkMessages :: Bag (MsgEnvelope e) -> Messages e #

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

Joins two collections of messages together. See Note [Discarding Messages].

errorsFound :: Diagnostic e => Messages e -> Bool #

Are there any hard errors here? -Werror warnings are not detected. If you want to check for -Werror warnings, use `errorsOrFatalWarningsFound`.

isEmptyMessages :: Messages e -> Bool #

## Formatting

pprMessageBag :: Bag SDoc -> SDoc #

pprMsgEnvelopeBagWithLoc :: Diagnostic e => DiagnosticOpts e -> Bag (MsgEnvelope e) -> [SDoc] #

pprMsgEnvelopeBagWithLocDefault :: Diagnostic e => Bag (MsgEnvelope e) -> [SDoc] #

Print the messages with the suitable default configuration, usually not what you want but sometimes you don't really care about what the configuration is (for example, if the message is in a panic).

pprMessages :: Diagnostic e => DiagnosticOpts e -> Messages e -> SDoc #

pprLocMsgEnvelope :: Diagnostic e => DiagnosticOpts e -> MsgEnvelope e -> SDoc #

pprLocMsgEnvelopeDefault :: Diagnostic e => MsgEnvelope e -> SDoc #

formatBulleted :: DecoratedSDoc -> SDoc #

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

## Construction

data DiagOpts #

Constructors

DiagOpts |

Fields

- diag_warning_flags :: !(EnumSet WarningFlag)

  Enabled warnings

- diag_fatal_warning_flags :: !(EnumSet WarningFlag)

  Fatal warnings

- diag_custom_warning_categories :: !WarningCategorySet

  Enabled custom warning categories

- diag_fatal_custom_warning_categories :: !WarningCategorySet

  Fatal custom warning categories

- diag_warn_is_error :: !Bool

  Treat warnings as errors

- diag_reverse_errors :: !Bool

  Reverse error reporting order

- diag_max_errors :: !(Maybe Int)

  Max reported error count

- diag_ppr_ctx :: !SDocContext

  Error printing context

emptyDiagOpts :: DiagOpts #

diag_wopt :: WarningFlag -> DiagOpts -> Bool #

diag_fatal_wopt :: WarningFlag -> DiagOpts -> Bool #

emptyMessages :: Messages e #

mkDecorated :: [SDoc] -> DecoratedSDoc #

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

mkLocMessage #

Arguments

:: MessageClass | What kind of message?
-> SrcSpan | location
-> SDoc | message
-> SDoc |

mkMsgEnvelope :: Diagnostic e => DiagOpts -> SrcSpan -> NamePprCtx -> e -> MsgEnvelope e #

Wrap a `Diagnostic` in a `MsgEnvelope`, recording its location. If you know your `Diagnostic` is an error, consider using `mkErrorMsgEnvelope`, which does not require looking at the `DiagOpts`

mkPlainMsgEnvelope :: Diagnostic e => DiagOpts -> SrcSpan -> e -> MsgEnvelope e #

Variant that doesn't care about qualified/unqualified names.

mkPlainErrorMsgEnvelope :: Diagnostic e => SrcSpan -> e -> MsgEnvelope e #

Variant of `mkPlainMsgEnvelope` which can be used when we are sure we are constructing a diagnostic with a `ErrorWithoutFlag` reason.

mkErrorMsgEnvelope :: Diagnostic e => SrcSpan -> NamePprCtx -> e -> MsgEnvelope e #

Wrap a `Diagnostic` in a `MsgEnvelope`, recording its location. Precondition: the diagnostic is, in fact, an error. That is, `diagnosticReason msg == ErrorWithoutFlag`.

mkMCDiagnostic :: DiagOpts -> DiagnosticReason -> Maybe DiagnosticCode -> MessageClass #

Make a `MessageClass` for a given `DiagnosticReason`, consulting the `DiagOpts`.

errorDiagnostic :: MessageClass #

Varation of `mkMCDiagnostic` which can be used when we are sure the input `DiagnosticReason` is `ErrorWithoutFlag` and there is no diagnostic code.

diagReasonSeverity :: DiagOpts -> DiagnosticReason -> Severity #

Computes the right `Severity` for the input `DiagnosticReason` out of the 'DiagOpts. This function has to be called when a diagnostic is constructed, i.e. with a 'DiagOpts "snapshot" taken as close as possible to where a particular diagnostic message is built, otherwise the computed `Severity` might not be correct, due to the mutable nature of the `DynFlags` in GHC.

mkPlainError :: [GhcHint] -> SDoc -> DiagnosticMessage #

Create an error `DiagnosticMessage` holding just a single `SDoc`

mkPlainDiagnostic :: DiagnosticReason -> [GhcHint] -> SDoc -> DiagnosticMessage #

mkDecoratedError :: [GhcHint] -> [SDoc] -> DiagnosticMessage #

Create an error `DiagnosticMessage` from a list of bulleted SDocs

mkDecoratedDiagnostic :: DiagnosticReason -> [GhcHint] -> [SDoc] -> DiagnosticMessage #

Create a `DiagnosticMessage` from a list of bulleted SDocs and a `DiagnosticReason`

noHints :: [GhcHint] #

Helper function to use when no hints can be provided. Currently this function can be used to construct plain `DiagnosticMessage` and add hints to them, but once #18516 will be fully executed, the main usage of this function would be in the implementation of the `diagnosticHints` typeclass method, to report the fact that a particular `Diagnostic` has no hints.

# Utilities

getCaretDiagnostic :: MessageClass -> SrcSpan -> IO SDoc #

# Issuing messages during compilation

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

printInfoForUser :: Logger -> NamePprCtx -> SDoc -> IO () #

printOutputForUser :: Logger -> NamePprCtx -> SDoc -> IO () #

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

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

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

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

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

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

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

withTiming #

Arguments

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

Arguments

:: MonadIO m |
=> Logger |
-> 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 -> Int -> SDoc -> IO () #

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

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

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

Trace a command (when verbosity level >= 3)

traceSystoolCommand :: Logger -> String -> IO a -> IO a #

Record in the eventlog when the given tool command starts and finishes, prepending the given `String` with "systool:", to easily be able to collect and process all the systool events.

For those events to show up in the eventlog, you need to run GHC with `-v2` or `-ddump-timings`.

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