Lift a computation from the argument monad to the constructed monad.

Lift a computation from the base monad

liftWith is similar to lift in that it lifts a computation from the argument monad to the constructed monad.

Instances should satisfy similar laws as the MonadTrans laws:

liftWith . const . return = return

liftWith (const (m >>= f)) = liftWith (const m) >>= liftWith . const . f

The difference with lift is that before lifting the m computation liftWith captures the state of t. It then provides the m computation with a Run function that allows running t n computations in n (for all n) on the captured state, e.g.

withFileLifted :: (Monad (t IO), MonadTransControl t) => FilePath -> IOMode -> (Handle -> t IO r) -> t IO r
withFileLifted file mode action = liftWith (\run -> withFile file mode (run . action)) >>= restoreT . return

If the Run function is ignored, liftWith coincides with lift:

lift f = liftWith (const f)

Implementations use the Run function associated with a transformer:

liftWith :: Monad m => ((Monad n => ReaderT r n b -> n b) -> m a) -> ReaderT r m a
liftWith f = ReaderT (r -> f (action -> runReaderT action r))

liftWith :: Monad m => ((Monad n => StateT s n b -> n (b, s)) -> m a) -> StateT s m a
liftWith f = StateT (s -> liftM (x -> (x, s)) (f (action -> runStateT action s)))

liftWith :: Monad m => ((Monad n => MaybeT n b -> n (Maybe b)) -> m a) -> MaybeT m a
liftWith f = MaybeT (liftM Just (f runMaybeT))

Construct a t computation from the monadic state of t that is returned from a Run function.

Instances should satisfy:

liftWith (\run -> run t) >>= restoreT . return = t

restoreT is usually implemented through the constructor of the monad transformer:

ReaderT  :: (r -> m a) -> ReaderT r m a
restoreT ::       m a  -> ReaderT r m a
restoreT action = ReaderT { runReaderT = const action }

StateT   :: (s -> m (a, s)) -> StateT s m a
restoreT ::       m (a, s)  -> StateT s m a
restoreT action = StateT { runStateT = const action }

MaybeT   :: m (Maybe a) -> MaybeT m a
restoreT :: m (Maybe a) -> MaybeT m a
restoreT action = MaybeT action

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

liftBaseWith is similar to liftIO and liftBase in that it lifts a base computation to the constructed monad.

Instances should satisfy similar laws as the MonadIO and MonadBase laws:

liftBaseWith . const . return = return

liftBaseWith (const (m >>= f)) = liftBaseWith (const m) >>= liftBaseWith . const . f

The difference with liftBase is that before lifting the base computation liftBaseWith captures the state of m. It then provides the base computation with a RunInBase function that allows running m computations in the base monad on the captured state:

withFileLifted :: MonadBaseControl IO m => FilePath -> IOMode -> (Handle -> m a) -> m a
withFileLifted file mode action = liftBaseWith (\runInBase -> withFile file mode (runInBase . action)) >>= restoreM
                             -- = control $ \runInBase -> withFile file mode (runInBase . action)
                             -- = liftBaseOp (withFile file mode) action

liftBaseWith is usually not implemented directly, but using defaultLiftBaseWith.

Construct a m computation from the monadic state of m that is returned from a RunInBase function.

Instances should satisfy:

liftBaseWith (\runInBase -> runInBase m) >>= restoreM = m

restoreM is usually not implemented directly, but using defaultRestoreM.