62ac970 · effectful · git.iko.soy

effectful-core/src/Effectful/Error.hs+16−19

compare with master

unifiedsplit

@@ -1,33 +1,33 @@

1−-- | Support for checked exceptions.

1+-- | Support for handling errors of a particular type, i.e. checked exceptions.

2--

3−-- /Note:/ the 'Error' effect provided by this module is a suitable replacement

3+-- /Note:/ the 'Error' effect is a suitable replacement for the

4−-- for the "Control.Monad.Trans.Except" monad transformer found in the

4+-- 'Control.Monad.Trans.Except.ExceptT' monad transformer from the

5-- @transformers@ library. It is __not__ a general mechanism for handling

6−-- exceptions, that's what functions from the "Control.Monad.Catch" module are

6+-- exceptions, that's what functions from the @exceptions@ library are for (see

7−-- for.

7+-- "Control.Monad.Catch" for more information).

8--

9−-- For example, if you want to catch an unchecked exception like

9+-- In particular, exceptions of type @e@ are distinct from errors of type @e@

10−-- 'Control.Exception.ErrorCall' you could use 'Control.Monad.Catch.catch':

10+-- and will __not__ be caught by functions from this module:

11--

12-- >>> import qualified Control.Monad.Catch as E

13-- >>> 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"

21-- *** Exception: BOOM!

15-- *** Exception: BOOM!

22-- ...

16-- ...

23--

17--

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+--

24-- On the other hand, functions for safe finalization and management of

25-- resources such as 'Control.Monad.Catch.finally' and

26-- 'Control.Monad.Catch.bracket' work as expected:

27--

28-- >>> let display = liftIO . putStrLn

29-- >>> :{

30−-- runEff . fmap (first snd) . runError @String $ do

30+-- runEff . fmap (either (Left . snd) Right) . runError @String $ do

31-- E.bracket_ (display "Beginning.")

32-- (display "Cleaning up.")

33-- (display "Computing." >> throwError "oops" >> display "More.")

@@ -61,7 +61,7 @@ import GHC.Stack

61import Effectful.Dispatch.Static

62import Effectful.Monad

63

64−-- | Provide the capability of handling errors of type @e@.

64+-- | Provide the ability to handle errors of type @e@.

65newtype Error e :: Effect where

66 Error :: ErrorId -> Error e m r

67

@@ -167,6 +167,3 @@ catchErrorIO eid m handler = do

167 if eid == etag

168 then handler e cs

169 else throwIO err

170−

171−-- $setup

172−-- >>> import Data.Bifunctor

effectful-core/src/Effectful/Fail.hs+1

@@ -1,3 +1,4 @@

1+-- | Provider of the 'MonadFail' instance for 'Eff'.

1module Effectful.Fail

2module Effectful.Fail

2 ( Fail(..)

3 ( Fail(..)

3 , runFail

4 , runFail

effectful-core/src/Effectful/Internal/Monad.hs+1−1

@@ -296,7 +296,7 @@ instance IOE :> es => MonadBaseControl IO (Eff es) where

296----------------------------------------

297-- Primitive

298

299−-- | An effect to perform primitive state-transformer actions.

299+-- | Provide the ability to perform primitive state-transformer actions.

300data Prim :: Effect where

301 Prim :: Prim m r

302

effectful-core/src/Effectful/Prim.hs+1

@@ -1,3 +1,4 @@

1+-- | Provider of the 'MonadPrim' instance for 'Eff'.

1module Effectful.Prim

2module Effectful.Prim

2 ( Prim

3 ( Prim

3 , runPrim

4 , runPrim

effectful-core/src/Effectful/Writer/Local.hs+1−1

@@ -16,7 +16,7 @@

16-- @transformers@ package includes additional operations

17-- 'Control.Monad.Trans.Writer.Strict.pass' and

18-- 'Control.Monad.Trans.Writer.Strict.censor', they don't cooperate with runtime

19−-- exceptions very well, so they're deliberately omitted here.

19+-- exceptions very well, so they're deliberately omitted.

20module Effectful.Writer.Local

21 ( Writer

22 , runWriter

effectful-core/src/Effectful/Writer/Shared.hs+18

@@ -1,3 +1,21 @@

1+-- | The 'Writer' effect.

2+--

3+-- Represented as an 'MVar' underneath, therefore:

4+--

5+-- - shareable between multiple threads,

6+--

7+-- - slower than "Effectful.Writer.Local".

8+--

9+-- /Warning:/ 'Writer'\'s state will be accumulated via __left-associated__ uses

10+-- of '<>', which makes it unsuitable for use with types for which such pattern

11+-- is inefficient. __This applies, in particular, to the standard list type__,

12+-- which makes the 'Writer' effect pretty niche.

13+--

14+-- /Note:/ while the 'Control.Monad.Trans.Writer.Strict.Writer' from the

15+-- @transformers@ package includes additional operations

16+-- 'Control.Monad.Trans.Writer.Strict.pass' and

17+-- 'Control.Monad.Trans.Writer.Strict.censor', they don't cooperate with runtime

18+-- exceptions very well, so they're deliberately omitted.

1module Effectful.Writer.Shared

19module Effectful.Writer.Shared

2 ( Writer

20 ( Writer

3 , runWriter

21 , runWriter