@@ -1,4 +1,21 @@
1−-- | Support for checked exceptions.
1+{- | Support for checked exceptions.
2+
3+ The `Error` effect provided by this module is a suitable replacement for the
4+ `Control.Monad.Except.ExceptT` monad transformer found in the mtl library.
5+ It is __not__ intended to be a general mechanism for catching errors like
6+ the functions of the 'exceptions' package. For example, if you want to catch
7+ an unchecked exception like `Control.Exception.SomeException` or
8+ `Control.Exception.ErrorCall` you could rely on `Control.Monad.catch`:
9+
10+ >>> :{
11+ let boom :: Eff '[IOE] String
12+ boom = error "BOOM!"
13+ in
14+ runIOE $ boom `Control.Monad.Catch.catch` \(e :: ErrorCall) ->
15+ return "caught some error"
16+ :}
17+ "caught some error"
18+-}
219module Effectful.Error
320 ( Error
421 , runError
@@ -19,6 +36,11 @@ import Effectful.Internal.Effect
1936import Effectful.Internal.Env
2037import Effectful.Internal.Monad
2138
39+-- $setup
40+-- >>> import Control.Monad.Catch
41+-- >>> import Control.Monad.IO.Class
42+-- >>> import Effectful.Interpreter
43+
2244data Error e :: Effect where
2345 Error :: Unique -> Error e m r
2446