error-context: Provides API for enriching errors with contexts

[ bsd3, control, error-handling, library ] [ Propose Tags ]

Please see the README on Github at https://github.com/mtesseract/error-context#readme


[Skip to Readme]
Versions [faq] 0.1.0.0, 0.1.1.0, 0.1.2.0, 0.2.0.0, 0.2.0.1
Change log ChangeLog.md
Dependencies base (>=4.7 && <5), exceptions, monad-logger, mtl, resourcet, safe-exceptions, text, unliftio-core [details]
License BSD-3-Clause
Copyright (c) 2018 Moritz Clasmeier
Author Moritz Clasmeier
Maintainer mtesseract@silverratio.net
Category Control, Error Handling
Home page https://github.com/mtesseract/error-context#readme
Bug tracker https://github.com/mtesseract/error-context/issues
Source repo head: git clone https://github.com/mtesseract/error-context
Uploaded by mtesseract at Mon Apr 2 11:41:30 UTC 2018
Distributions NixOS:0.2.0.1
Downloads 718 total (41 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2018-04-14 [all 1 reports]

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for error-context-0.1.1.0

[back to package description]

!! This is experimental work-in-progress !!

Welcome to error-context! This is a library providing context-aware error and exception handling for Haskell.

What problem does error-context attempt to solve?

Good error handling is hard. Sometimes it happens that when propagating errors some context is lost. Call traces sometimes help, but the current solutions in Haskell-land for accessing call traces are rather limited. Furthermore, sometimes call traces that at written by and for humans are more convenient to read.

The error-context library allows you to easily attach call traces ('error contexts') to errors, in particular to exceptions. Special catch-functions are provided for accessing these contexts.

How to use it?

Add an ErrorContextT layer to your monad transformer stack by adding runErrorContextT to the transformer unwrapping code.

The ErrorContextT transformer provides the context-enriching logic via special implementations of MonadThrow, MonadCatch and MonadIO.

Examples

See https://github.com/mtesseract/error-context/blob/master/test/Control/Error/Context/Test.hs.

What about "pure" exceptions?

The ErrorContextT transformer implements MonadThrow and MonadIO, therefore exceptions thrown by throwM and via liftIO are automatically context-enriched. But the story for exceptional values created via

throw :: Exception e => e -> a

are not context-enriched. But there is a workaround for this use-case:

ensureExceptionContext :: (MonadCatch m, MonadErrorContext m) => m a -> m a

This function provides context-aware enriching for any exceptions thrown within some monadic value, including those thrown by evaluating values created by throw.