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.

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.

Given a FilePath and an Auto, serialize and freeze the state of the Auto as binary to that FilePath.

Give a FilePath and an Auto, and readAuto will attempt to resume the saved state of the Auto from disk, reading from the given FilePath. Will return Left upon a decoding error, with the error, and Right if the decoding is succesful.

Like readAuto, but will return the original Auto (instead of a resumed one) if the file does not exist.

Useful if you want to "resume an Auto" "if there is" a save state, or just use it as-is if there isn't.

Transforms the given Auto into an Auto that constantly saves its state to the given FilePath at every "step". Requires an underlying MonadIO.

Note that (unless the Auto depends on IO), the resulting Auto is meant to be operationally identical in its inputs/outputs to the original one.

Like loading, except silently suppresses all I/O and decoding errors; if there are errors, it returns back the given Auto as-is.

Useful for when you aren't sure the save state is on disk or not yet, and want to resume it only in the case that it is.

Transforms the given Auto into an Auto that, when you first try to run or step it, "loads" itself from disk at the given FilePath.

Will throw a runtime exception on either an I/O error or a decoding error.

Note that (unless the Auto depends on IO), the resulting Auto is meant to be operationally identical in its inputs/outputs to the fast-forwarded original Auto.

Like serializing, except suppresses all I/O and decoding errors.

Useful in the case that when the Auto is first run and there is no save state yet on disk (or the save state is corrupted), it'll "start a new one"; if there is one, it'll load it automatically. Then, on every further step in both cases, it'll update the save state.

A combination of saving and loading. When the Auto is first run, it loads the save state from the given FilePath and fast forwards it. Then, subsequently, it updates the save state on disk on every step.

Takes an Auto and basically "wraps" it so that you can trigger saves with a blip stream.

For example, we can take sumFrom 0:

saveOnB (sumFrom 0) :: Auto IO (Int, Blip FilePath) Int

It'll behave just like sumFrom 0 (with the input you pass in the first field of the tuple)...and whenever the blip stream (the second field of the input tuple) emits, it'll save the state of sumFrom 0 to disk at the given FilePath.

Contrast to saveFromB, where the Auto itself can trigger saves; in this one, saves are triggered "externally".

Might be useful in similar situations as saveFromB, except if you want to trigger the save externally.

Like loadOnB, except silently ignores errors. When a load is requested, but there is an IO or parse error, the loading is skipped.

Takes an Auto and basically "wraps" it so that you can trigger loads/resumes from a file with a blip stream.

For example, we can take sumFrom 0:

loadOnB (sumFrom 0) :: Auto IO (Int, Blip FilePath) Int

It'll behave just like sumFrom 0 (with the input you pass in the first field of the tiple)...and whenever the blip stream (the second field of the input tuple) emits, it'll "reset" and "reload" the sumFrom 0 from the FilePath on disk.

Will throw a runtime exception if there is an IO error or a parse error.

Contrast to loadFromB, where the Auto itself can trigger reloads/resets; in this one, the loads are triggered "externally".

Might be useful in similar situations as loadFromB, except if you want to trigger the loading externally.

Takes an Auto that produces a blip stream with a FilePath and a value, and turns it into an Auto that, outwardly, produces just the value.

Whenever the output blip stream emits, it automatically serializes and saves the state of the Auto to the emitted FilePath.

In practice, this allows any Auto to basically control when it wants to "save", by providing a blip stream.

The following is an alternative implementation of saving, except saving every two steps instead of every step:

saving2 fp a = saveFromB (a &&& (every 2 . pure fp))

Or, in proc notation:

saving2 fp a = saveFromB $ proc x -> do
    y <- a       -< x
    b <- every 2 -< fp
    id -< (y, b)

(Recall that every n is the Auto that emits the received value every n steps)

In useful real-world cases, you can have the Auto decide whether or not to save itself based on its input. Like, for example, when it detects a certain user command, or when the user has reached a given location.

The following takes a FilePath and an Auto (a), and turns it into an Auto that "saves" whenever a crosses over from positive to negative.

saveOnNegative fp a = saveFromB $ proc x -> do
    y       <- a            -< x
    saveNow <- became (< 0) -< y
    id       -< (y, fp <$ saveNow)

Contrast to saveOnB, where the saves are triggered by outside input. In this case, the saves are triggered by the Auto to be saved itself.

Like loadFromB, except silently ignores errors. When a load is requested, but there is an IO or parse error, the loading is skipped.

Takes an Auto that outputs a b and a blip stream of FilePaths and returns an Auto that ouputs only that b stream...but every time the blip stream emits, it "resets/loads" itself from that FilePath.

The following is a re-implementation of loading...except delayed by one (the second step that is run is the first "resumed" step).

loading2 fp a = loadFromB $ proc x -> do
    y       <- a           -< x
    loadNow <- immediately -< fp
    id       -< (y, loadNow)

(the blip stream emits only once, immediately, to re-load).

In the real world, you could have the Auto decide to reset or resume itself based on a user command:

loadFrom = loadFromB $ proc x -> do
    steps  <- count -< ()
    toLoad <- case words x of
                  ("load":fp:_) -> do
                      immediately -< fp
                  _             -> do
                      never       -< ()
    id      -< (steps, toLoad)

This will throw a runtime error on an IO exception or parsing error.