Control.Monad.Trans.MSF.Except

MSFs in the ExceptT monad are monadic stream functions that can throw exceptions, i.e. return an exception value instead of a continuation. This module gives ways to throw exceptions in various ways, and to handle them through a monadic interface.

Documentation

newtype MSFExcept m a b e

MSFs with an ExceptT transformer layer are in fact monads /in the exception type/.

• return corresponds to throwing an exception immediately.
• >>= is exception handling: The first value throws an exception, while the Kleisli arrow handles the exception and produces a new signal function, which can throw exceptions in a different type.
• m: The monad that the MSF may take side effects in.
• a: The input type
• b: The output type
• e: The type of exceptions that can be thrown

Constructors

MSFExcept

Fields

• runMSFExcept :: MSF (ExceptT e m) a b

Instances

Monad m => Applicative (MSFExcept m a b)

Applicative instance for MSFs on the Either monad. The function pure throws an exception.

Defined in Control.Monad.Trans.MSF.Except

Methods

pure :: a0 -> MSFExcept m a b a0

(<*>) :: MSFExcept m a b (a0 -> b0) -> MSFExcept m a b a0 -> MSFExcept m a b b0

liftA2 :: (a0 -> b0 -> c) -> MSFExcept m a b a0 -> MSFExcept m a b b0 -> MSFExcept m a b c

(*>) :: MSFExcept m a b a0 -> MSFExcept m a b b0 -> MSFExcept m a b b0

(<*) :: MSFExcept m a b a0 -> MSFExcept m a b b0 -> MSFExcept m a b a0

Monad m => Functor (MSFExcept m a b)

Functor instance for MSFs on the Either monad. Fmapping is the same as applying a transformation to the Left values.

Defined in Control.Monad.Trans.MSF.Except

Methods

fmap :: (a0 -> b0) -> MSFExcept m a b a0 -> MSFExcept m a b b0

(<$) :: a0 -> MSFExcept m a b b0 -> MSFExcept m a b a0

Monad m => Monad (MSFExcept m a b)

Monad instance for MSFExcept. Bind uses the exception as the return value in the monad.

Defined in Control.Monad.Trans.MSF.Except

Methods

(>>=) :: MSFExcept m a b a0 -> (a0 -> MSFExcept m a b b0) -> MSFExcept m a b b0

(>>) :: MSFExcept m a b a0 -> MSFExcept m a b b0 -> MSFExcept m a b b0

return :: a0 -> MSFExcept m a b a0

throw :: Monad m => e -> MSF (ExceptT e m) a b

Immediately throw the given exception.

try :: MSF (ExceptT e m) a b -> MSFExcept m a b e

Execute an MSF in ExceptT until it raises an exception.

An alias for the MSFExcept constructor, used to enter the MSFExcept monad context.

step :: Monad m => (a -> m (b, e)) -> MSFExcept m a b e

Advances a single tick with the given Kleisli arrow, and then throws an exception.

pass :: Monad m => MSF (ExceptT e m) a a

Do not throw an exception.

safe :: Monad m => MSF m a b -> MSFExcept m a b e

An MSF without an ExceptT layer never throws an exception, and can thus have an arbitrary exception type.

throwOnCond :: Monad m => (a -> Bool) -> e -> MSF (ExceptT e m) a a

Throw the exception e whenever the function evaluates to True.

maybeToExceptS :: (Functor m, Monad m) => MSF (MaybeT m) a b -> MSF (ExceptT () m) a b

Converts an MSF in MaybeT to an MSF in ExceptT. Whenever Nothing is thrown, throw () instead.

exceptS :: (Functor m, Monad m) => MSF (ExceptT e m) a b -> MSF m a (Either e b)

Escape an ExceptT layer by outputting the exception whenever it occurs. If an exception occurs, the current MSF continuation is tested again on the next input.

listToMSFExcept :: Monad m => [b] -> MSFExcept m a b ()

Converts a list to an MSFExcept, which outputs an element of the list at each step, throwing () when the list ends.

reactimateExcept :: Monad m => MSFExcept m () () e -> m e

Reactimates an MSFExcept until it throws an exception.

safely :: Monad m => MSFExcept m a b Void -> MSF m a b

If no exception can occur, the MSF can be executed without the ExceptT layer.

reactimateB :: Monad m => MSF m () Bool -> m ()

Reactimates an MSF until it returns True.

throwS :: Monad m => MSF (ExceptT e m) e a

Immediately throw the incoming exception.

throwOnCondM :: Monad m => (a -> m Bool) -> e -> MSF (ExceptT e m) a a

Throws the exception when the input is True. Variant of throwOnCond for Kleisli arrows.

throwOn :: Monad m => e -> MSF (ExceptT e m) Bool ()

Throw the exception when the input is True.

throwOn' :: Monad m => MSF (ExceptT e m) (Bool, e) ()

Variant of throwOn, where the exception may change every tick.

throwMaybe :: Monad m => MSF (ExceptT e m) (Maybe e) (Maybe a)

When the input is Just e, throw the exception e. (Does not output any actual data.)

catchS :: Monad m => MSF (ExceptT e m) a b -> (e -> MSF m a b) -> MSF m a b

Catch an exception in an MSF. As soon as an exception occurs, the current continuation is replaced by a new MSF, the exception handler, based on the exception value. For exception catching where the handler can throw further exceptions, see MSFExcept further below.

untilE :: Monad m => MSF m a b -> MSF m b (Maybe e) -> MSF (ExceptT e m) a b

Similar to Yampa's delayed switching. Loses a b in case of an exception.

inExceptT :: Monad m => MSF (ExceptT e m) (ExceptT e m a) a

Embed an ExceptT value inside the MSF. Whenever the input value is an ordinary value, it is passed on. If it is an exception, it is raised.

transG :: (Monad m1, Monad m2) => (a2 -> m1 a1) -> (forall c. a2 -> m1 (b1, c) -> m2 (b2, Maybe c)) -> MSF m1 a1 b1 -> MSF m2 a2 b2

More general lifting combinator that enables recovery. Note that, unlike a polymorphic lifting function forall a . m a -> m1 a, this auxiliary function needs to be a bit more structured, and produces a Maybe value. The previous MSF is used if a new one is not produced.

tagged :: Monad m => MSF (ExceptT e1 m) a b -> MSF (ExceptT e2 m) (a, e2) b

In case an exception occurs in the first argument, replace the exception by the second component of the tuple.

currentInput :: Monad m => MSFExcept m e b e

Immediately throw the current input as an exception.

handleExceptT :: Monad m => MSF (ExceptT e1 m) a b -> (e1 -> MSF (ExceptT e2 m) a b) -> MSF (ExceptT e2 m) a b

Execute an MSF and, if it throws an exception, recover by switching to a second MSF.

handleGen :: (a -> m1 (b1, MSF m1 a b1) -> m2 (b2, MSF m2 a b2)) -> MSF m1 a b1 -> MSF m2 a b2

Use a generic handler to handle exceptions in MSF processing actions.

once :: Monad m => (a -> m e) -> MSFExcept m a b e

Inside the MSFExcept monad, execute an action of the wrapped monad. This passes the last input value to the action, but doesn't advance a tick.

once_ :: Monad m => m e -> MSFExcept m a b e

Variant of once without input.

step_ :: Monad m => b -> MSFExcept m a b ()

Advances a single tick outputting the value, and then throws ().

performOnFirstSample :: Monad m => m (MSF m a b) -> MSF m a b

Extract an MSF from a monadic action.

Runs a monadic action that produces an MSF on the first iteration/step, and uses that MSF as the main signal function for all inputs (including the first one).

switch :: Monad m => MSF m a (b, Maybe c) -> (c -> MSF m a b) -> MSF m a b

Run first MSF until the second value in the output tuple is Just c (for some c), then start the second MSF.

Analog to Yampa's switch, with Maybe instead of Event.

dSwitch :: Monad m => MSF m a (b, Maybe c) -> (c -> MSF m a b) -> MSF m a b

Run first MSF until the second value in the output tuple is Just c (for some c), then start the second MSF.

Analog to Yampa's dswitch, with Maybe instead of Event.

type Except e = ExceptT e Identity

The parameterizable exception monad.

Computations are either exceptions or normal values.

The return function returns a normal value, while >>= exits on the first exception. For a variant that continues after an error and collects all the errors, see Errors.

newtype ExceptT e (m :: Type -> Type) a

A monad transformer that adds exceptions to other monads.

ExceptT constructs a monad parameterized over two things:

• e - The exception type.
• m - The inner monad.

The return function yields a computation that produces the given value, while >>= sequences two subcomputations, exiting on the first exception.

Constructors

ExceptT (m (Either e a))

Instances

MonadSplit g m => MonadSplit g (ExceptT e m)

Defined in Control.Monad.Random.Class

Methods

getSplit :: ExceptT e m g

Functor m => Generic1 (ExceptT e m :: Type -> Type)

Defined in Control.Monad.Trans.Except

Associated Types

type Rep1 (ExceptT e m) :: k -> Type

Methods

from1 :: forall (a :: k). ExceptT e m a -> Rep1 (ExceptT e m) a

to1 :: forall (a :: k). Rep1 (ExceptT e m) a -> ExceptT e m a

MonadBase b m => MonadBase b (ExceptT e m)

Defined in Control.Monad.Base

Methods

liftBase :: b α -> ExceptT e m α

MonadTrans (ExceptT e)

Defined in Control.Monad.Trans.Except

Methods

lift :: Monad m => m a -> ExceptT e m a

MonadInterleave m => MonadInterleave (ExceptT e m)

Defined in Control.Monad.Random.Class

Methods

interleave :: ExceptT e m a -> ExceptT e m a

MonadRandom m => MonadRandom (ExceptT e m)

Defined in Control.Monad.Random.Class

Methods

getRandomR :: Random a => (a, a) -> ExceptT e m a

getRandom :: Random a => ExceptT e m a

getRandomRs :: Random a => (a, a) -> ExceptT e m [a]

getRandoms :: Random a => ExceptT e m [a]

MonadFail m => MonadFail (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

fail :: String -> ExceptT e m a

MonadFix m => MonadFix (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

mfix :: (a -> ExceptT e m a) -> ExceptT e m a

MonadIO m => MonadIO (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

liftIO :: IO a -> ExceptT e m a

MonadZip m => MonadZip (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

mzip :: ExceptT e m a -> ExceptT e m b -> ExceptT e m (a, b)

mzipWith :: (a -> b -> c) -> ExceptT e m a -> ExceptT e m b -> ExceptT e m c

munzip :: ExceptT e m (a, b) -> (ExceptT e m a, ExceptT e m b)

Foldable f => Foldable (ExceptT e f)

Defined in Control.Monad.Trans.Except

Methods

fold :: Monoid m => ExceptT e f m -> m

foldMap :: Monoid m => (a -> m) -> ExceptT e f a -> m

foldMap' :: Monoid m => (a -> m) -> ExceptT e f a -> m

foldr :: (a -> b -> b) -> b -> ExceptT e f a -> b

foldr' :: (a -> b -> b) -> b -> ExceptT e f a -> b

foldl :: (b -> a -> b) -> b -> ExceptT e f a -> b

foldl' :: (b -> a -> b) -> b -> ExceptT e f a -> b

foldr1 :: (a -> a -> a) -> ExceptT e f a -> a

foldl1 :: (a -> a -> a) -> ExceptT e f a -> a

toList :: ExceptT e f a -> [a]

null :: ExceptT e f a -> Bool

length :: ExceptT e f a -> Int

elem :: Eq a => a -> ExceptT e f a -> Bool

maximum :: Ord a => ExceptT e f a -> a

minimum :: Ord a => ExceptT e f a -> a

sum :: Num a => ExceptT e f a -> a

product :: Num a => ExceptT e f a -> a

(Eq e, Eq1 m) => Eq1 (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

liftEq :: (a -> b -> Bool) -> ExceptT e m a -> ExceptT e m b -> Bool

(Ord e, Ord1 m) => Ord1 (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

liftCompare :: (a -> b -> Ordering) -> ExceptT e m a -> ExceptT e m b -> Ordering

(Read e, Read1 m) => Read1 (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (ExceptT e m a)

liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [ExceptT e m a]

liftReadPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec (ExceptT e m a)

liftReadListPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec [ExceptT e m a]

(Show e, Show1 m) => Show1 (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

liftShowsPrec :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> ExceptT e m a -> ShowS

liftShowList :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> [ExceptT e m a] -> ShowS

Contravariant m => Contravariant (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

contramap :: (a' -> a) -> ExceptT e m a -> ExceptT e m a'

(>$) :: b -> ExceptT e m b -> ExceptT e m a

Traversable f => Traversable (ExceptT e f)

Defined in Control.Monad.Trans.Except

Methods

traverse :: Applicative f0 => (a -> f0 b) -> ExceptT e f a -> f0 (ExceptT e f b)

sequenceA :: Applicative f0 => ExceptT e f (f0 a) -> f0 (ExceptT e f a)

mapM :: Monad m => (a -> m b) -> ExceptT e f a -> m (ExceptT e f b)

sequence :: Monad m => ExceptT e f (m a) -> m (ExceptT e f a)

(Functor m, Monad m, Monoid e) => Alternative (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

empty :: ExceptT e m a

(<|>) :: ExceptT e m a -> ExceptT e m a -> ExceptT e m a

some :: ExceptT e m a -> ExceptT e m [a]

many :: ExceptT e m a -> ExceptT e m [a]

(Functor m, Monad m) => Applicative (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

pure :: a -> ExceptT e m a

(<*>) :: ExceptT e m (a -> b) -> ExceptT e m a -> ExceptT e m b

liftA2 :: (a -> b -> c) -> ExceptT e m a -> ExceptT e m b -> ExceptT e m c

(*>) :: ExceptT e m a -> ExceptT e m b -> ExceptT e m b

(<*) :: ExceptT e m a -> ExceptT e m b -> ExceptT e m a

Functor m => Functor (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

fmap :: (a -> b) -> ExceptT e m a -> ExceptT e m b

(<$) :: a -> ExceptT e m b -> ExceptT e m a

Monad m => Monad (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

(>>=) :: ExceptT e m a -> (a -> ExceptT e m b) -> ExceptT e m b

(>>) :: ExceptT e m a -> ExceptT e m b -> ExceptT e m b

return :: a -> ExceptT e m a

(Monad m, Monoid e) => MonadPlus (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

mzero :: ExceptT e m a

mplus :: ExceptT e m a -> ExceptT e m a -> ExceptT e m a

Generic (ExceptT e m a)

Defined in Control.Monad.Trans.Except

Associated Types

type Rep (ExceptT e m a) :: Type -> Type

Methods

from :: ExceptT e m a -> Rep (ExceptT e m a) x

to :: Rep (ExceptT e m a) x -> ExceptT e m a

(Read e, Read1 m, Read a) => Read (ExceptT e m a)

Defined in Control.Monad.Trans.Except

Methods

readsPrec :: Int -> ReadS (ExceptT e m a)

readList :: ReadS [ExceptT e m a]

readPrec :: ReadPrec (ExceptT e m a)

readListPrec :: ReadPrec [ExceptT e m a]

(Show e, Show1 m, Show a) => Show (ExceptT e m a)

Defined in Control.Monad.Trans.Except

Methods

showsPrec :: Int -> ExceptT e m a -> ShowS

show :: ExceptT e m a -> String

showList :: [ExceptT e m a] -> ShowS

(Eq e, Eq1 m, Eq a) => Eq (ExceptT e m a)

Defined in Control.Monad.Trans.Except

Methods

(==) :: ExceptT e m a -> ExceptT e m a -> Bool

(/=) :: ExceptT e m a -> ExceptT e m a -> Bool

(Ord e, Ord1 m, Ord a) => Ord (ExceptT e m a)

Defined in Control.Monad.Trans.Except

Methods

compare :: ExceptT e m a -> ExceptT e m a -> Ordering

(<) :: ExceptT e m a -> ExceptT e m a -> Bool

(<=) :: ExceptT e m a -> ExceptT e m a -> Bool

(>) :: ExceptT e m a -> ExceptT e m a -> Bool

(>=) :: ExceptT e m a -> ExceptT e m a -> Bool

max :: ExceptT e m a -> ExceptT e m a -> ExceptT e m a

min :: ExceptT e m a -> ExceptT e m a -> ExceptT e m a

type Rep1 (ExceptT e m :: Type -> Type)

Defined in Control.Monad.Trans.Except

type Rep1 (ExceptT e m :: Type -> Type) = D1 ('MetaData "ExceptT" "Control.Monad.Trans.Except" "transformers-0.6.1.0" 'True) (C1 ('MetaCons "ExceptT" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (m :.: Rec1 (Either e))))

type Rep (ExceptT e m a)

Defined in Control.Monad.Trans.Except

type Rep (ExceptT e m a) = D1 ('MetaData "ExceptT" "Control.Monad.Trans.Except" "transformers-0.6.1.0" 'True) (C1 ('MetaCons "ExceptT" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (m (Either e a)))))

runExcept :: Except e a -> Either e a

Extractor for computations in the exception monad. (The inverse of except).

mapExcept :: (Either e a -> Either e' b) -> Except e a -> Except e' b

Map the unwrapped computation using the given function.

• runExcept (mapExcept f m) = f (runExcept m)

withExcept :: (e -> e') -> Except e a -> Except e' a

Transform any exceptions thrown by the computation using the given function (a specialization of withExceptT).

runExceptT :: ExceptT e m a -> m (Either e a)

The inverse of ExceptT.

mapExceptT :: (m (Either e a) -> n (Either e' b)) -> ExceptT e m a -> ExceptT e' n b

Map the unwrapped computation using the given function.

• runExceptT (mapExceptT f m) = f (runExceptT m)

withExceptT :: forall (m :: Type -> Type) e e' a. Functor m => (e -> e') -> ExceptT e m a -> ExceptT e' m a

Transform any exceptions thrown by the computation using the given function.

throwE :: forall (m :: Type -> Type) e a. Monad m => e -> ExceptT e m a

Signal an exception value e.

• runExceptT (throwE e) = return (Left e)

• throwE e >>= m = throwE e

catchE

Arguments

:: forall (m :: Type -> Type) e a e'. Monad m

=> ExceptT e m a

the inner computation

-> (e -> ExceptT e' m a)

a handler for exceptions in the inner computation

-> ExceptT e' m a

Handle an exception.

• catchE (lift m) h = lift m

• catchE (throwE e) h = h e

except :: forall (m :: Type -> Type) e a. Monad m => Either e a -> ExceptT e m a

Constructor for computations in the exception monad. (The inverse of runExcept).

handleE :: forall (m :: Type -> Type) e e' a. Monad m => (e -> ExceptT e' m a) -> ExceptT e m a -> ExceptT e' m a

The same as flip catchE, which is useful in situations where the code for the handler is shorter.

tryE :: forall (m :: Type -> Type) e a. Monad m => ExceptT e m a -> ExceptT e m (Either e a)

Similar to catchE, but returns an Either result which is (Right a) if no exception was thown, or (Left ex) if an exception ex was thrown.

finallyE :: forall (m :: Type -> Type) e a. Monad m => ExceptT e m a -> ExceptT e m () -> ExceptT e m a

finallyE a b executes computation a followed by computation b, even if a exits early by throwing an exception. In the latter case, the exception is re-thrown after b has been executed.