GHC.Utils.Error

Basic types

data Validity' a

Constructors

IsValid

Everything is fine

NotValid a

A problem, and some indication of why

Instances

Functor Validity'

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

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

Show Severity

Defined in GHC.Types.Error

Methods

showsPrec :: Int -> Severity -> ShowS

show :: Severity -> String

showList :: [Severity] -> ShowS

ToJson Severity

Defined in GHC.Types.Error

Methods

json :: Severity -> JsonDoc

Outputable Severity

Defined in GHC.Types.Error

Methods

ppr :: Severity -> SDoc

Eq Severity

Defined in GHC.Types.Error

Methods

(==) :: Severity -> Severity -> Bool

(/=) :: Severity -> Severity -> Bool

Messages

class 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

defaultDiagnosticOpts :: DiagnosticOpts a

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

Diagnostic DriverMessage

Defined in GHC.Driver.Errors.Ppr

Associated Types

type DiagnosticOpts DriverMessage

Methods

defaultDiagnosticOpts :: DiagnosticOpts DriverMessage

diagnosticMessage :: DiagnosticOpts DriverMessage -> DriverMessage -> DecoratedSDoc

diagnosticReason :: DriverMessage -> DiagnosticReason

diagnosticHints :: DriverMessage -> [GhcHint]

diagnosticCode :: DriverMessage -> Maybe DiagnosticCode

Diagnostic GhcMessage

Defined in GHC.Driver.Errors.Ppr

Associated Types

type DiagnosticOpts GhcMessage

Methods

defaultDiagnosticOpts :: DiagnosticOpts GhcMessage

diagnosticMessage :: DiagnosticOpts GhcMessage -> GhcMessage -> DecoratedSDoc

diagnosticReason :: GhcMessage -> DiagnosticReason

diagnosticHints :: GhcMessage -> [GhcHint]

diagnosticCode :: GhcMessage -> Maybe DiagnosticCode

Diagnostic DsMessage

Defined in GHC.HsToCore.Errors.Ppr

Associated Types

type DiagnosticOpts DsMessage

Methods

defaultDiagnosticOpts :: DiagnosticOpts DsMessage

diagnosticMessage :: DiagnosticOpts DsMessage -> DsMessage -> DecoratedSDoc

diagnosticReason :: DsMessage -> DiagnosticReason

diagnosticHints :: DsMessage -> [GhcHint]

diagnosticCode :: DsMessage -> Maybe DiagnosticCode

Diagnostic PsMessage

Defined in GHC.Parser.Errors.Ppr

Associated Types

type DiagnosticOpts PsMessage

Methods

defaultDiagnosticOpts :: DiagnosticOpts PsMessage

diagnosticMessage :: DiagnosticOpts PsMessage -> PsMessage -> DecoratedSDoc

diagnosticReason :: PsMessage -> DiagnosticReason

diagnosticHints :: PsMessage -> [GhcHint]

diagnosticCode :: PsMessage -> Maybe DiagnosticCode

Diagnostic TcRnMessage

Defined in GHC.Tc.Errors.Ppr

Associated Types

type DiagnosticOpts TcRnMessage

Methods

defaultDiagnosticOpts :: DiagnosticOpts TcRnMessage

diagnosticMessage :: DiagnosticOpts TcRnMessage -> TcRnMessage -> DecoratedSDoc

diagnosticReason :: TcRnMessage -> DiagnosticReason

diagnosticHints :: TcRnMessage -> [GhcHint]

diagnosticCode :: TcRnMessage -> Maybe DiagnosticCode

Diagnostic DiagnosticMessage

Defined in GHC.Types.Error

Associated Types

type DiagnosticOpts DiagnosticMessage

Methods

defaultDiagnosticOpts :: DiagnosticOpts DiagnosticMessage

diagnosticMessage :: DiagnosticOpts DiagnosticMessage -> DiagnosticMessage -> DecoratedSDoc

diagnosticReason :: DiagnosticMessage -> DiagnosticReason

diagnosticHints :: DiagnosticMessage -> [GhcHint]

diagnosticCode :: DiagnosticMessage -> Maybe DiagnosticCode

Diagnostic UnknownDiagnostic

Defined in GHC.Types.Error

Associated Types

type DiagnosticOpts UnknownDiagnostic

Methods

defaultDiagnosticOpts :: DiagnosticOpts UnknownDiagnostic

diagnosticMessage :: DiagnosticOpts UnknownDiagnostic -> UnknownDiagnostic -> DecoratedSDoc

diagnosticReason :: UnknownDiagnostic -> DiagnosticReason

diagnosticHints :: UnknownDiagnostic -> [GhcHint]

diagnosticCode :: UnknownDiagnostic -> 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 MsgEnvelopes 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

Instances

Foldable MsgEnvelope

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

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)

Functor MsgEnvelope

Defined in GHC.Types.Error

Methods

fmap :: (a -> b) -> MsgEnvelope a -> MsgEnvelope b

(<$) :: a -> MsgEnvelope b -> MsgEnvelope a

Show (MsgEnvelope DiagnosticMessage)

Defined in GHC.Types.Error

Methods

showsPrec :: Int -> MsgEnvelope DiagnosticMessage -> ShowS

show :: MsgEnvelope DiagnosticMessage -> String

showList :: [MsgEnvelope DiagnosticMessage] -> ShowS

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 DiagnosticReason (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

ToJson MessageClass

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

IsString SDoc

Defined in GHC.Utils.Outputable

Methods

fromString :: String -> SDoc

IsDoc SDoc

Defined in GHC.Utils.Outputable

Associated Types

type Line SDoc = (r :: Type)

Methods

line :: Line SDoc -> SDoc

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

lines_ :: [Line SDoc] -> SDoc

vcat :: [SDoc] -> SDoc

dualDoc :: SDoc -> HDoc -> SDoc

IsLine SDoc

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

Defined in GHC.Utils.Outputable

Methods

empty :: SDoc

docWithContext :: (SDocContext -> SDoc) -> SDoc

Outputable SDoc

Defined in GHC.Utils.Outputable

Methods

ppr :: SDoc -> SDoc

OutputableP env SDoc

Defined in GHC.Utils.Outputable

Methods

pdoc :: env -> SDoc -> SDoc

type Line SDoc

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

Foldable Messages

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

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)

Functor Messages

Defined in GHC.Types.Error

Methods

fmap :: (a -> b) -> Messages a -> Messages b

(<$) :: a -> Messages b -> Messages a

Monoid (Messages e)

Defined in GHC.Types.Error

Methods

mempty :: Messages e

mappend :: Messages e -> Messages e -> Messages e

mconcat :: [Messages e] -> Messages e

Semigroup (Messages e)

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 => Outputable (Messages e)

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 :: forall e. 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 :: forall e. Diagnostic e => MsgEnvelope e -> SDoc

formatBulleted :: SDocContext -> 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_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

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]