Control.Varying.Spline

Using splines we can easily create continuous value streams from multiple piecewise event streams. A spline is a monadic layer on top of event streams which are only continuous over a certain domain. The idea is that we use do notation to "run an event stream" from which we will consume produced values. Once the event stream inhibits the computation completes and returns a result value. That result value is then used to determine the next spline in the sequence.

A spline can be converted back into a value stream using execSpline or execSplineT. This allows us to build long, complex, sequential behaviors using familiar notation.

Spline

type Spline a b c = SplineT a b Identity c

A SplineT monad parameterized with Identity that takes input of type a, output of type b and a result value of type c.

Spline Transformer

data SplineT a b m c

SplineT shares a number of types with VarT, specifically its monad, input and output types (m, a and b, respectively). A spline adds a result type which represents the monadic computation's result value. Much like the State monad it has an "internal state" and an eventual result value, where the internal state is the output value. The result value is used only in determining the next spline to sequence.

Constructors

SplineT

Fields

unSplineT :: VarT m a (Step (Event b) c)

SplineTConst c

Instances

MonadTrans (SplineT a b)

A spline is a transformer and other monadic computations can be lifted int a spline.

(Applicative m, Monad m) => Monad (SplineT a b m)

A spline is monad if its output type is a monoid. A spline responds to bind by running until it produces an eventual value, then uses that value to run the next spline.

(Applicative m, Monad m) => Functor (SplineT a b m)

A spline is a functor by applying the function to the result.

(Applicative m, Monad m) => Applicative (SplineT a b m)

A spline is an applicative if its output type is a monoid. It responds to pure by returning a spline that immediately returns the argument. It responds to <*> by applying the left arguments eventual value (the function) to the right arguments eventual value. The output values will me combined with mappend.

(Functor m, Applicative m, MonadIO m) => MonadIO (SplineT a b m)

A spline can do IO if its underlying monad has a MonadIO instance. It takes the result of the IO action as its immediate return value and uses mempty to generate an empty output value.

runSplineT :: (Applicative m, Monad m) => SplineT a b m c -> VarT m a (Step (Event b) c)

Unwrap a spline into a value stream.

scanSpline :: (Applicative m, Monad m) => SplineT a b m c -> [a] -> m [(Event b, Event c)]

Run the spline over the input values, gathering the output and result values in a list.

fromEvents :: (Applicative m, Monad m) => b -> VarT m a (Event b) -> SplineT a b m b

Create a spline using an event stream. The spline will run until the stream inhibits, using the stream's last produced value as the current output value. In the case the stream inhibits before producing a value the default value is used. The spline's result is the last output value.

outputStream :: (Applicative m, Monad m) => b -> SplineT a b m c -> VarT m a b

Evaluates a spline into a value stream of its output type.

resultStream :: (Applicative m, Monad m) => SplineT a b m c -> VarT m a (Event c)

Evaluates a spline to an event stream of its result. The resulting value stream inhibits until the spline's domain is complete and then it produces events of the result type.

step :: (Applicative m, Monad m) => b -> SplineT a b m ()

Produce the argument as an output value exactly once.

Combinators

untilEvent :: (Applicative m, Monad m) => VarT m a b -> VarT m a (Event c) -> SplineT a b m (b, c)

Create a spline from a value stream and an event stream. The spline uses the value stream as its output value. The spline will run until the event stream produces a value, at that point the last output value and the event value are tupled and returned as the spline's result value.

untilEvent_ :: (Applicative m, Monad m) => VarT m a b -> VarT m a (Event c) -> SplineT a b m b

A variant of untilEvent that only results in the left result, discarding the right result.

_untilEvent :: (Applicative m, Monad m) => VarT m a b -> VarT m a (Event c) -> SplineT a b m b

A variant of untilEvent that only results in the right result, discarding the left result.

pair :: Monad m => (b -> d -> f) -> SplineT a b m c -> SplineT a d m e -> SplineT a f m (c, e)

Run two splines in parallel, combining their output. When both conclude, return their result values in a tuple.

race :: (Applicative m, Monad m) => (b -> d -> e) -> SplineT a b m c -> SplineT a d m c -> SplineT a e m c

Run two splines in parallel, combining their output. Return the result of the spline that concludes first. If they conclude at the same time the result is taken from the left spline.

capture :: (Applicative m, Monad m, Eq b) => SplineT a b m c -> SplineT a b m (Maybe b, c)

Capture the spline's last output value and tuple it with the spline's result. This is helpful when you want to sample the last output value in order to determine the next spline to sequence.

mapOutput :: (Applicative m, Monad m) => VarT m a (b -> t) -> SplineT a b m c -> SplineT a t m c

Map the output value of a spline.

adjustInput :: Monad m => VarT m a (a -> r) -> SplineT r b m c -> SplineT a b m c

Map the input value of a spline.

Step

data Step b c

A discrete step in a continuous function. This type discretely describes an eventual value on the right and an output value on the left.

Constructors

Step

Fields

stepOutput :: b

stepResult :: Event c

Instances

Functor (Step a)

A discrete step is a functor by applying a function to the contained event's value.

Monoid f => Applicative (Step f)

A discrete spline is an applicative if its left datatype is a monoid. It replies to pure with an empty left value while the right value is the argument wrapped in an event. It means "the argument happens instantly".

(Monoid f, Monoid b) => Monoid (Step f b)

A discrete spline is a monoid if its left and right types are monoids.