The Auto type. For this library, an Auto semantically representsdenotes a a relationship/ between an input and an output that is preserved over multiple steps, where that relationship is (optionally) maintained within the context of a monad.

A lot of fancy words, I know...but you can think of an Auto as nothing more than a "stream transformer" of value streams. A stream of sequential input values come in one at a time, and a stream of outputs pop out one at a time, as well.

Using the streamAuto function, you can "unwrap" the inner value stream transformer from any Auto: if a :: Auto m a b, streamAuto lets you turn it into an [a] -> m [b]. "Give me a stream of as, one at a time, and I'll give you a list of bs, matching a relationship to your stream of as."

-- unwrap your inner [a] -> m [b]!
streamAuto :: Monad m => Auto m a b -> ([a] -> m [b])

You can also turn an Auto m a b into an effects stream that executes effects sequentially with toEffectStream and streamAutoEffects, so you can run it with a ListT-compatible library like pipes.

There's a handy type synonym Auto' for relationships that don't really need a monadic context; the m is just Identity:

type Auto' = Auto Identity

So if you had an a :: Auto' a b, you can use streamAuto' to "unwrap" the inner stream transformer, [a] -> [b].

-- unwrap your inner [a] -> [b]!
streamAuto' :: Auto' a b -> ([a] -> [b])

All of the Autos given in this library maintain some sort of semantic relationship between streams --- for some, the outputs might be the inputs with a function applied; for others, the outputs might be the cumulative sum of the inputs.

See the tutorial for more information!

Operationally, an Auto m a b is implemented as a "stateful function". A function from an a where, every time you "apply" it, you get a b and an "updated Auto"/function with updated state.

You can get this function using stepAuto:

stepAuto :: Auto m a b -> (a -> m (b, Auto m a b))

Or, for Auto', stepAuto':

stepAuto' :: Auto' a b -> (a -> (b, Auto' a b))

"Give me an a and I'll give you a b and your "updated" Auto".

Autos really are mostly useful because they can be composed, chained, and modified using their various typeclass instances, like Category, Applicative, Functor, Arrow, etc., and also with the combinators in this library. You can build complex programs as a complex Auto by building up smaller and smaller components. See the tutorial for more information on this.

This type also contains information on its own serialization, so you can serialize and re-load the internal state to binary or disk. See the "serialization" section in the documentation for Control.Auto.Core, or the documentation for mkAutoM for more details.

Special case of Auto where the underlying Monad is Identity.

Instead of "wrapping" an [a] -> m [b], it "wraps" an [a] -> [b].

Returns a string representation of the internal constructor of the Auto. Useful for debugging the result of compositions and functions and seeing how they affect the internal structure of the Auto.

In the order of efficiency, AutoFuncs tend to be faster than AutoStates tend to be faster than AutoArbs. However, when composing one with the other (using Category or Applicative), the two have to be "reduced" to the greatest common denominator; composing an AutoFunc with an AutoArb produces an AutoArb.

More benchmarking is to be done to be able to rigorously say what these really mean, performance wise.

Re-structure Auto internals to use the Arb ("arbitrary") constructors, as recursion-based mealy machines.

Almost always a bad idea in every conceivable situation. Why is it even here?

I'm sorry.

In theory, "purifying" an Auto'" should prep it for faster evaluation when used with stepAuto' or streamAuto'. But the benchmarks have not been run yet, so stay tuned!

TODO: Benchmark

Runs the Auto through one step.

That is, given an Auto m a b, returns a function that takes an a and returns a b and an "updated"/"next" Auto; an a -> m (b, Auto m a b).

This is the main way of running an Auto "step by step", so if you have some sort of game loop that updates everything every "tick", this is what you're looking for. At every loop, gather input a, feed it into the Auto, "render" the result b, and get your new Auto to run the next time.

Here is an example with sumFrom 0, the Auto whose output is the cumulative sum of the inputs, and an underying monad of Identity. Here,

stepAuto :: Auto Identity Int Int
         -> (Int -> Identity (Int, Auto Identity Int Int))

Every time you "step", you give it an Int and get a resulting Int (the cumulative sum) and the "updated Auto", with the updated accumulator.

>>> let a0 :: Auto Identity Int Int
        a0 = sumFrom 0
>>> let Identity (res1, a1) = stepAuto a0 4      -- run with 4
>>> res1
4                -- the cumulative sum, 4
>>> let Identity (res2, a2) = stepAuto a1 5      -- run with 5
>>> res2
9                -- the cumulative sum, 4 + 5
>>> let Identity (res3, _ ) = stepAuto a2 3      -- run with 3
>>> res3
12               -- the cumulative sum, 4 + 5 + 3

By the way, for the case where your Auto is under Identity, we have a type synomym Auto'...and a convenience function to make "running" it more streamlined:

>>> let a0 :: Auto' Int Int
        a0 = sumFrom 0
>>> let (res1, a1) = stepAuto' a0 4          -- run with 4
>>> res1
4                -- the cumulative sum, 4
>>> let (res2, a2) = stepAuto' a1 5          -- run with 5
>>> res2
9                -- the cumulative sum, 4 + 5
>>> let (res3, _ ) = stepAuto' a2 3          -- run with 3
>>> res3
12               -- the cumulative sum, 4 + 5 + 3

But, if your Auto actaully has effects when being stepped, stepAuto will execute them:

>>> let a0 :: Auto IO Int Int
        a0 = effect (putStrLn "hey!") *> sumFrom 0
>>> (res1, a1) <- stepAuto a0 4              -- run with 4
hey!         -- IO effect
>>> res1
4                -- the cumulative sum, 4
>>> (res2, a2) <- stepAuto a1 5              -- run with 5
hey!         -- IO effect
>>> res2
9                -- the cumulative sum, 4 + 5
>>> (res3, _ ) <- stepAuto a2 3              -- run with 3
hey!         -- IO effect
>>> res3
12               -- the cumulative sum, 4 + 5 + 3

(Here, effect (putStrLn "hey") is an Auto IO Int (), which ignores its input and just executes putStrLn "hey" every time it is run. When we use *> from Control.Applicative, we "combine" the two Autos together and run them both on each input (4, 5, 3...)...but for the "final" output at the end, we only return the output of the second one, sumFrom 0 (5, 9, 12...))

If you think of an Auto m a b as a "stateful function" a -> m b, then stepAuto lets you "run" it.

In order to directly run an Auto on a stream, an [a], use streamAuto. That gives you an [a] -> m [b].

Runs an Auto' through one step.

That is, given an Auto' a b, returns a function that takes an a and returns a b and an "updated"/"next" Auto'; an a -> (b, Auto' a b).

See stepAuto documentation for motivations, use cases, and more details. You can use this instead of stepAuto when your underyling monad is Identity, and your Auto doesn't produce any effects.

Here is an example with sumFrom 0, the Auto' whose output is the cumulative sum of the inputs

stepAuto' :: Auto' Int Int
          -> (Int -> (Int, Auto' Int Int))

Every time you "step", you give it an Int and get a resulting Int (the cumulative sum) and the "updated Auto'", with the updated accumulator.

>>> let a0 :: Auto' Int Int
        a0 = sumFrom 0
>>> let (res1, a1) = stepAuto' a0 4          -- run with 4
>>> res1
4                -- the cumulative sum, 4
>>> let (res2, a2) = stepAuto' a1 5          -- run with 5
>>> res2
9                -- the cumulative sum, 4 + 5
>>> let (res3, _ ) = stepAuto' a2 3          -- run with 3
>>> res3
12               -- the cumulative sum, 4 + 5 + 3

If you think of an Auto' a b as a "stateful function" a -> b, then stepAuto' lets you "run" it.

In order to directly run an Auto' on a stream, an [a], use streamAuto'. That gives you an [a] -> [b].

Like stepAuto, but drops the "next Auto" and just gives the result.

Like stepAuto', but drops the "next Auto'" and just gives the result. evalAuto for Auto'.

Like stepAuto, but drops the result and just gives the "updated Auto".

Like stepAuto', but drops the result and just gives the "updated Auto'". execAuto for Auto'.

Encode an Auto and its internal state into a ByteString.

Resume an Auto from its ByteString serialization, giving a Left if the deserialization is not possible.

Returns a Put --- instructions (from Data.Serialize) on how to "freeze" the Auto, with its internal state, and save it to a binary encoding. It can later be reloaded and "resumed" by 'resumeAuto'/'decodeAuto'.

Returns a Get from an Auto --- instructions (from Data.Serialize) on taking a ByteString and "restoring" the originally saved Auto, in the originally saved state.

Takes an Auto that is serializable/resumable and returns an Auto that is not. That is, when it is "saved", saves no data, and when it is "resumed", resets itself back to the initial configuration every time; in other words, decodeAuto (unserialize a) bs = Right (unserialize a). Trying to "resume" it will just always give itself, unchanged.

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.

Abstraction over lower-level funging with serialization; lets you modify the result of an Auto by being able to intercept the (b, Auto m a b) output and return a new output value m c.

Note that this is a lot like fmap:

fmap :: (b -> c) -> Auto m a b -> Auto m a c

Except gives you access to both the b and the "updated Auto"; instead of an b -> c, you get to pass a (b, Auto m a b) -> m c.

Basically experimenting with a bunch of abstractions over different lower-level modification of Autos, because making sure the serialization works as planned can be a bit difficult.

Construct the Auto whose output is always the given value, ignoring its input.

Provided for API constency, but you should really be using pure from the Applicative instance, from Control.Applicative, which does the same thing.

Construct the Auto that always "executes" the given monadic value at every step, yielding the result as its output and ignoring its input.

Provided for API consistency, but you shold really be using effect from Control.Auto.Effects, which does the same thing.

Construct a stateless Auto that simply applies the given (pure) function to every input, yielding the output. The output stream is just the result of applying the function to every input.

streamAuto' (mkFunc f) = map f

This is rarely needed; you should be using arr from the Arrow instance, from Control.Arrow.

Construct a stateless Auto that simply applies and executes the givne (monadic) function to every input, yielding the output. The output stream is the result of applying the function to every input, executing/sequencing the action, and returning the returned value.

streamAuto (mkFuncM f) = mapM f

It's recommended that you use arrM from Control.Auto.Effects. This is only really provided for consistency.

Construct an Auto from a state transformer: an a -> s -> (b, s) gives you an Auto m a b, for any Monad m. At every step, it takes in the a input, runs the function with the stored internal state, returns the b result, and now contains the new resulting state. You have to intialize it with an initial state, of course.

From the "stream transformer" point of view, this is rougly equivalent to mapAccumL from Data.List, with the function's arguments and results in the backwards order.

streamAuto' (mkState f s0) = snd . mapAccumL (\s x -> swap (f x s))

Try not to use this if it's ever avoidable, unless you're a framework developer or something. Try make something by combining/composing the various Auto combinators.

If your state s does not have a Serialize instance, then you should either write a meaningful one, provide the serialization methods manually with mkState', or throw away serializability and use mkState_.

A version of mkState, where the internal state isn't serialized. It can be "saved" and "loaded", but the state is lost in the process.

See mkState for more details.

Useful if your state s cannot have a meaningful Serialize instance.

Construct an Auto from a "monadic" state transformer: a -> s -> m (b, s) gives you an Auto m a b. At every step, it takes in the a input, runs the function with the stored internal state and "executes" the m (b, s) to get the b output, and stores the s as the new, updated state. Must be initialized with an initial state.

Try not to use this if it's ever avoidable, unless you're a framework developer or something. Try make something by combining/composing the various Auto combinators.

This version is a wrapper around mkAuto, that keeps track of the serialization and re-loading of the internal state for you, so you don't have to deal with it explicitly.

If your state s does not have a Serialize instance, then you should either write a meaningful one, provide the serialization methods manually with mkStateM', or throw away serializability and use mkStateM_.

A version of mkStateM, where the internal state isn't serialized. It can be "saved" and "loaded", but the state is lost in the process.

See mkStateM for more details.

Useful if your state s cannot have a meaningful Serialize instance.

A version of mkState, where the internal state doesn't have a Serialize instance, so you provide your own instructions for getting and putting the state.

See mkState for more details.

A version of mkStateM, where the internal state doesn't have a Serialize instance, so you provide your own instructions for getting and putting the state.

See mkStateM for more details.

Construct an Auto from a "folding" function: b -> a -> b yields an Auto m a b. Basically acts like a foldl or a scanl. There is an internal accumulator that is "updated" with an a at every step. Must be given an initial accumulator.

Example: an Auto that sums up all of its input.

>>> let summer = accum (+) 0
>>> let (sum1, summer')  = stepAuto' summer 3
>>> sum1
3
>>> let (sum2, summer'') = stepAuto' summer' 10
>>> sum2
13
>>> streamAuto'  summer'' [1..10]
[14,16,19,23,28,34,41,49,58,68]

If your accumulator b does not have a Serialize instance, then you should either write a meaningful one, or throw away serializability and use accum_.

A version of accum, where the internal accumulator isn't serialized. It can be "saved" and "loaded", but the state is lost in the process.

See accum for more details.

Useful if your accumulator b cannot have a meaningful Serialize instance.

Construct an Auto from a "monadic" "folding" function: b -> a -> m b yields an Auto m a b. Basically acts like a foldM or scanM (if it existed). here is an internal accumulator that is "updated" with an input a with the result of the executed m b at every step. Must be given an initial accumulator.

See accum for more details.

If your accumulator b does not have a Serialize instance, then you should either write a meaningful one, or throw away serializability and use accumM_.

A version of 'accumM_, where the internal accumulator isn't serialized. It can be "saved" and "loaded", but the state is lost in the process.

See accumM for more details.

Useful if your accumulator b cannot have a meaningful Serialize instance.

A "delayed" version of accum, where the first output is the initial state of the accumulator, before applying the folding function. Useful in recursive bindings.

>>> let summerD = accumD (+) 0
>>> let (sum1, summerD')  = stepAuto' summerD 3
>>> sum1
0
>>> let (sum2, summerD'') = stepAuto' summerD' 10
>>> sum2
3
>>> streamAuto'  summerD'' [1..10]
[13,14,16,19,23,28,34,41,49,58]

(Compare with the example in accum)

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

A "delayed" version of accumM, where the first output is the initial state of the accumulator, before applying the folding function. Useful in recursive bindings.

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

Construct an Auto by explicity giving its serialization, deserialization, and the function from a to a b and "updated Auto".

Ideally, you wouldn't have to use this unless you are making your own framework. Try your best to make what you want by assembling primtives together. Working with serilization directly is hard.

See mkAutoM for more detailed instructions on doing this right.

Like mkAuto, but without any way of meaningful serializing or deserializing.

Be careful! This Auto can still carry arbitrary internal state, but it cannot be meaningfully serialized or re-loaded/resumed. You can still pretend to do so using 'resumeAuto'/'saveAuto'/'encodeAuto'/'decodeAuto' (and the type system won't stop you), but when you try to "resume"/decode it, its state will be lost.

Construct an Auto by explicitly giving its serializiation, deserialization, and the (monadic) function from a to a b and the "updated Auto".

See the "serialization" section in the Control.Auto.Core module for more information.

Ideally, you wouldn't have to use this unless you are making your own framework. Try your best to make what you want by assembling primtives together.

But sometimes you have to write your own combinators, and you're going to have to use mkAutoM to make it work.

Sometimes, it's simple:

fmap :: (a -> b) -> Auto r a -> Auto r b
fmap f a0 = mkAutoM (do aResumed <- resumeAuto a0
                        return (fmap f aResumed)  )
                    (saveAuto a0)
                    $ x -> do
                        (y, a1) <- stepAuto a0 x
                        return (f y, fmap f a1)

Serializing fmap f a0 is just the same as serializing a0. And to resume it, we resume a0 to get a resumed version of a0, and then we apply fmap f to the Auto that we resumed.

Also another nice "simple" example is:

catchA :: Exception e
       => Auto IO a b
       -> Auto IO a (Either e b)
catchA a = mkAutoM (do aResumed <- resumeAuto a
                       return (catchA aResumed) )
                   (saveAuto a)
                 $ x -> do
                     eya' <- try $ stepAuto a x
                     case eya' of
                       Right (y, a') -> return (Right y, catchA a')
                       Left e        -> return (Left e , catchA a )

Which is basically the same principle, in terms of serializing and resuming strategies.

When you have "switching" --- things that behave like different Autos at different points in time --- then things get a little complicated, because you have to figure out which Auto to resume.

For example, let's look at the source of -?>:

(-?>) :: Monad m
      => Interval m a b   -- ^ initial behavior
      -> Interval m a b   -- ^ final behavior, when the initial
                          --   behavior turns off.
      -> Interval m a b
a1 -?> a2 = mkAutoM l s t
  where
    l = do
      flag <- get
      if flag
        then resumeAuto (switched a2)
        else (-?> a2) $ resumeAuto a1
    s = put False *> saveAuto a1
    t x = do
      (y1, a1') <- stepAuto a1 x
      case y1 of
        Just _  ->
          return (y1, a1' -?> a2)
        Nothing -> do
          (y, a2') <- stepAuto a2 x
          return (y, switched a2')
    switched a = mkAutoM (switched $ resumeAuto a)
                         (put True  *> saveAuto a)
                       $ x -> do
                           (y, a') <- stepAuto a x
                           return (y, switched a')

We have to invent a serialization and reloading scheme, taking into account the two states that the resulting Auto can be in:

1. Initially, it is behaving like a1. So, to save it, we put a flag saying that we are still in stage 1 (False), and then put a1's current serialization data.
2. After the switch, it is behaving like a2. So, to save it, we put a flag saying that we are now in stage 2 (True), and then put a2's current.

Now, when we resume a1 -?> a2, resumeAuto on a1 -?> a2 will give us l. So the Get we use --- the process we use to resume the entire a1 -?> a2, will start at the initial Get/loading function, l here. We have to encode our branching and resuming/serialization scheme into the initial, front-facing l. So l has to check for the flag, and if the flag is true, load in the data for the switched state; otherwise, load in the data for the pre-switched state.

Not all of them are this tricky. Mostly "switching" combinators will be tricky, because switching means changing what you are serializing.

This one might be considerably easier, because of mapM:

zipAuto :: Monad m
        => a                -- ^ default input value
        -> [Auto m a b]     -- ^ Autos to zip up
        -> Auto m [a] [b]
zipAuto x0 as = mkAutoM (zipAuto x0 $ mapM resumeAuto as)
                        (mapM_ saveAuto as)
                        $ xs -> do
                            res <- zipWithM stepAuto as (xs ++ repeat x0)
                            let (ys, as') = unzip res
                            return (ys, zipAuto x0 as')

To serialize, we basically sequence saveAuto over all of the internal Autos --- serialize each of their serialization data one-by-one one after the other in our binary.

To load, we do the same thing; we go over every Auto in as and resumeAuto it, and then collect the results in a list --- a list of resumed Autos. And then we apply zipAuto x0 to that list of Autos, to get our resumed zipAuto x0 as.

So, it might be complicated. In the end, it might be all worth it, too, to have implicit serialization compose like this. Think about your serialization strategy first. Step back and think about what you need to serialize at every step, and remember that it's _the initial_ "resuming" function that has to "resume everything"...it's not the resuming function that exists when you finally save your Auto, it's the resuming Get that was there at the beginning. For -?>, the intial l had to know how to "skip ahead".

And of course as always, test.

If you need to make your own combinator or transformer but are having trouble with the serializtion, feel free to contact me at justin@jle.im, on freenode at #haskell or #haskell-auto, open a github issue, etc. Just contact me somehow, I'll be happy to help!

Like mkAutoM, but without any way of meaningful serializing or deserializing.

Be careful! This Auto can still carry arbitrary internal state, but it cannot be meaningfully serialized or re-loaded/resumed. You can still pretend to do so using 'resumeAuto'/'saveAuto'/'encodeAuto'/'decodeAuto' (and the type system won't stop you), but when you try to "resume"/decode it, its state will be reset.

Force the serializing components of an Auto.

TODO: Test if this really works

A special Auto that acts like the id Auto, but forces results as they come through to be fully evaluated, when composed with other Autos.

TODO: Test if this really works

A special Auto that acts like the id Auto, but forces results as they come through to be evaluated to Weak Head Normal Form, with seq, when composed with other Autos.

TODO: Test if this really works