monad-control 1.0.1.0 → 1.0.2.0

raw patch · 2 files changed

+132/−1 lines, 2 filesPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

Files

• Control/Monad/Trans/Control.hs +131/−0
• monad-control.cabal +1/−1

@@ -32,6 +32,8 @@       -- ** Defaults       -- $MonadTransControlDefaults     , RunDefault, defaultLiftWith, defaultRestoreT+      -- $MonadTransControlDefaults2+    , RunDefault2, defaultLiftWith2, defaultRestoreT2        -- * MonadBaseControl     , MonadBaseControl (..), RunInBase@@ -109,6 +111,21 @@  class MonadTrans t => MonadTransControl t where   -- | Monadic state of @t@.+  --+  -- For clarity, because haddock does not display associated types, below are+  -- the elaborated 'StT' definitions provided by this library:+  --+  -- @+  -- StT 'IdentityT'    a ~ a+  -- StT 'MaybeT'       a ~ 'Maybe' a+  -- StT ('ErrorT' e)   a ~ 'Error' e => 'Either' e a+  -- StT ('ExceptT' e)  a ~ 'Either' e a+  -- StT 'ListT'        a ~ [a]+  -- StT ('ReaderT' r)  a ~ a+  -- StT ('StateT' s)   a ~ (a, s)+  -- StT ('WriterT' w)  a ~ 'Monoid' w => (a, w)+  -- StT ('RWST' r w s) a ~ 'Monoid' w => (a, s, w)+  -- @   type StT t a :: *    -- | @liftWith@ is similar to 'lift' in that it lifts a computation from@@ -132,6 +149,20 @@   -- Instances should satisfy:   --   -- @liftWith (\\run -> run t) >>= restoreT . return = t@+  --+  -- Example type signatures:+  --+  -- @+  -- restoreT :: 'Monad' m             => m a            -> 'IdentityT' m a+  -- restoreT :: 'Monad' m             => m ('Maybe' a)    -> 'MaybeT' m a+  -- restoreT :: ('Monad' m, 'Error' e)  => m ('Either' e a) -> 'ErrorT' e m a+  -- restoreT :: 'Monad' m             => m ('Either' e a) -> 'ExceptT' e m a+  -- restoreT :: 'Monad' m             => m [a]          -> 'ListT' m a+  -- restoreT :: 'Monad' m             => m a            -> 'ReaderT' r m a+  -- restoreT :: 'Monad' m             => m (a, s)       -> 'StateT' s m a+  -- restoreT :: ('Monad' m, 'Monoid' w) => m (a, w)       -> 'WriterT' w m a+  -- restoreT :: ('Monad' m, 'Monoid' w) => m (a, s, w)    -> 'RWST' r w s m a+  -- @   restoreT :: Monad m => m (StT t a) -> t m a  -- | A function that runs a transformed monad @t n@ on the monadic state that@@ -140,6 +171,20 @@ -- A @Run t@ function yields a computation in @n@ that returns the monadic state -- of @t@. This state can later be used to restore a @t@ computation using -- 'restoreT'.+--+-- Example type equalities:+--+-- @+-- Run 'IdentityT'    ~ forall n b. 'Monad' n             => 'IdentityT'  n b -> n b+-- Run 'MaybeT'       ~ forall n b. 'Monad' n             => 'MaybeT'     n b -> n ('Maybe' b)+-- Run ('ErrorT' e)   ~ forall n b. ('Monad' n, 'Error' e)  => 'ErrorT' e   n b -> n ('Either' e b)+-- Run ('ExceptT' e)  ~ forall n b. 'Monad' n             => 'ExceptT' e  n b -> n ('Either' e b)+-- Run 'ListT'        ~ forall n b. 'Monad' n             => 'ListT'      n b -> n [b]+-- Run ('ReaderT' r)  ~ forall n b. 'Monad' n             => 'ReaderT' r  n b -> n b+-- Run ('StateT' s)   ~ forall n b. 'Monad' n             => 'StateT' s   n b -> n (a, s)+-- Run ('WriterT' w)  ~ forall n b. ('Monad' n, 'Monoid' w) => 'WriterT' w  n b -> n (a, w)+-- Run ('RWST' r w s) ~ forall n b. ('Monad' n, 'Monoid' w) => 'RWST' r w s n b -> n (a, s, w)+-- @ type Run t = forall n b. Monad n => t n b -> n (StT t b)  @@ -155,6 +200,8 @@ -- -- @ -- {-\# LANGUAGE GeneralizedNewtypeDeriving \#-}+-- {-\# LANGUAGE UndecidableInstances \#-}+-- {-\# LANGUAGE TypeFamilies \#-} -- -- newtype CounterT m a = CounterT {unCounterT :: StateT Int m a} --   deriving (Monad, MonadTrans)@@ -186,7 +233,48 @@ defaultRestoreT t = t . restoreT {-# INLINABLE defaultRestoreT #-} +-------------------------------------------------------------------------------+--+------------------------------------------------------------------------------- +-- $MonadTransControlDefaults2+--+-- The following functions can be used to define a 'MonadTransControl' instance+-- for a monad transformer stack of two.+--+-- @+-- {-\# LANGUAGE GeneralizedNewtypeDeriving \#-}+--+-- newtype CalcT m a = CalcT { unCalcT :: StateT Int (ExceptT String m) a }+--   deriving (Monad, MonadTrans)+--+-- instance MonadTransControl CalcT where+--     type StT CalcT a = StT (ExceptT String) (StT (StateT Int) a)+--     liftWith = 'defaultLiftWith2' CalcT unCalcT+--     restoreT = 'defaultRestoreT2' CalcT+-- @++-- | A function like 'Run' that runs a monad transformer @t@ which wraps the+-- monad transformers @n@ and @n'@. This is used in 'defaultLiftWith2'.+type RunDefault2 t n n' = forall m b. (Monad m, Monad (n' m)) => t m b -> m (StT n' (StT n b))++-- | Default definition for the 'liftWith' method.+defaultLiftWith2 :: (Monad m, Monad (n' m), MonadTransControl n, MonadTransControl n')+                 => (forall b.   n (n' m) b -> t m b)     -- ^ Monad constructor+                 -> (forall o b. t o b -> n (n' o) b)     -- ^ Monad deconstructor+                 -> (RunDefault2 t n n' -> m a)+                 -> t m a+defaultLiftWith2 t unT = \f -> t $ liftWith $ \run -> liftWith $ \run' -> f $ run' . run . unT+{-# INLINABLE defaultLiftWith2 #-}++-- | Default definition for the 'restoreT' method for double 'MonadTransControl'.+defaultRestoreT2 :: (Monad m, Monad (n' m), MonadTransControl n, MonadTransControl n')+                 => (n (n' m) a -> t m a)     -- ^ Monad constructor+                 -> m (StT n' (StT n a))+                 -> t m a+defaultRestoreT2 t = t . restoreT . restoreT+{-# INLINABLE defaultRestoreT2 #-}+ -------------------------------------------------------------------------------- -- MonadTransControl instances --------------------------------------------------------------------------------@@ -291,6 +379,35 @@  class MonadBase b m => MonadBaseControl b m | m -> b where     -- | Monadic state of @m@.+    --+    -- For all non-transformer monads, @StM m a ~ a@:+    --+    -- @+    -- StM 'IO'         a ~ a+    -- StM 'Maybe'      a ~ a+    -- StM ('Either' e) a ~ a+    -- StM []         a ~ a+    -- StM ((->) r)   a ~ a+    -- StM 'Identity'   a ~ a+    -- StM 'STM'        a ~ a+    -- StM ('ST' s)     a ~ a+    -- @+    --+    -- All transformer monads\' 'StM' depends on both the monadic state of the+    -- transformer (given by its 'StT' from 'MonadTransControl'), as well as its+    -- inner monad's monadic state, given by its 'StM' from 'MonadBaseControl':+    --+    -- @+    -- StM ('IdentityT'  m) a ~ StM m a+    -- StM ('MaybeT'     m) a ~ StM m ('Maybe' a)+    -- StM ('ErrorT' e   m) a ~ 'Error' e => StM m ('Either' e a)+    -- StM ('ExceptT' e  m) a ~ StM m ('Either' e a)+    -- StM ('ListT'      m) a ~ StM m [a]+    -- StM ('ReaderT' r  m) a ~ StM m a+    -- StM ('StateT' s   m) a ~ StM m (a, s)+    -- StM ('WriterT' w  m) a ~ 'Monoid' w => StM m (a, w)+    -- StM ('RWST' r w s m) a ~ 'Monoid' w => StM m (a, s, w)+    -- @     type StM m a :: *      -- | @liftBaseWith@ is similar to 'liftIO' and 'liftBase' in that it@@ -322,6 +439,20 @@ -- A @RunInBase m@ function yields a computation in the base monad of @m@ that -- returns the monadic state of @m@. This state can later be used to restore the -- @m@ computation using 'restoreM'.+--+-- Example type equalities:+--+-- @+-- RunInBase ('IdentityT'  m) b ~ forall a.             'IdentityT'  m a -> b ('StM' m a)+-- RunInBase ('MaybeT'     m) b ~ forall a.             'MaybeT'     m a -> b ('StM' m ('Maybe' a))+-- RunInBase ('ErrorT' e   m) b ~ forall a. 'Error' e =>  'ErrorT' e   m a -> b ('StM' m ('Either' e a))+-- RunInBase ('ExceptT' e  m) b ~ forall a.             'ExceptT' e  m a -> b ('StM' m ('Either' e a))+-- RunInBase ('ListT'      m) b ~ forall a.             'ListT'      m a -> b ('StM' m [a])+-- RunInBase ('ReaderT' r  m) b ~ forall a.             'ReaderT'    m a -> b ('StM' m a)+-- RunInBase ('StateT' s   m) b ~ forall a.             'StateT' s   m a -> b ('StM' m (a, s))+-- RunInBase ('WriterT' w  m) b ~ forall a. 'Monoid' w => 'WriterT' w  m a -> b ('StM' m (a, w))+-- RunInBase ('RWST' r w s m) b ~ forall a. 'Monoid' w => 'RWST' r w s m a -> b ('StM' m (a, s, w))+-- @ type RunInBase m b = forall a. m a -> b (StM m a)  

@@ -1,5 +1,5 @@ Name:                monad-control-Version:             1.0.1.0+Version:             1.0.2.0 Synopsis:            Lift control operations, like exception catching, through monad transformers License:             BSD3 License-file:        LICENSE