mtl 2.3 → 2.3.1
raw patch · 8 files changed
+188/−33 lines, 8 filesdep ~base
Dependency ranges changed: base
Files
- CHANGELOG.markdown +20/−8
- Control/Monad/Cont.hs +23/−1
- Control/Monad/Cont/Class.hs +57/−3
- Control/Monad/Error/Class.hs +44/−2
- Control/Monad/Except.hs +11/−0
- Control/Monad/Writer/Class.hs +2/−2
- README.markdown +23/−8
- mtl.cabal +8/−9
CHANGELOG.markdown view
@@ -1,7 +1,18 @@+2.3.1 -- 2022-09-10+-----+* Add `modifyError` to `Control.Monad.Error.Class`, and re-export from+ `Control.Monad.Except`.+* Make the `MonadCont` instance for `ContT` more polykinded; now, `r` is allowed+ to be of an arbitrary kind `k`, rather than only `Type`.+* Add a generic `liftCallCC` for use with any `MonadTrans`.+* Add `modifyError` to `Control.Monad.Error.Class`+* Return re-export of `ExceptT` and related functions to `Control.Monad.Except`.+* Add `label` function to `MonadCont`+ 2.3 -- 2022-05-07 ----* Add instances for `Control.Monad.Trans.Writer.CPS` and - `Control.Monad.Trans.RWS.CPS` from `transformers` 0.5.6 and add +* Add instances for `Control.Monad.Trans.Writer.CPS` and+ `Control.Monad.Trans.RWS.CPS` from `transformers` 0.5.6 and add `Control.Monad.Writer.CPS` and `Control.Monad.RWS.CPS`. * `Control.Monad.Cont` now re-exports `evalCont` and `evalContT`. * Add `tryError`, `withError`, `handleError`, and `mapError` to@@ -9,7 +20,7 @@ * Remove `Control.Monad.List` and `Control.Monad.Error`. * Remove instances of deprecated `ListT` and `ErrorT`. * Remove re-exports of `Error`.-* Add instances for `Control.Monad.Trans.Accum` and +* Add instances for `Control.Monad.Trans.Accum` and `Control.Monad.Trans.Select`. * Require GHC 8.6 or higher, and `cabal-install` 3.0 or higher. * Require `transformers-0.5.6` or higher.@@ -17,8 +28,9 @@ `LiftingAccum` deriving helper. * Add `Control.Monad.Select` for the `MonadSelect` type class, as well as the `LiftingSelect` deriving helper.+* Remove re-exports of `Control.Monad`, `Control.Monad.Fix` and `Data.Monoid` modules -2.2.2+2.2.2 -- 2018-02-24 ----- * `Control.Monad.Identity` now re-exports `Control.Monad.Trans.Identity` * Fix a bug in which `Control.Monad.State.Class.modify'` was not as strict in@@ -28,24 +40,24 @@ `Control.Monad.Except{.Class}` * Add a `MonadWriter w ((,) w)` instance (when built against `base-4.9` or later) -2.2.1+2.2.1 -- 2014-06-02 ------- * Provide MINIMAL pragmas for `MonadState`, `MonadWriter`, `MonadReader` * Added a cyclic definition of `ask` in terms of `reader` for consistency with `get`/`put` vs. `state` and `tell` vs. `writer` * Fix deprecation warnings caused by `transformers` 0.4 deprecating `ErrorT`. * Added `Control.Monad.Except` in the style of the other `mtl` re-export modules -2.2.0.1+2.2.0.1 -- 2014-05-05 ------- * Fixed a bug caused by the change in how `transformers` 0.4 exports its data types. We will now export `runFooT` for each transformer again! -2.2+2.2 -- 2014-05-05 --- * `transformers` 0.4 support * Added instances for `ExceptT` * Added `modify'` to `Control.Monad.State.*` -2.1.3.1+2.1.3.1 -- 2014-03-24 ------- * Avoid importing `Control.Monad.Instances` on GHC 7.8 to build without deprecation warnings.
Control/Monad/Cont.hs view
@@ -53,6 +53,9 @@ module Control.Monad.Cont ( -- * MonadCont class MonadCont.MonadCont(..),+ MonadCont.label,+ MonadCont.label_,+ -- * The Cont monad Cont.Cont, Cont.cont,@@ -71,9 +74,12 @@ -- * Example 2: Using @callCC@ -- $callCCExample- + -- * Example 3: Using @ContT@ Monad Transformer -- $ContTExample++ -- * Example 4: Using @label@+ -- $labelExample ) where import qualified Control.Monad.Cont.Class as MonadCont@@ -164,4 +170,20 @@ @askString@ takes as a parameter a continuation taking a string parameter, and returning @IO ()@. Compare its signature to 'runContT' definition.+-}++{-$labelExample++The early exit behavior of 'Control.Monad.Cont.Class.callCC' can be leveraged to produce other idioms:++> whatsYourNameLabel :: IO ()+> whatsYourNameLabel = evalContT $ do+> (beginning, attempts) <- label (0 :: Int)+> liftIO $ putStrLn $ "Attempt #" <> show attempts+> liftIO $ putStrLn $ "What's your name?"+> name <- liftIO getLine+> when (null name) $ beginning (attempts + 1)+> liftIO $ putStrLn $ "Welcome, " ++ name ++ "!"++Calling @beggining@ will interrupt execution of the block, skipping the welcome message, which will be printed only once at the very end of the loop. -}
Control/Monad/Cont/Class.hs view
@@ -1,4 +1,7 @@+{-# LANGUAGE RankNTypes #-} {-# LANGUAGE Safe #-}+{-# LANGUAGE PolyKinds #-}+{-# LANGUAGE QuantifiedConstraints #-} -- Needed because the CPSed versions of Writer and State are secretly State -- wrappers, which don't force such constraints, even though they should legally -- be there.@@ -56,8 +59,13 @@ module Control.Monad.Cont.Class ( MonadCont(..),+ label,+ label_,+ liftCallCC, ) where +import Data.Kind (Type)+import Control.Monad.Fix (fix) import Control.Monad.Trans.Cont (ContT) import qualified Control.Monad.Trans.Cont as ContT import Control.Monad.Trans.Except (ExceptT)@@ -78,8 +86,11 @@ import qualified Control.Monad.Trans.Accum as Accum import qualified Control.Monad.Trans.RWS.CPS as CPSRWS import qualified Control.Monad.Trans.Writer.CPS as CPSWriter+import Control.Monad.Trans.Class (MonadTrans (lift))+import Control.Monad.Signatures (CallCC)+import Control.Monad (join) -class Monad m => MonadCont m where+class Monad m => MonadCont (m :: Type -> Type) where {- | @callCC@ (call-with-current-continuation) calls a function with the current continuation as its argument. Provides an escape continuation mechanism for use with Continuation monads.@@ -101,13 +112,14 @@ callCC :: ((a -> m b) -> m a) -> m a {-# MINIMAL callCC #-} -instance MonadCont (ContT r m) where+-- | @since 2.3.1+instance forall k (r :: k) (m :: (k -> Type)) . MonadCont (ContT r m) where callCC = ContT.callCC -- --------------------------------------------------------------------------- -- Instances for other mtl transformers -{- | @since 2.2 -}+-- | @since 2.2 instance MonadCont m => MonadCont (ExceptT e m) where callCC = Except.liftCallCC callCC @@ -152,3 +164,45 @@ , MonadCont m ) => MonadCont (AccumT w m) where callCC = Accum.liftCallCC callCC++-- | Introduces a recursive binding to the continuation.+-- Due to the use of @callCC@, calling the continuation will interrupt execution+-- of the current block creating an effect similar to goto/setjmp in C.+--+-- @since 2.3.1+--+label :: MonadCont m => a -> m (a -> m b, a)+label a = callCC $ \k -> let go b = k (go, b) in return (go, a)++-- | Simplified version of `label` without arguments.+-- +-- @since 2.3.1+--+label_ :: MonadCont m => m (m a)+label_ = callCC $ return . fix++-- | Lift a 'ContT.callCC'-style function through any 'MonadTrans'. +--+-- = Note+--+-- For any function @f@, @'liftCallCC f'@ satisfies the [uniformity+-- condition](https://hackage.haskell.org/package/transformers-0.5.6.2/docs/Control-Monad-Signatures.html#t:CallCC)+-- provided that @f@ is quasi-algebraic. More specifically, for any @g@, we must have:+--+-- > 'join' '$' f (\exit -> 'pure' '$' g (exit '.' 'pure') = f g+--+-- 'ContT.callCC' is quasi-algebraic; furthermore, for any quasi-algebraic @f@,+-- @'liftCallCC' f@ is also quasi-algebraic. +--+-- = See also+--+-- * [Proof of quasi-algebraic+-- properties](https://gist.github.com/KingoftheHomeless/5927257cc7f6f8a2da685a2045dac204)+-- * [Original issue](https://github.com/haskell/mtl/issues/77)+--+-- @since 2.3.1+liftCallCC :: + forall (t :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) (a :: Type) (b :: Type) . + (MonadTrans t, Monad m, forall (m' :: Type -> Type) . Monad m' => Monad (t m')) => + CallCC m (t m a) b -> CallCC (t m) a b+liftCallCC f g = join . lift . f $ \exit -> pure $ g (lift . exit . pure)
Control/Monad/Error/Class.hs view
@@ -49,10 +49,11 @@ withError, handleError, mapError,+ modifyError, ) where import Control.Monad.Trans.Except (ExceptT)-import qualified Control.Monad.Trans.Except as ExceptT (throwE, catchE)+import qualified Control.Monad.Trans.Except as ExceptT (catchE, runExceptT, throwE) import Control.Monad.Trans.Identity (IdentityT) import qualified Control.Monad.Trans.Identity as Identity import Control.Monad.Trans.Maybe (MaybeT)@@ -211,7 +212,7 @@ -- | 'MonadError' analogue to the 'withExceptT' function. -- Modify the value (but not the type) of an error. The type is -- fixed because of the functional dependency @m -> e@. If you need--- to change the type of @e@ use 'mapError'.+-- to change the type of @e@ use 'mapError' or 'modifyError'. withError :: MonadError e m => (e -> e) -> m a -> m a withError f action = tryError action >>= either (throwError . f) pure @@ -225,3 +226,44 @@ -- the result is lifted into the second 'MonadError' instance. mapError :: (MonadError e m, MonadError e' n) => (m (Either e a) -> n (Either e' b)) -> m a -> n b mapError f action = f (tryError action) >>= liftEither++{- |+A different 'MonadError' analogue to the 'withExceptT' function.+Modify the value (and possibly the type) of an error in an @ExceptT@-transformed+monad, while stripping the @ExceptT@ layer.++This is useful for adapting the 'MonadError' constraint of a computation.++For example:++> data DatabaseError = ...+>+> performDatabaseQuery :: (MonadError DatabaseError m, ...) => m PersistedValue+>+> data AppError+> = MkDatabaseError DatabaseError+> | ...+>+> app :: (MonadError AppError m, ...) => m ()++Given these types, @performDatabaseQuery@ cannot be used directly inside+@app@, because the error types don't match. Using 'modifyError', an equivalent+function with a different error type can be constructed:++> performDatabaseQuery' :: (MonadError AppError m, ...) => m PersistedValue+> performDatabaseQuery' = modifyError MkDatabaseError performDatabaseQuery++Since the error types do match, @performDatabaseQuery'@ _can_ be used in @app@,+assuming all other constraints carry over.++This works by instantiating the @m@ in the type of @performDatabaseQuery@ to+@ExceptT DatabaseError m'@, which satisfies the @MonadError DatabaseError@+constraint. Immediately, the @ExceptT DatabaseError@ layer is unwrapped,+producing 'Either' a @DatabaseError@ or a @PersistedValue@. If it's the former,+the error is wrapped in @MkDatabaseError@ and re-thrown in the inner monad,+otherwise the result value is returned.++@since 2.3.1+-}+modifyError :: MonadError e' m => (e -> e') -> ExceptT e m a -> m a+modifyError f m = ExceptT.runExceptT m >>= either (throwError . f) pure
Control/Monad/Except.hs view
@@ -42,6 +42,16 @@ Error.withError, Error.handleError, Error.mapError,+ Error.modifyError,+ -- * The ExceptT monad transformer+ Except.ExceptT(ExceptT),+ Except.Except,+ Except.runExceptT,+ Except.mapExceptT,+ Except.withExceptT,+ Except.runExcept,+ Except.mapExcept,+ Except.withExcept, -- * Example 1: Custom Error Data Type -- $customErrorExample @@ -50,6 +60,7 @@ ) where import qualified Control.Monad.Error.Class as Error+import qualified Control.Monad.Trans.Except as Except {- $warning Please do not confuse 'ExceptT' and 'throwError' with 'Control.Exception.Exception' /
Control/Monad/Writer/Class.hs view
@@ -198,9 +198,9 @@ -- -- @since 2.3 instance- ( Monoid w+ ( Monoid w' , MonadWriter w m- ) => MonadWriter w (AccumT w m) where+ ) => MonadWriter w (AccumT w' m) where writer = lift . writer tell = lift . tell listen = Accum.liftListen listen
README.markdown view
@@ -89,14 +89,6 @@ - Transformer: `Control.Monad.Trans.Identity.IdentityT` (in the `transformers` package) - Identity functor and monad: `Data.Functor.Identity.Identity` (in the `base` package) -* `Control.Monad.List`-- This transformer combines the list monad with another monad. _Note- that this does not yield a monad unless the inner monad is- [commutative](https://en.wikipedia.org/wiki/Commutative_property)._-- - Transformer: `Control.Monad.List.ListT`- * `Control.Monad.RWS` A convenient transformer that combines the Reader, Writer, and@@ -136,6 +128,29 @@ - Class: `Control.Monad.Writer.Class.MonadWriter` - Lazy transformers: `Control.Monad.Writer.Lazy.WriterT` - Strict transformers: `Control.Monad.Writer.Strict.WriterT`++* `Control.Monad.Accum`++ The `Accum` monad transformer represents a computation which+ manages append-only state, or a writer that can read all+ previous inputs. It binds a function to a monadic value by+ lazily accumulating subcomputations via `(<>)`. For more general+ access, use [State](https://hackage.haskell.org/package/transformers-0.6.0.4/docs/Control-Monad-Trans-State.html) instead.++ - Class: `Control.Monad.Accum`+ - Transformer: `Control.Monad.Trans.Accum.AccumT`++* `Control.Monad.Select`++ The `Select` monad transformer represents a computation which+ can do backtracking search using a 'ranked' evaluation strategy.+ Binding a function to a monad value chains together evaluation+ strategies in the sense that the results of previous strategies+ may influence subsequent rank and evaluation strategies in+ subcomputations.++ - Class: `Control.Monad.Select`+ - Transformer: `Control.Monad.Trans.Select.SelectT` ## Resources
mtl.cabal view
@@ -1,11 +1,11 @@ cabal-version: 3.0 name: mtl-version: 2.3+version: 2.3.1 license: BSD-3-Clause license-file: LICENSE author: Andy Gill-maintainer: chessai <chessai1996@gmail.com>, - Emily Pillmore <emilypi@cohomolo.gy>, +maintainer: chessai <chessai1996@gmail.com>,+ Emily Pillmore <emilypi@cohomolo.gy>, Koz Ross <koz.ross@retro-freedom.nz> category: Control synopsis: Monad classes for transformers, using functional dependencies@@ -18,11 +18,11 @@ build-type: Simple -extra-source-files: +extra-source-files: CHANGELOG.markdown README.markdown -tested-with: GHC ==8.6.5 || ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.2+tested-with: GHC ==8.6.5 || ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.4 || ==9.4.1 source-repository head type: git@@ -54,15 +54,14 @@ Control.Monad.Writer.Strict Control.Monad.Accum Control.Monad.Select- - build-depends: ++ build-depends: , base >=4.12 && < 5 , transformers >= 0.5.6 && <0.7 - ghc-options: + ghc-options: -Wall -Wcompat -Wincomplete-record-updates -Wincomplete-uni-patterns -Wredundant-constraints -Wmissing-export-lists default-language: Haskell2010-