Data.Error

Documentation

data Error

The canonical Error type.

It can be

• created from a human-readable error message (newError)
• more semantic context can be added to an existing Error (addContext)
• pretty-printed (prettyError)

Instances

Show Error

The Show instance exists for the user’s convenience on the REPL.

If you want to display an error, use prettyError instead.

Defined in Data.Error

Methods

showsPrec :: Int -> Error -> ShowS

show :: Error -> String

showList :: [Error] -> ShowS

Error creation

newError :: Text -> Error

Create an ad-hoc Error from an error message.

From Show and Exception

These two functions can be helpful, but consider that they don’t always provide very user-friendly error messages. It is recommended that you use addContext to improve the messages generated by showToError and exceptionToError.

showToError :: Show a => a -> Error

Create an error from a Show type.

If your type implements Exception, it is usually better to use exceptionToError instead. Strings produced by show are usually not very user-friendly.

Note: goes via String, so not efficient.

exceptionToError :: Exception exc => exc -> Error

Create an error from an Exception type.

The default implementation of displayException is show, so the same user-friendliness problems of showToError apply.

Note: goes via String, so not efficient.

Adding context

addContext :: Text -> Error -> Error

Add a higher-level context to an Error.

For example, your code hits a “file not found” I/O exception. Instead of propagating it unseen, you catch it and annotate it with addContext, and describe why you wanted to open the file in the first place:

addContext "Trying to open config file"
  $ newError "file not found: ./foo"

This way, when a user see the error, they will understand better what happened:

"Trying to open config file: file not found: ./foo"

See prettyError.

Pretty printing

prettyError :: Error -> Text

Pretty print the error.

It will print all context messages, starting with the outermost.

Example:

>>> prettyError $ newError "file not found: ./foo"
"file not found: ./foo"

>>> :{
  prettyError
    $ addContext "Trying to open config file"
      $ newError "file not found: ./foo"
:}
"Trying to open config file: file not found: ./foo"

Unsafe unwrapping

Sometimes you want to assure that an Error could not have happened at runtime, even though there is the possibility in the types. In that case you can use expectError/unwrapError. They will panic at runtime if there was an error.

expectError should usually be preffered, since it adds a context message.

These are modelled after Result::expect() and Result::unwrap() in the rust stdlib.

expectError :: HasCallStack => Text -> Either Error p -> p

Return the value from a potentially failing computation.

Abort with the error message if it was an error.

The text message is added to the Error as additional context before aborting.

Panics: if Error

Example:

>>> expectError "something bad happened" $ Left (newError "oh no!")
*** Exception: something bad happened: oh no!
...

>>> expectError "something bad happened" $ Right 42
42

unwrapError :: HasCallStack => Either Error p -> p

Return the value from a potentially failing computation.

Abort with the Errors message if it was a Left.

Panics: if Error

Example:

>>> unwrapError $ Left (newError "oh no!")
*** Exception: oh no!
...

>>> unwrapError $ Right 42
42