Applies the given "monadic function" (function returning a monadic action) to every incoming item; the result is the result of executing the action returned.

Note that this essentially lifts a "Kleisli arrow"; it's like arr, but for "monadic functions" instead of normal functions:

arr  :: (a -> b)   -> Auto m a b
arrM :: (a -> m b) -> Auto m a b

arrM f . arrM g == arrM (f <=< g)

One neat trick you can do is that you can "tag on effects" to a normal Auto by using *> from Control.Applicative. For example:

>>> let a = arrM print *> sumFrom 0
>>> ys <- streamAuto a [1..5]
1                -- IO output
2
3
4
5
>>> ys
[1,3,6,10,15]    -- the result

Here, a behaves "just like" sumFrom 0...except, when you step it, it prints out to stdout as a side-effect. We just gave automatic stdout logging behavior!

To get every output, executes the monadic action and returns the result as the output. Always ignores input.

This is basically like an "effectful" pure:

pure   :: b   -> Auto m a b
effect :: m b -> Auto m a b

The output of pure is always the same, and the output of effect is always the result of the same monadic action. Both ignore their inputs.

Fun times when the underling Monad is, for instance, Reader.

>>> let a = effect ask    :: Auto (Reader b) a b
>>> let r = evalAuto a () :: Reader b b
>>> runReader r "hello"
"hello"
>>> runReader r 100
100

If your underling monad has effects (IO, State, Maybe, Writer, etc.), then it might be fun to take advantage of *> from Control.Applicative to "tack on" an effect to a normal Auto:

>>> let a = effect (modify (+1)) *> sumFrom 0 :: Auto (State Int) Int Int
>>> let st = streamAuto a [1..10]
>>> let (ys, s') = runState st 0
>>> ys
[1,3,6,10,15,21,28,36,45,55]
>>> s'
10

Our Auto a behaves exactly like sumFrom 0, except at each step, it also increments the underlying/global state by one. It is sumFrom 0 with an "attached effect".

The input stream is a stream of monadic actions, and the output stream is the result of their executions, through executing them.

Maps one blip stream to another; replaces every emitted value with the result of the monadic function, executing it to get the result.

Maps one blip stream to another; replaces every emitted value with the result of a fixed monadic action, run every time an emitted value is received.

Outputs the identical blip stream that is received; however, every time it sees an emitted value, executes the given monadic action on the side.

The very first output executes a monadic action and uses the result as the output, ignoring all input. From then on, it persistently outputs that first result.

Like execOnce, except outputs the result of the action instead of ignoring it.

Useful for loading resources in IO on the "first step", like a word list:

dictionary :: Auto IO a [String]
dictionary = cache (lines $ readFile "wordlist.txt")

Always outputs '()', but when asked for the first output, executes the given monadic action.

Pretty much like cache, but always outputs '()'.

The non-resumable/non-serializable version of cache. Every time the Auto is deserialized/reloaded, it re-executes the action to retrieve the result again.

Useful in cases where you want to "re-load" an expensive resource on every startup, instead of saving it to in the save states.

dictionary :: Auto IO a [String]
dictionary = cache_ (lines $ readFile "dictionary.txt")

The non-resumable/non-serializable version of execOnce. Every time the Auto is deserialized/reloaded, the action is re-executed again.

Swaps out the underlying Monad of an Auto using the given monad morphism "transforming function", a natural transformation.

Basically, given a function to "swap out" any m a with an m' a, it swaps out the underlying monad of the Auto.

This forms a functor, so you rest assured in things like this:

hoistA id == id
hoistA f a1 . hoistA f a2 == hoistA f (a1 . a2)

Generalizes an Auto' a b to an Auto m a b' for any Monad m, using hoist.

You generally should be able to avoid using this if you never directly write any Auto's and always write 'Auto m' parameterized over all Monads, but...in case you import one from a library or something, you can use this.

Unrolls the underlying ReaderT of an Auto into an Auto that takes in the input "environment" every turn in addition to the normal input.

So you can use any ReaderT r m as if it were an m. Useful if you want to compose and create some isolated Autos with access to an underlying environment, but not your entire program.

Also just simply useful as a convenient way to use an Auto over Reader with stepAuto and friends.

When used with Reader r, it turns an Auto (Reader r) a b into an Auto' (a, r) b.

Takes an Auto that operates under the context of a read-only environment, an environment value, and turns it into a normal Auto that always "sees" that value when it asks for one.

>>> let a   = effect ask :: Auto (Reader b) a b
>>> let rdr = streamAuto' a [1..5] :: Reader b [b]
>>> runReader rdr "hey"
["hey", "hey", "hey", "hey", "hey"]

Useful if you wanted to use it inside/composed with an Auto that does not have a global environment:

bar :: Auto' Int String
bar = proc x -> do
    hey <- sealReader (effect ask) "hey" -< ()
    id -< hey ++ show x

>>> streamAuto' bar [1..5]
["hey1", "hey2", "hey3", "hey4", "hey5"]

Note that this version serializes the given r environment, so that every time the Auto is reloaded/resumed, it resumes with the originally given r environment, ignoring whatever r is given to it when trying to resume it. If this is not the behavior you want, use sealReader_.

Reader is convenient because it allows you to "chain" and "compose" Autos with a common environment, instead of explicitly passing in values every time. For a convenient way of generating Autos under ReaderT, and also for some motivating examples, see readerA and runReaderA.

The non-resuming/non-serializing version of sealReader. Does not serialize/reload the r environment, so that whenever you "resume" the Auto, it uses the new r given when you are trying to resume, instead of loading the originally given one.

DOES serialize the actual Auto!

Transforms an Auto on two input streams ( a "normal input" stream a and an "environment input stream" r) into an Auto on one input stream a with an underlying environment r through a Reader monad.

Why is this useful? Well, if you have several Autos that all take in a side r stream, and you want to convey that every single one should get the same r at every step, you can instead have all of them pull from a common underlying global environment.

Note: Function is the inverse of runReaderA:

readerA . runReaderA == id
runReaderA . readerA == id

Takes an Auto that operates under the context of a read-only environment, an environment value, and turns it into a normal Auto that always gets its environment value from an MVar.

This allows for "hot swapping" configurations. If your whole program runs under a configuration data structure as the environment, you can load the configuration data to the MVar and then "hot swap" it out by just changing the value in the MVar from a different thread.

Note that this will block on every "step" until the MVar is readablefullhas a value, if it does not.

Basically a disciplined wrapper/usage over sealReaderM.

Takes an Auto that operates under the context of a read-only environment, an environment value, and turns it into a normal Auto that always gets its environment value by executing an action every step in the underlying monad.

This can be abused to write unmaintainble code really fast if you don't use it in a disciplined way. One possible usage is to query a database in IO (or MonadIO) for a value at every step. If you're using underlying global state, you can use it to query that too, with get or gets. You could even use getLine, maybe, to get the result from standard input at every step.

One disciplined wrapper around this is sealReaderMVar, where the environment at every step comes from reading an MVar. This can be used to "hot swap" configuration files.

Transforms an Auto on with two output streams (a "normal output stream" b, and a "logging output stream" w) into an Auto with just one output stream a, funneling the logging stream w into an underlying WriterT monad.

Note: Function is the inverse of runWriterA:

writerA . runWriterA == id
runWriterA . writerA == id

Unrolls the underlying WriterT w m Monad, so that an Auto that takes in a stream of a and outputs a stream of b will now output a stream (b, w), where w is the "new log" of the underlying Writer at every step.

Examples:

foo :: Auto (Writer (Sum Int)) Int Int
foo = effect (tell 1) *> effect (tell 1) *> sumFrom 0

>>> let fooWriter = streamAuto foo
>>> runWriter $ fooWriter [1..10]
([1,3,6,10,15,21,28,36,45,55], Sum 20)

foo increments an underlying counter twice every time it is stepped; its "result" is just the cumulative sum of the inputs.

When we "stream" it, we get a [Int] -> Writer (Sum Int) [Int]...which we can give an input list and runWriter it, getting a list of outputs and a "final accumulator state" of 10, for stepping it ten times.

However, if we use runWriterA before streaming it, we get:

>>> let fooW = runWriterA foo
>>> streamAuto' fooW [1..10]
[ (1 , Sum 2), (3 , Sum 2), (6 , Sum 2)
, (10, Sum 2), (15, Sum 2), (21, Sum 2), -- ...

Instead of accumulating it between steps, we get to "catch" the Writer output at every individual step.

We can write and compose our own Autos under Writer, using the convenience of a shared accumulator, and then "use them" with other Autos:

bar :: Auto' Int Int
bar = proc x -> do
  (y, w) <- runWriterA foo -< x
  blah <- blah -< w

And now you have access to the underlying accumulator of foo to access. There, w represents the continually updating accumulator under foo, and will be different/growing at every "step".

For a convenient way to create an Auto under WriterT, see writerA.

Takes an Auto that works with underlying global, mutable state, and "seals off the state" from the outside world.

An 'Auto (StateT s m) a b' maps a stream of a to a stream of b, but does so in the context of requiring an initial s to start, and outputting a modified s.

Consider this example State Auto:

foo :: Auto (State Int) Int Int
foo = proc x -> do
    execB (modify (+1)) . emitOn odd  -< x
    execB (modify (*2)) . emitOn even -< x
    st   <- effect get -< ()
    sumX <- sumFrom 0  -< x
    id    -< sumX + st

On every output, the "global" state is incremented if the input is odd and doubled if the input is even. The stream st is always the value of the global state at that point. sumX is the cumulative sum of the inputs. The final result is the sum of the value of the global state and the cumulative sum.

In writing like this, you lose some of the denotative properties because you are working with a global state that updates at every output. You have some benefit of now being able to work with global state, if that's what you wanted I guess.

To "run" it, you could use streamAuto to get a State Int Int:

>>> let st = streamAuto foo [1..10] :: State Int Int
>>> runState st 5
([  7, 15, 19, 36, 42, 75, 83,136,156,277], 222)

(The starting state is 5 and the ending state after all of that is 222)

However, writing your entire program with global state is a bad bad idea! So, how can you get the "benefits" of having small parts like foo be written using State, and being able to use it in a program with no global state?

Using sealState! Write the part of your program that would like shared global state with State...and compose it with the rest as if it doesn't, locking it away!

sealState       :: Auto (State s) a b -> s -> Auto' a b
sealState foo 5 :: Auto' Int Int

bar :: Auto' Int (Int, String)
bar = proc x -> do
    food <- sealState foo 5 -< x
    id -< (food, show x)

>>> streamAuto' bar [1..10]
[ (7, "1"), (15, "2"), (19, "3"), (36, "4"), (42, "5"), (75, "6") ...

We say that sealState f s0 takes an input stream, and the output stream is the result of running the stream through f, first with an initial state of s0, and afterwards with each next updated state.

If you wanted to "seal" the state and have it be untouchable to the outside world, yet still have a way to "monitor"/"view" it, you can modify the original Auto using &&&, effect, and 'get to get a "view" of the state:

>>> streamAuto' (sealState (foo &&& effect get) 5) [1..10]
[(7,6),(15,12),(19,13),(36,26),(42,27),(75,54),(83,55),(146,110),(156,111),(277,222)]

Now, every output of sealState foo 5 is tuplied up with a peek of its state at that point.

For a convenient way of "creating" an Auto under StateT in the first place, see stateA.

The non-resuming/non-serializing version of sealState.

Unrolls the underlying StateT of an Auto into an Auto that takes in an input state every turn (in addition to the normal input) and outputs, along with the original result, the modified state.

So now you can use any StateT s m as if it were an m. Useful if you want to compose and create some isolated Autos with access to an underlying state, but not your entire program.

Also just simply useful as a convenient way to use an Auto over State with stepAuto and friends.

When used with State s, it turns an Auto (State s) a b into an Auto' (a, s) (b, s).

For a convenient way to "generate" an Auto StateT, see stateA

Transforms an Auto with two input streams and two output streams (a "normal" input a output b stream, and a "state transforming" side-stream taking in s and outputting s), abstracts away the s stream as a modifcation to an underyling StateT monad. That is, your normal inputs and outputs are now your only inputs and outputs, and your input s comes from the underlying global mutable state, and the output s goes to update the underlying global mutable state.

For example, you might have a bunch of Autos that interact with a global mutable state:

foo :: Auto (StateT Double m) Int Bool
bar :: Auto (StateT Double m) Bool Int
baz :: Auto (StateT Double m) Bool String

Where foo, bar, and baz all interact with global mutable state. You'd use them like this:

full :: Auto (StateT Double m) Int String
full = proc inp -> do
    fo <- foo -< inp
    br <- bar -< fo
    bz <- baz -< fo
    id -< replicae br bz

stateA allows you generate a new Auto under StateT:

thing :: Auto m (Int, Double) (Bool, Double)
stateA thing :: Auto (StateT Double m) Int Bool

So now the two side-channels are interpreted as working with the global state:

full :: Auto (StateT Double m) Int String
full = proc inp -> do
    fo <- foo          -< inp
    tg <- stateA thing -< inp
    br <- bar          -< fo || tg
    bz <- baz          -< fo && tg
    id -< replicae br bz

You can then "seal it all up" in the end with an initial state, that keeps on re-running itself with the resulting state every time:

full' :: Double -> Auto m Int String
full' = sealState full

Admittedly, this is a bit more esoteric and dangerous (programming with global state? what?) than its components readerA and writerA; I don't actually recommend you programming with global state unless it really is the best solution to your problem...it tends to encourage imperative code/loops, and "unreasonable" and manageable code. See documentation for sealStateA for best practices. Basically every bad thing that comes with global mutable state. But, this is provided here for sake of completeness with readerA and writerA.

Note: function is the inverse of runstateA.

stateA . runStateA == id
runStateA . stateA == id

Like stateA, but assumes that the output is the modified state.

Unrolls the underlying Monad of an Auto if it happens to be Traversable ('[]', Maybe, etc.).

It can turn, for example, an Auto [] a b into an Auto' a [b]; it collects all of the results together. Or an Auto Maybe a b into an Auto' a (Maybe b).

This might be useful if you want to make some sort of "underlying inhibiting" Auto where the entire computation might just end up being Nothing in the end. With this, you can turn that possibly-catastrophically-failing Auto (with an underlying Monad of Maybe) into a normal Auto, and use it as a normal Auto in composition with other Autos...returning Just if your computation succeeded.

runTraversableA :: Auto Maybe a b -> Interval' a b

foo :: Auto Maybe Int Int
foo = arrM $ x -> if even x then Just (x div 2) else Nothing

bar :: Auto Maybe Int Int
bar = arrM Just

>>> streamAuto foo [2,4,6,7]
Nothing
>>> streamAuto' (runTraversableA foo) [2,4,6,7]
[Just 1, Just 2, Just 3, Nothing]
>>> streamAuto (foo &&& bar) [2,4,6]
Just [(1, 2),(2, 4),(3, 6)]
>>> streamAuto (foo &&& bar) [2,4,6,7]
Nothing
>>> streamAuto' (runTraversableA foo <|?> runTraversableA bar) [2,4,6,7]
[Just 1, Just 2, Just 3, Just 7]

Wraps a "try" over an underlying IO monad; if the Auto encounters a runtime exception while trying to "step" itself, it'll output a Left with the Exception. Otherwise, will output left.

Note that you have to explicitly specify the type of the exceptions you are catching; see Control.Exception documentation for more details.