Control.Monad.Trans.Peel

This module defines the class MonadTransPeel of monad transformers through which control operations can be lifted. Instances are included for all the standard monad transformers from the transformers library except ContT.

idPeel and liftPeel are provided to assist creation of MonadPeelIO-like classes (see Control.Monad.IO.Peel) based on core monads other than IO.

liftOp and liftOp_ enable convenient lifting of two common special cases of control operation types.

Documentation

class MonadTrans t => MonadTransPeel t where

MonadTransPeel is the class of monad transformers supporting an extra operation peel, enabling control operations (functions that use monadic actions as input instead of just output) to be lifted through the transformer.

Methods

peel :: (Monad m, Monad n, Monad o) => t n (t m a -> m (t o a))

peel is used to peel off the outer layer of a transformed monadic action, allowing an transformed action t m a to be treated as a base action m b.

More precisely, peel captures the monadic state of t at the point where it is bound (in t n), yielding a function t m a -> m (t o a); this function runs a transformed monadic action t m a in the base monad m using the captured state, and leaves the result t o a in the monad m after all side effects in m have occurred.

This can be used together with lift to lift control operations with types such as M a -> M a into the transformed monad t M:

   instance Monad M
   foo :: M a -> M a
   foo' :: (MonadTransPeel t, Monad (t M)) => t M a -> t M a
   foo' a = do
     k <- peel  -- k :: t M a -> M (t M a)
     join $ lift $ foo (k a)  -- uses foo :: M (t M a) -> M (t M a)

peel is typically used with m == n == o, but is required to be polymorphic for greater type safety: for example, this type ensures that the result of running the action in m has no remaining side effects in m.

Instances

MonadTransPeel MaybeT

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => MaybeT n (MaybeT m a -> m (MaybeT o a))

MonadTransPeel (ExceptT e)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => ExceptT e n (ExceptT e m a -> m (ExceptT e o a))

MonadTransPeel (IdentityT :: (Type -> Type) -> Type -> Type)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => IdentityT n (IdentityT m a -> m (IdentityT o a))

MonadTransPeel (ReaderT r)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => ReaderT r n (ReaderT r m a -> m (ReaderT r o a))

MonadTransPeel (StateT s)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => StateT s n (StateT s m a -> m (StateT s o a))

MonadTransPeel (StateT s)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => StateT s n (StateT s m a -> m (StateT s o a))

Monoid w => MonadTransPeel (WriterT w)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => WriterT w n (WriterT w m a -> m (WriterT w o a))

Monoid w => MonadTransPeel (WriterT w)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => WriterT w n (WriterT w m a -> m (WriterT w o a))

Monoid w => MonadTransPeel (RWST r w s)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => RWST r w s n (RWST r w s m a -> m (RWST r w s o a))

Monoid w => MonadTransPeel (RWST r w s)

Defined in Control.Monad.Trans.Peel

Methods

peel :: forall m (n :: Type -> Type) (o :: Type -> Type) a. (Monad m, Monad n, Monad o) => RWST r w s n (RWST r w s m a -> m (RWST r w s o a))

idPeel :: (Monad m, Monad n, Monad o) => n (m a -> m (o a))

idPeel acts as the "identity" peel operation from a monad m to itself.

   idPeel = return $ liftM return

It serves as the base case for a class like MonadPeelIO, which allows control operations in some base monad (here IO) to be lifted through arbitrary stacks of zero or more monad transformers in one call. For example, Control.Monad.IO.Peel defines

   class MonadIO m => MonadPeelIO m where
     peelIO :: m (m a -> IO (m a))
   instance MonadPeelIO IO where
     peelIO = idPeel

liftPeel :: (MonadTransPeel t, Monad m, Monad m', Monad n', Monad (t n'), Monad o', Monad (t o')) => n' (m' (t o' a) -> m (o' (t o' a))) -> t n' (t m' a -> m (t o' a))

liftPeel is used to compose two peel operations: the outer provided by a MonadTransPeel instance, and the inner provided as the argument.

It satisfies liftPeel idPeel == peel.

It serves as the induction step of a MonadPeelIO-like class. For example, Control.Monad.IO.Peel defines

   instance MonadPeelIO m => MonadPeelIO (StateT s m) where
     peelIO = liftPeel peelIO

using the MonadTransPeel instance of StateT s.

liftOp :: (MonadTransPeel t, Monad m, Monad n, Monad o, Monad (t n)) => ((a -> m (t o b)) -> n (t n c)) -> (a -> t m b) -> t n c

liftOp is a particular application of peel that allows lifting control operations of type (a -> m b) -> m b to MonadTransPeel t => (a -> t m b) -> t m b.

   liftOp f g = do
     k <- peel
     join $ lift $ f (k . g)

liftOp_ :: (MonadTransPeel t, Monad m, Monad n, Monad o, Monad (t n)) => (m (t o a) -> n (t n b)) -> t m a -> t n b

liftOp_ is a particular application of peel that allows lifting control operations of type m a -> m a to MonadTransPeel m => t m a -> t m a.

It can be thought of as a generalization of mapReaderT, mapStateT, etc.

   liftOp_ f m = do
     k <- peel
     join $ lift $ f (k m)