@@ -1,33 +1,33 @@
1−-- | Support for checked exceptions.
1+-- | Support for handling errors of a particular type, i.e. checked exceptions.
22--
3−-- /Note:/ the 'Error' effect provided by this module is a suitable replacement
4−-- for the "Control.Monad.Trans.Except" monad transformer found in the
3+-- /Note:/ the 'Error' effect is a suitable replacement for the
4+-- 'Control.Monad.Trans.Except.ExceptT' monad transformer from the
55-- @transformers@ library. It is __not__ a general mechanism for handling
6−-- exceptions, that's what functions from the "Control.Monad.Catch" module are
7−-- for.
6+-- exceptions, that's what functions from the @exceptions@ library are for (see
7+-- "Control.Monad.Catch" for more information).
88--
9−-- For example, if you want to catch an unchecked exception like
10−-- 'Control.Exception.ErrorCall' you could use 'Control.Monad.Catch.catch':
9+-- In particular, exceptions of type @e@ are distinct from errors of type @e@
10+-- and will __not__ be caught by functions from this module:
1111--
1212-- >>> import qualified Control.Monad.Catch as E
1313-- >>> let boom = error "BOOM!"
14−-- >>> runEff $ boom `E.catch` \(_::ErrorCall) -> pure "caught an error"
15−-- "caught an error"
16−--
17−-- In particular, unchecked exceptions of type @e@ are distinct from errors of
18−-- type @e@ and will __not__ be caught by functions from this module:
19−--
20−-- >>> runEff . runError @ErrorCall $ boom `catchError` \_ (_::ErrorCall) -> pure "caught an error"
14+-- >>> runEff . runError @ErrorCall $ boom `catchError` \_ (_::ErrorCall) -> pure "caught"
2115-- *** Exception: BOOM!
2216-- ...
2317--
18+-- If you want to catch regular exceptions, you should use
19+-- 'Control.Monad.Catch.catch' (or a similar function):
20+--
21+-- >>> runEff $ boom `E.catch` \(_::ErrorCall) -> pure "caught"
22+-- "caught"
23+--
2424-- On the other hand, functions for safe finalization and management of
2525-- resources such as 'Control.Monad.Catch.finally' and
2626-- 'Control.Monad.Catch.bracket' work as expected:
2727--
2828-- >>> let display = liftIO . putStrLn
2929-- >>> :{
30−-- runEff . fmap (first snd) . runError @String $ do
30+-- runEff . fmap (either (Left . snd) Right) . runError @String $ do
3131-- E.bracket_ (display "Beginning.")
3232-- (display "Cleaning up.")
3333-- (display "Computing." >> throwError "oops" >> display "More.")
@@ -61,7 +61,7 @@ import GHC.Stack
6161import Effectful.Dispatch.Static
6262import Effectful.Monad
6363
64−-- | Provide the capability of handling errors of type @e@.
64+-- | Provide the ability to handle errors of type @e@.
6565newtype Error e :: Effect where
6666 Error :: ErrorId -> Error e m r
6767
@@ -167,6 +167,3 @@ catchErrorIO eid m handler = do
167167 if eid == etag
168168 then handler e cs
169169 else throwIO err
170−
171−-- $setup
172−-- >>> import Data.Bifunctor