Control.Varying.Event

An event stream is simply a stream of Maybe a. This kind of stream is considered to be only defined at those occurances of Just a. Events describe things that happen at a specific time, place or any collection of inputs.

For example, you can think of the event stream VarT IO Double (Event ()) as an occurrence of () at a specific value of Double. It is possible that this Double is time, or it could be the number of ice cream sandwiches eaten by a particular cat.

In varying we use event streams to dynamically update the network while it is running. For more info on switching and sequencing streams with events please check out Spline, which lets you chain together sequences of values and events using a familiar do-notation.

Event constructors (synonyms of Maybe)

type Event = Maybe

event :: a -> Event a

A synonym for the Maybe constructor Just.

noevent :: Event a

A synonym for the Maybe constructor Nothing.

Generating events from value streams

use :: (Functor f, Functor e) => a -> f (e b) -> f (e a)

use :: Monad m => b -> VarT m a (Event x) -> VarT m a (Event b)

Populates a varying Event with a value. This is meant to be used with the various on... event triggers. For example, use 1 onTrue produces values of Event 1 when the input value is True.

onTrue :: Monad m => VarT m Bool (Event ())

Triggers an Event () when the input value is True.

use b onTrue :: Monad m => VarT m Bool (Event b)

onUnique :: (Monad m, Eq a) => VarT m a (Event a)

Triggers an Event a when the input is distinct from the previous input.

use b onUnique :: (Eq x, Monad m) => VarT m x (Event b)

onWhen :: Applicative m => (a -> Bool) -> VarT m a (Event a)

Triggers an Event a when the condition is met.

Folding and gathering event streams

foldStream :: Monad m => (a -> t -> a) -> a -> VarT m (Event t) a

Like a left fold over all the stream's produced values.

startingWith :: Monad m => a -> VarT m (Event a) a

Produces the given value until the input events produce a value, then produce that value until a new input event produces. This always holds the last produced value, starting with the given value.

time >>> after 3 >>> startingWith 0

>>> :{
let v = onWhen (== 3) >>> startingWith 0
in testVarOver v [0, 1, 2, 3, 4]
>>> :}
0
0
0
3
3

startWith :: Monad m => a -> VarT m (Event a) a

Produces the given value until the input events produce a value, then produce that value until a new input event produces. This always holds the last produced value, starting with the given value.

time >>> after 3 >>> startingWith 0

>>> :{
let v = onWhen (== 3) >>> startingWith 0
in testVarOver v [0, 1, 2, 3, 4]
>>> :}
0
0
0
3
3

Combining multiple event streams

bothE :: Monad m => (a -> b -> c) -> VarT m a (Event a) -> VarT m a (Event b) -> VarT m a (Event c)

Combine two Event streams. Produces an event only when both streams proc at the same time.

anyE :: Monad m => [VarT m a (Event b)] -> VarT m a (Event b)

Combine two Event streams and produce an Event any time either stream produces. In the case that both streams produce, this produces the Event of the leftmost stream.

List-like operations on event streams

filterE :: Monad m => (b -> Bool) -> VarT m a (Event b) -> VarT m a (Event b)

Inhibit all Events that don't pass the predicate.

takeE :: Monad m => Int -> VarT m a (Event b) -> VarT m a (Event b)

Stream through some number of successful Events and then inhibit forever.

dropE :: Monad m => Int -> VarT m a (Event b) -> VarT m a (Event b)

Inhibit the first n occurences of an Event.

Primitive event streams

once :: Monad m => b -> VarT m a (Event b)

Produce the given event value once and then inhibit forever.

always :: Monad m => b -> VarT m a (Event b)

Produces Events with the initial value forever.

always e = pure (Event e)

never :: Monad m => VarT m b (Event c)

Never produces any Event values.

never = pure Nothing

before :: (Monad m, Num t, Ord t) => t -> VarT m t (Event t)

Emits events before accumulating t of input dt. Note that as soon as we have accumulated >= t we stop emitting events and therefore an event will never be emitted exactly at time == t.

after :: (Monad m, Num t, Ord t) => t -> VarT m t (Event t)

Emits events after t input has been accumulated. Note that event emission is not guaranteed to begin exactly at t, since it depends on the input.

Switching

switch :: Monad m => VarT m a (Event (VarT m a b)) -> VarT m a (Event b)

Higher-order switching. Use an event stream of value streams and produces event values of the latest produced value stream. Switches to a new value stream each time one is produced. The currently used value stream maintains local state until the outer event stream produces a new value stream.

In this example we're sequencing the value streams we'd like to use and then switching them when the outer event stream fires.

>>> import Control.Varying.Spline
>>> :{
let v :: VarT IO () (Event Int)
    v = switch $ flip outputStream Nothing $ do
          step $ Just $ 1 >>> accumulate (+) 0
          step Nothing
          step Nothing
          step $ Just 5
          step Nothing
in testVarOver v [(), (), (), (), ()] -- testing over five frames
>>> :}
Just 1
Just 2
Just 3
Just 5
Just 5

Bubbling

onlyWhen

Arguments

:: Monad m

=> VarT m a b

v - The value stream

-> (a -> Bool)

f - The predicate to run on v's input values.

-> VarT m a (Event b)

Produce Events of a value stream v only when its input value passes a predicate f. v maintains state while cold.

onlyWhenE

Arguments

:: Monad m

=> VarT m a b

v - The value stream

-> VarT m a (Event c)

h - The event stream

-> VarT m a (Event b)

Produce events of a stream v only when an event stream h produces an event. v and h maintain state while cold.