Documentation

An Automaton that can terminate with an exception.

• m: The monad that the Automaton may take side effects in.
• a: The type of input values the stream constantly consumes.
• b: The type of output values the stream constantly produces.
• e: The type of exceptions with which the stream can terminate.

This type is useful because it is a monad in the exception type e.

• 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.

Consider this example: @ automaton :: AutomatonExcept a b m e1 f :: e1 -> AutomatonExcept a b m e2

example :: AutomatonExcept a b m e2 example = automaton >>= f @

Here, automaton produces output values of type b until an exception e1 occurs. The function f is called on the exception value and produces a continuation automaton which is then executed (until it possibly throws an exception e2 itself).

The generality of the monad interface comes at a cost, though. In order to achieve higher performance, you should use the Monad interface sparingly. Whenever you can express the same control flow using Functor, Applicative, Selective, or just the (>>) operator, you should do this. The encoding of the internal state type will be much more efficiently optimized.

The reason for this is that in an expression ma >>= f, the type of f is e1 -> AutomatonExcept a b m e2, which implies that the state of the AutomatonExcept produced isn't known at compile time, and thus GHC cannot optimize the automaton. But often the full expressiveness of >>= isn't necessary, and in these cases, a much faster automaton is produced by using Functor, Applicative and Selective.

Note: By "exceptions", we mean an ExceptT transformer layer, not IO exceptions.

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

Immediately throw the given exception.

Execute an Automaton in ExceptT until it raises an exception.

Typically used to enter the monad context of AutomatonExcept.

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

Do not throw an exception.

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

In particular, the exception type can be Void, so it can be used as the last statement in an AutomatonExcept do-block. See safely for an example.

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

Used to exit the AutomatonExcept context, often in combination with safe:

automaton = safely $ do
  e <- try someAutomaton
  once $ input -> putStrLn $ "Whoops, something happened when receiving input " ++ show input ++ ": " ++ show e ++ ", but I'll continue now."
  safe fallbackAutomaton

Throw the exception e whenever the function evaluates to True.

Converts an Automaton in MaybeT to an Automaton in ExceptT.

Whenever Nothing is thrown, throw () instead.

Escape an ExceptT layer by outputting the exception whenever it occurs.

If an exception occurs, the current state is is tested again on the next input.

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

reactimates an AutomatonExcept until it throws an exception.

Immediately throw the incoming exception.

This is useful to combine with ArrowChoice, e.g. with if and case expressions in Arrow syntax.

Throws the exception when the input is True.

Variant of throwOnCond for Kleisli arrows.

Throw the exception when the input is True.

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

When the input is Just e, throw the exception e.

This does not output any data since it terminates on the first nontrivial input.

Catch an exception in an Automaton.

As soon as an exception occurs, switch to a new Automaton, the exception handler, based on the exception value.

For exception catching where the handler can throw further exceptions, see AutomatonExcept further below.

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

Embed an ExceptT value inside the Automaton.

Whenever the input value is an ordinary value, it is passed on. If it is an exception, it is raised.

Immediately throw the current input as an exception.

Useful inside AutomatonExcept if you don't want to advance a further step in execution, but first see what the current input is before continuing.

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

Variant of once without input.

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

Extract an Automaton from a monadic action.

Runs a monadic action that produces an Automaton on the first step, and then runs result for all further inputs (including the first one).

reactimates an Automaton until it returns True.

Run the first Automaton until the second value in the output tuple is Just c, then start the second automaton, discarding the current output b.

This is analogous to Yampa's switch, with Maybe instead of Event.

Run the first Automaton until the second value in the output tuple is Just c, then start the second automaton one step later (after the current b has been output).

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

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.

Signal an exception value e.

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

• throwE e >>= m = throwE e

The inverse of ExceptT.