Control.Varying.Spline

Using splines we can easily create continuously varying values 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 do-notation computation completes and returns a result value. That result value is then used to determine the next spline in the sequence. This allows us to build up long, complex behaviors sequentially using a very familiar notation that can be easily turned into a continuously varying value.

Spline

type Spline m a b c = SplineT m Event a b c

Spline is a specialized SplineT that uses Event as its output container. This means that new values overwrite/replace old values due to Event's Last-like monoid instance.

runSpline :: (Applicative m, Monad m) => Spline m a b c -> Var m a (Step (Event b) c)

Unwrap a spline into a varying value. This is an alias of runSplineT.

execSpline :: (Applicative m, Monad m) => b -> Spline m a b c -> Var m a b

Using a default start value, evaluate the spline to a varying value. A spline is only defined over a finite domain so we must supply a default value to use before the spline produces its first output value.

spline :: (Applicative m, Monad m) => b -> Var m a (Event b) -> Spline m a b 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 value is the last output value.

Spline Transformer

data SplineT m f a b c

SplineT shares a number of types with Var, specifically its monad, input and output types (m, a and b, respectively). A spline adds a container type that determines how empty output values should be created, appended and applied (the type must be monoidal and applicative). It also 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 return 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 :: Var m a (Step (f b) c)

SplineTConst c

Instances

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

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.

Methods

(>>=) :: SplineT m f a b c -> (c -> SplineT m f a b d) -> SplineT m f a b d

(>>) :: SplineT m f a b c -> SplineT m f a b d -> SplineT m f a b d

return :: c -> SplineT m f a b c

fail :: String -> SplineT m f a b c

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

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

Methods

fmap :: (c -> d) -> SplineT m f a b c -> SplineT m f a b d

(<$) :: c -> SplineT m f a b d -> SplineT m f a b c

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

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.

Methods

pure :: c -> SplineT m f a b c

(<*>) :: SplineT m f a b (c -> d) -> SplineT m f a b c -> SplineT m f a b d

(*>) :: SplineT m f a b c -> SplineT m f a b d -> SplineT m f a b d

(<*) :: SplineT m f a b c -> SplineT m f a b d -> SplineT m f a b c

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

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.

Methods

liftIO :: IO c -> SplineT m f a b c

runSplineT :: (Applicative m, Monad m, Monoid (f b)) => SplineT m f a b c -> Var m a (Step (f b) c)

Unwrap a spline into a varying value.

evalSplineT :: (Applicative m, Monad m, Monoid (f b)) => SplineT m f a b c -> Var m a (Event c)

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

execSplineT :: (Applicative m, Monad m, Monoid (f b)) => SplineT m f a b c -> Var m a (f b)

Evaluates a spline to a varying value of its output type.

varyUntilEvent :: (Applicative m, Monad m) => Var m a b -> Var m a (Event c) -> (b -> c -> d) -> Spline m a b d

Create a spline from a varying value and an event stream. The spline uses the varying value 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 used in a merge function to produce the spline's result value.

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

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

Step

data Step f b where

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

Constructors

Step :: Monoid f => f -> Event b -> Step f b

Instances

Functor (Step f)

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

Methods

fmap :: (a -> b) -> Step f a -> Step f b

(<$) :: a -> Step f b -> Step f a

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".

Methods

pure :: a -> Step f a

(<*>) :: Step f (a -> b) -> Step f a -> Step f b

(*>) :: Step f a -> Step f b -> Step f b

(<*) :: Step f a -> Step f b -> Step f a

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

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

Methods

mempty :: Step f b

mappend :: Step f b -> Step f b -> Step f b

mconcat :: [Step f b] -> Step f b