Documentation

Defines whether a particular diagnostic should be reported back to the user.

One important use case is "missing signature" code lenses, for which we need to enable the corresponding warning during type checking. However, we do not want to show the warning unless the programmer asks for it (#261).

Human readable diagnostics for a specific file.

This type packages a pretty printed, human readable error message along with the related source location so that we can display the error on either the console or in the IDE at the right source location.

It also optionally keeps a structured diagnostic message GhcMessage in StructuredMessage.

A Maybe-like wrapper for a GhcMessage that doesn't try to compare, show, or force the GhcMessage inside, so that we can derive Show, Eq, Ord, NFData on FileDiagnostic. FileDiagnostic only uses this as metadata so we can safely ignore it in fields.

Instead of pattern matching on these constructors directly, consider Prism from the lens package. This allows to conveniently pattern match deeply into the 'MsgEnvelope GhcMessage' constructor. The module Error implements additional Lenss and Prisms, allowing you to avoid importing GHC modules directly.

For example, to pattern match on a TcRnMessage you can use the lens:

  message ^? _SomeStructuredMessage . msgEnvelopeErrorL . _TcRnMessage

This produces a value of type `Maybe TcRnMessage`.

Further, consider utility functions such as stripTcRnMessageContext, which strip context from error messages which may be more convenient in certain situations.

The result of an IDE operation. Warnings and errors are in the Diagnostic, and a value is in the Maybe. For operations that throw an error you expect a non-empty list of diagnostics, at least one of which is an error, and a Nothing. For operations that succeed you expect perhaps some warnings and a Just. For operations that depend on other failing operations you may get empty diagnostics and a Nothing, to indicate this phase throws no fresh errors but still failed.

A rule on a file should only return diagnostics for that given file. It should not propagate diagnostic errors through multiple phases.

Produce a FileDiagnostic for the given NormalizedFilePath with an error message.

Create a FileDiagnostic from an existing Diagnostic for a specific NormalizedFilePath. The optional 'MsgEnvelope GhcMessage' is the original error message that was used for creating the Diagnostic. It is included here, to allow downstream consumers, such as HLS plugins, to provide LSP features based on the structured error messages. Additionally, if available, we insert the ghc error code into the Diagnostic. These error codes are used in https://errors.haskell.org/ to provide documentation and explanations for error messages.

an IdeResult with a fingerprint