Documentation

The point of the newtype and all the annoying boilerplate is to redefine the "fail" method of the Monad and MonadFail typeclasses.

An error: a primary location and message, plus optional secondary labelled locations and suggested-fix hints.

A non-fatal diagnostic: printed to stderr when emitted (see warnAt), or promoted to an AstError under -Werror.

A secondary location with an explanatory note, attached to an error to point at a related part of the source (e.g. "first defined here").

The strategy of combining computations that can throw exceptions by bypassing bound functions from the point an exception is thrown to the point that it is handled.

Is parameterized over the type of error information and the monad type constructor. It is common to use Either String as the monad type constructor for an error monad in which error descriptions take the form of strings. In that case and many other common cases the resulting monad is already defined as an instance of the MonadError class. You can also define your own error type and/or use a monad type constructor other than Either String or Either IOError. In these cases you will have to explicitly define instances of the MonadError class. (If you are using the deprecated Control.Monad.Error or Control.Monad.Trans.Error, you may also have to define an Error instance.)

Like failAt, but include an extra bit of data on failure.

Like failAt, but attach secondary labelled locations and/or hints.

Report a violated internal invariant: a bug in rwc itself, not a problem with the user's program. Rendered with a "please report it" hint so the message can't be mistaken for a complaint about the user's code.

Re-point a diagnostic at a fallback location when it has none, or when it resolves to a different source file than the fallback — typically because the error surfaced inside inlined library code while compiling a user definition. The original location, when it had one, is kept as a secondary note so the expansion site stays visible.

Run an action, relocating any error it raises to the given fallback location (see relocateErr).

Emit a warning: printed to stderr immediately (so it isn't lost if a later pass fails), suppressed by -w, or promoted to an error by -Werror (which therefore fails on the *first* warning).

Print an error to stderr, GHC-style, with a source excerpt and a caret under the offending region (plus any secondary "note" blocks) when the files can be found on the load path.