Represents a relationship between an input and an output, where the output can be "on" or "off" (using Just and Nothing) for contiguous chunks of time.

"Just" a type alias for Auto m a (Maybe b). If you ended up here with a link...no worries! If you see Interval m a b, just think Auto m a (Maybe b) for type inference/type checking purposes.

If you see something of type Interval, you can rest assured that it has "interval semantics" --- it is on and off for meaningfully contiguous chunks of time, instead of just on and off willy nilly. If you have a function that expects an Interval, then the function expects its argument to behave in this way.

Interval, specialized with Identity as its underlying Monad. Analogous to Auto' for Auto.

The output stream is alwayas off, regardless of the input.

Note that any monadic effects of the input Auto when composed with off are still executed, even though their result value is suppressed.

off == pure Nothing

The output stream is always on, with exactly the value of the corresponding input.

toOn == arr Just

An "interval collapsing" Auto. A stream of on/off values comes in; the output is the value of the input when the input is on, and the "default value" when the input is off.

Much like fromMaybe from Data.Maybe.

fromInterval d = arr (fromMaybe d)

An "interval collapsing" Auto. A stream of on/off values comes in; when the input is off, the output is the "default value". When the input is off, the output is the given function applied to the "on" value.

Much like maybe from Data.Maybe.

fromIntervalWith d f = arr (maybe d f)

For onFor n, the first n items in the output stream are always "on" (passing through with exactly the value of the corresponding input); for the rest, the output stream is always "off", suppressing all input values forevermore.

If a number less than 0 is passed, 0 is used.

For offFor n, the first n items in the output stream are always "off", suppressing all input; for the rest, the output stream is always "on", outputting exactly the value of the corresponding input.

A combination of onFor and offFor; for window b e, the output stream will be "on" from item b to item e inclusive with the value of the corresponding input; for all other times, the output stream is always off, suppressing any input.

The output is "on" with exactly the value of he corresponding input when the input passes the predicate, and is "off" otherwise.

>>> let a = whenI (\x -> x >= 2 && x <= 4)
>>> streamAuto' a [1..6]
[Nothing, Just 2, Just 3, Just 4, Nothing, Nothing]

Careful when using this; you could exactly create an Interval that "breaks" "interval semantics"; for example, 'whenI even', when you know your input stream does not consist of chunks of even numbers and odd numbers at a time.

Like whenI, but only allows values to pass whenever the input does not satisfy the predicate. Blocks whenever the predicate is true.

>>> let a = unlessI (\x -> x < 2 || x > 4)
>>> steamAuto' a [1..6]
[Nothing, Just 2, Just 3, Just 4, Nothing, Nothing]

Forks a common input stream between an Interval and an Auto, and returns, itself, a normal non-interval Auto.. If the output of the first one is "on", the output of the whole thing is that "on" value. Otherwise, the output is exactly that of the second one.

>>> let a1 = (onFor 2 . pure "hello") <|!> pure "world"
>>> take 5 . streamAuto' a1 $ repeat ()
["hello", "hello", "world", "world", "world"]

This one is neat because it associates from the right, so it can be "chained":

>>> let a2 = onFor 2 . pure "hello"
        <|!> onFor 4 . pure "world"
        <|!> pure "goodbye!"
>>> take 6 . streamAuto' a2 $ repeat ()
["hello", "hello", "world", "world", "goodbye!", "goodbye!"]

 a <|!> b <|!> c

associates as

 a <|!> (b <|!> c)

So using this, you can "chain" a bunch of choices between intervals, and then at the right-most, "final" one, provide the default behavior.

Warning: If your underlying monad produces effects, remember that both Autos are run at every step, along with any monadic effects, regardless of whether they are "on" or "off".

Forks a common input stream between the two Intervals and returns, itself, an Interval. If the output of the first one is "on", the whole thing is on with that output. Otherwise, the output is exactly that of the second one.

>>> let a = (onFor 2 . pure "hello") <|?> (onFor 4 . pure "world")
>>> take 5 . streamAuto' a $ repeat ()
[Just "hello", Just "hello", Just "world", Just "world", Nothing]

You can drop the parentheses, because of precedence; the above could have been written as:

>>> let a' = onFor 2 . pure "hello" <|?> onFor 4 . pure "world"

Warning: If your underlying monad produces effects, remember that both Autos are run at every step, along with any monadic effects, regardless of whether they are "on" or "off".

Note that more often than not, <|!> is probably more useful. This is useful only in the case that you really, really want an interval at the end of it all.

Forks an input stream between all Intervals in the list. The result is an Interval whose output is "on" when any of the original Intervals is on, with the value of the first "on" one.

chooseInterval == foldr (<|?>) off

Forks an input stream between all Intervals in the list, plus a "default Auto. The output is the value of the first "on" Interval; if there isn't any, the output from the "default Auto" is used.

choose == foldr (<|!>)

Takes two input streams --- a stream of normal values, and a blip stream. Before the first emitted value of the input blip stream, the output is always "off", suppressing all inputs. After the first emitted value of the input blip stream, the output is always "on" with the corresponding value of the first input stream.

>>> let a = after . (count &&& inB 3)
>>> take 6 . streamAuto' a $ repeat ()
[Nothing, Nothing, Just 2, Just 3, Just 4, Just 5]

(count is the Auto that ignores its input and outputs the current step count at every step, and inB 3 is the Auto generating a blip stream that emits at the third step.)

Be careful to remember that in the above example, count is still "run" at every step, and is progressed (and if it were an Auto with monadic effects, they would still be executed). It just isn't allowed to pass its output values through after until the blip stream emits.

Takes two input streams --- a stream of normal values, and a blip stream. Before the first emitted value of the input blip stream, the output is always "on" with the corresponding value of the first input stream. After the first emitted value of the input blip stream, the output will be "off" forever, suppressing all input.

>>> let a = before . (count &&& inB 3)
>>> take 5 . streamAuto' a $ repeat ()
[Just 0, Just 1, Nothing, Nothing, Nothing]

(count is the Auto that ignores its input and outputs the current step count at every step, and inB 3 is the Auto generating a blip stream that emits at the third step.)

Be careful to remember that in the above example, count is still "run" at every step, and is progressed (and if it were an Auto with monadic effects, they would still be executed). It just isn't allowed to pass its output values through before after the blip stream emits.

Takes three input streams: a stream of normal values, a blip stream of "turning-on" blips, and a blip stream of "turning-off" blips. After the first blip stream emits, the output will switch to "on" with the value of the first input stream. After the second blip stream emits, the output will switch to "off", supressing all inputs. An emission from the first stream toggles this "on"; an emission from the second stream toggles this "off".

>>> let a = between . (count &&& (inB 3 &&& inB 5))
>>> take 7 . streamAuto' a $ repeat ()
[Nothing, Nothing, Just 2, Just 3, Nothing, Nothing, Nothing]

The output is constantly "on" with the last emitted value of the input blip stream. However, before the first emitted value, it is "off". value of the input blip stream. From then on, the output is always the last emitted value

>>> let a = hold . inB 3
>>> streamAuto' a [1..5]
[Nothing, Nothing, Just 3, Just 3, Just 3]

If you want an Auto m (Blip a) a (no Nothing...just a "default value" before everything else), then you can use holdWith from Control.Auto.Blip...or also just hold with <|!> or fromInterval.

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

For holdFor n, The output is only "on" if there was an emitted value from the input blip stream in the last n steps. Otherwise, is off.

Like hold, but it only "holds" the last emitted value for the given number of steps.

>>> let a = holdFor 2 . inB 3
>>> streamAuto' a [1..7]
[Nothing, Nothing, Just 3, Just 3, Nothing, Nothing, Nothing]

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

Stretches the last "on"/Just input over the entire range of following "off"/Nothing inputs. Holds on to the last Just until another one comes along.

>>> streamAuto' holdJusts [Nothing, Just 1, Just 3, Nothing, Nothing, Just 5]
[Nothing, Just 1, Just 3, Just 3, Just 3, Just 5]

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

Lifts an Auto m a b (transforming as into bs) into an Auto m (Maybe a) (Maybe b) (or, Interval m (Maybe a) b, transforming intervals of as into intervals of b.

It does this by running the Auto as normal when the input is "on", and freezing itbeing "off" when the input is off/.

>>> let a1 = during (sumFrom 0) . onFor 2 . pure 1
>>> take 5 . streamAuto' a1 $ repeat ()
[Just 1, Just 2, Nothing, Nothing, Nothing]

>>> let a2 = during (sumFrom 0) . offFor 2 . pure 1
>>> take 5 . streamAuto' a2 $ repeat ()
[Nothing, Nothing, Just 1, Just 2, Just 3]

(Remember that pure x is the Auto that ignores its input and constantly just pumps out x at every step)

Note the difference between putting the sumFrom "after" the offFor in the chain with during (like the previous example) and putting the sumFrom "before":

>>> let a3 = offFor 2 . sumFrom 0 . pure 1
>>> take 5 . streamAuto' a3 $ repeat ()
[Nothing, Nothing, Just 3, Just 4, Just 5]

In the first case (with a2), the output of pure 1 was suppressed by offFor, and during (sumFrom 0) was only summing on the times that the 1's were "allowed through"...so it only "starts counting" on the third step.

In the second case (with a3), the output of the pure 1 is never suppressed, and went straight into the sumFrom 0. sumFrom is always summing, the entire time. The final output of that sumFrom 0 is suppressed at the end with offFor 2.

Composes two Intervals, the same way that . composes two Autos:

(.)   :: Auto     m b c -> Auto     m a b -> Auto     m a c
compI :: Interval m b c -> Interval m a b -> Interval m a c

Basically, if any Interval in the chain is "off", then the entire rest of the chain is "skipped", short-circuiting a la Maybe.

(Users of libraries with built-in inhibition semantics like Yampa and netwire might recognize this as the "default" composition in those other libraries)

As a contrived example, how about an Auto that only allows values through during a window...between, say, the second and fourth steps:

>>> let window' start dur = onFor dur `compI` offFor (start - 1)
>>> streamAuto' (window' 2 3)
[Nothing, Just 2, Just 3, Just 4, Nothing, Nothing]

Lifts (more technically, "binds") an Interval m a b into an Interval m (Maybe a) b.

Does this by running the Auto as normal when the input is "on", and freezing itbeing "off" when the input is off/.

It's kind of like during, but the resulting Maybe (Maybe b)) is "joined" back into a Maybe b.

bindI a == fmap join (during a)

This is really an alternative formulation of compI; typically, you will be using compI more often, but this form can also be useful (and slightly more general). Note that:

bindI f == compI f id

This combinator allows you to properly "chain" ("bind") together series of inhibiting Autos. If you have an Interval m a b and an Interval m b c, you can chain them into an Interval m a c.

f             :: Interval m a b
g             :: Interval m b c
bindI g . f :: Interval m a c

(Users of libraries with built-in inhibition semantics like Yampa and netwire might recognize this as the "default" composition in those other libraries)

See compI for examples of this use case.