Reactive.Banana.Combinators

Synopsis

The main types and combinators of Functional Reactive Programming (FRP).

At its core, FRP is about two data types Event and Behavior and the various ways to combine them. There is also a third type Moment, which is necessary for the higher-order combinators.

Core Combinators

Event and Behavior

data Event a

Event a represents a stream of events as they occur in time. Semantically, you can think of Event a as an infinite list of values that are tagged with their corresponding time of occurrence,

type Event a = [(Time,a)]

Each pair is called an event occurrence. Note that within a single event stream, no two event occurrences may happen at the same time.

Instances

Functor Event

The function fmap applies a function f to every value. Semantically,

fmap :: (a -> b) -> Event a -> Event b
fmap f e = [(time, f a) | (time, a) <- e]

Defined in Reactive.Banana.Types

Methods

fmap :: (a -> b) -> Event a -> Event b

(<$) :: a -> Event b -> Event a

Semigroup a => Monoid (Event a)

The combinator mempty represents an event that never occurs. It is a synonym,

mempty :: Event a
mempty = never

Defined in Reactive.Banana.Types

Methods

mempty :: Event a

mappend :: Event a -> Event a -> Event a

mconcat :: [Event a] -> Event a

Semigroup a => Semigroup (Event a)

The combinator <> merges two event streams of the same type. In case of simultaneous occurrences, the events are combined with the underlying Semigroup operation. Semantically,

(<>) :: Event a -> Event a -> Event a
(<>) ex ey = unionWith (<>) ex ey

Defined in Reactive.Banana.Types

Methods

(<>) :: Event a -> Event a -> Event a

sconcat :: NonEmpty (Event a) -> Event a

stimes :: Integral b => b -> Event a -> Event a

data Behavior a

Behavior a represents a value that varies in time. Semantically, you can think of it as a function

type Behavior a = Time -> a

Instances

Applicative Behavior

The function pure returns a value that is constant in time. Semantically,

pure     :: a -> Behavior a
pure x    = \time -> x

The combinator <*> applies a time-varying function to a time-varying value.

(<*>)    :: Behavior (a -> b) -> Behavior a -> Behavior b
fx <*> bx = \time -> fx time $ bx time

Defined in Reactive.Banana.Types

Methods

pure :: a -> Behavior a

(<*>) :: Behavior (a -> b) -> Behavior a -> Behavior b

liftA2 :: (a -> b -> c) -> Behavior a -> Behavior b -> Behavior c

(*>) :: Behavior a -> Behavior b -> Behavior b

(<*) :: Behavior a -> Behavior b -> Behavior a

Functor Behavior

The function fmap applies a function f at every point in time. Semantically,

fmap :: (a -> b) -> Behavior a -> Behavior b
fmap f b = \time -> f (b time)

Defined in Reactive.Banana.Types

Methods

fmap :: (a -> b) -> Behavior a -> Behavior b

(<$) :: a -> Behavior b -> Behavior a

IsString a => IsString (Behavior a)

Defined in Reactive.Banana.Types

Methods

fromString :: String -> Behavior a

(Semigroup a, Monoid a) => Monoid (Behavior a)

Defined in Reactive.Banana.Types

Methods

mempty :: Behavior a

mappend :: Behavior a -> Behavior a -> Behavior a

mconcat :: [Behavior a] -> Behavior a

Semigroup a => Semigroup (Behavior a)

Defined in Reactive.Banana.Types

Methods

(<>) :: Behavior a -> Behavior a -> Behavior a

sconcat :: NonEmpty (Behavior a) -> Behavior a

stimes :: Integral b => b -> Behavior a -> Behavior a

Floating a => Floating (Behavior a)

Defined in Reactive.Banana.Types

Methods

pi :: Behavior a

exp :: Behavior a -> Behavior a

log :: Behavior a -> Behavior a

sqrt :: Behavior a -> Behavior a

(**) :: Behavior a -> Behavior a -> Behavior a

logBase :: Behavior a -> Behavior a -> Behavior a

sin :: Behavior a -> Behavior a

cos :: Behavior a -> Behavior a

tan :: Behavior a -> Behavior a

asin :: Behavior a -> Behavior a

acos :: Behavior a -> Behavior a

atan :: Behavior a -> Behavior a

sinh :: Behavior a -> Behavior a

cosh :: Behavior a -> Behavior a

tanh :: Behavior a -> Behavior a

asinh :: Behavior a -> Behavior a

acosh :: Behavior a -> Behavior a

atanh :: Behavior a -> Behavior a

log1p :: Behavior a -> Behavior a

expm1 :: Behavior a -> Behavior a

log1pexp :: Behavior a -> Behavior a

log1mexp :: Behavior a -> Behavior a

Num a => Num (Behavior a)

Defined in Reactive.Banana.Types

Methods

(+) :: Behavior a -> Behavior a -> Behavior a

(-) :: Behavior a -> Behavior a -> Behavior a

(*) :: Behavior a -> Behavior a -> Behavior a

negate :: Behavior a -> Behavior a

abs :: Behavior a -> Behavior a

signum :: Behavior a -> Behavior a

fromInteger :: Integer -> Behavior a

Fractional a => Fractional (Behavior a)

Defined in Reactive.Banana.Types

Methods

(/) :: Behavior a -> Behavior a -> Behavior a

recip :: Behavior a -> Behavior a

fromRational :: Rational -> Behavior a

interpret :: (Event a -> Moment (Event b)) -> [Maybe a] -> IO [Maybe b]

Interpret an event processing function. Useful for testing.

Note: You can safely assume that this function is pure, even though the type seems to suggest otherwise. I'm really sorry about the extra IO, but it can't be helped. See source code for the sordid details.

First-order

This subsections lists the primitive first-order combinators for FRP. The Functor, Applicative and Monoid instances are also part of this, but they are documented at the types Event and Behavior.

module Control.Applicative

module Data.Semigroup

never :: Event a

Event that never occurs. Semantically,

never = []

unionWith :: (a -> a -> a) -> Event a -> Event a -> Event a

Merge two event streams of the same type. The function argument specifies how event values are to be combined in case of a simultaneous occurrence. The semantics are

unionWith f ((timex,x):xs) ((timey,y):ys)
   | timex <  timey = (timex,x)     : unionWith f xs ((timey,y):ys)
   | timex >  timey = (timey,y)     : unionWith f ((timex,x):xs) ys
   | timex == timey = (timex,f x y) : unionWith f xs ys

filterE :: (a -> Bool) -> Event a -> Event a

Allow all events that fulfill the predicate, discard the rest. Semantically,

filterE p es = [(time,a) | (time,a) <- es, p a]

apply :: Behavior (a -> b) -> Event a -> Event b

Apply a time-varying function to a stream of events. Semantically,

apply bf ex = [(time, bf time x) | (time, x) <- ex]

This function is generally used in its infix variant <@>.

Moment and accumulation

data Moment a

The Moment monad denotes a pure computation that happens at one particular moment in time. Semantically, it is a reader monad

type Moment a = Time -> a

When run, the argument tells the time at which this computation happens.

Note that in this context, time really means to logical time. Of course, every calculation on a computer takes some amount of wall-clock time to complete. Instead, what is meant here is the time as it relates to Events and Behaviors. We use the fiction that every calculation within the Moment monad takes zero logical time to perform.

Instances

MonadFix Moment

Defined in Reactive.Banana.Types

Methods

mfix :: (a -> Moment a) -> Moment a

Applicative Moment

Defined in Reactive.Banana.Types

Methods

pure :: a -> Moment a

(<*>) :: Moment (a -> b) -> Moment a -> Moment b

liftA2 :: (a -> b -> c) -> Moment a -> Moment b -> Moment c

(*>) :: Moment a -> Moment b -> Moment b

(<*) :: Moment a -> Moment b -> Moment a

Functor Moment

Defined in Reactive.Banana.Types

Methods

fmap :: (a -> b) -> Moment a -> Moment b

(<$) :: a -> Moment b -> Moment a

Monad Moment

Defined in Reactive.Banana.Types

Methods

(>>=) :: Moment a -> (a -> Moment b) -> Moment b

(>>) :: Moment a -> Moment b -> Moment b

return :: a -> Moment a

MonadMoment Moment

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> Moment a

Monoid a => Monoid (Moment a)

Defined in Reactive.Banana.Types

Methods

mempty :: Moment a

mappend :: Moment a -> Moment a -> Moment a

mconcat :: [Moment a] -> Moment a

Semigroup a => Semigroup (Moment a)

Defined in Reactive.Banana.Types

Methods

(<>) :: Moment a -> Moment a -> Moment a

sconcat :: NonEmpty (Moment a) -> Moment a

stimes :: Integral b => b -> Moment a -> Moment a

class MonadFix m => MonadMoment m where

An instance of the MonadMoment class denotes a computation that happens at one particular moment in time. Unlike the Moment monad, it need not be pure anymore.

Methods

liftMoment :: Moment a -> m a

Instances

MonadMoment Moment

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> Moment a

MonadMoment MomentIO

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> MomentIO a

MonadMoment m => MonadMoment (MaybeT m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> MaybeT m a

(MonadMoment m, Monoid w) => MonadMoment (AccumT w m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> AccumT w m a

MonadMoment m => MonadMoment (ExceptT e m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> ExceptT e m a

MonadMoment m => MonadMoment (IdentityT m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> IdentityT m a

MonadMoment m => MonadMoment (ReaderT r m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> ReaderT r m a

MonadMoment m => MonadMoment (StateT s m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> StateT s m a

MonadMoment m => MonadMoment (StateT s m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> StateT s m a

MonadMoment m => MonadMoment (WriterT w m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> WriterT w m a

(MonadMoment m, Monoid w) => MonadMoment (WriterT w m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> WriterT w m a

(MonadMoment m, Monoid w) => MonadMoment (WriterT w m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> WriterT w m a

MonadMoment m => MonadMoment (RWST r w s m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> RWST r w s m a

(MonadMoment m, Monoid w) => MonadMoment (RWST r w s m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> RWST r w s m a

(MonadMoment m, Monoid w) => MonadMoment (RWST r w s m)

Defined in Reactive.Banana.Types

Methods

liftMoment :: Moment a -> RWST r w s m a

accumE :: MonadMoment m => a -> Event (a -> a) -> m (Event a)

The accumE function accumulates a stream of event values, similar to a strict left scan, scanl'. It starts with an initial value and emits a new value whenever an event occurrence happens. The new value is calculated by applying the function in the event to the old value.

Example:

accumE "x" [(time1,(++"y")),(time2,(++"z"))]
    = trimE [(time1,"xy"),(time2,"xyz")]
    where
    trimE e start = [(time,x) | (time,x) <- e, start <= time]

stepper :: MonadMoment m => a -> Event a -> m (Behavior a)

Construct a time-varying function from an initial value and a stream of new values. The result will be a step function. Semantically,

stepper x0 ex = \time1 -> \time2 ->
    last (x0 : [x | (timex,x) <- ex, time1 <= timex, timex < time2])

Here is an illustration of the result Behavior at a particular time:

Note: The smaller-than-sign in the comparison timex < time2 means that at time time2 == timex, the value of the Behavior will still be the previous value. In the illustration, this is indicated by the dots at the end of each step. This allows for recursive definitions. See the discussion below for more on recursion.

Recursion

Recursion is a very important technique in FRP that is not apparent from the type signatures.

Here is a prototypical example. It shows how the accumE can be expressed in terms of the stepper and apply functions by using recursion:

accumE a e1 = mdo
   let e2 = (\a f -> f a) <$> b <@> e1
   b <- stepper a e2
   return e2

(The mdo notation refers to value recursion in a monad. The MonadFix instance for the Moment class enables this kind of recursive code.) (Strictly speaking, this also means that accumE is not a primitive, because it can be expressed in terms of other combinators.)

This general pattern appears very often in practice: A Behavior (here b) controls what value is put into an Event (here e2), but at the same time, the Event contributes to changes in this Behavior. Modeling this situation requires recursion.

For another example, consider a vending machine that sells banana juice. The amount that the customer still has to pay for a juice is modeled by a Behavior bAmount. Whenever the customer inserts a coin into the machine, an Event eCoin occurs, and the amount will be reduced. Whenver the amount goes below zero, an Event eSold will occur, indicating the release of a bottle of fresh banana juice, and the amount to be paid will be reset to the original price. The model requires recursion, and can be expressed in code as follows:

mdo
    let price = 50 :: Int
    bAmount  <- accumB price $ unions
                  [ subtract 10 <$ eCoin
                  , const price <$ eSold ]
    let eSold = whenE ((<= 0) <$> bAmount) eCoin

On one hand, the Behavior bAmount controls whether the Event eSold occcurs at all; the bottle of banana juice is unavailable to penniless customers. But at the same time, the Event eSold will cause a reset of the Behavior bAmount, so both depend on each other.

Recursive code like this examples works thanks to the semantics of stepper. In general, mutual recursion between several Events and Behaviors is always well-defined, as long as an Event depends on itself only via a Behavior, and vice versa.

Higher-order

valueB :: MonadMoment m => Behavior a -> m a

Obtain the value of the Behavior at a given moment in time. Semantically, it corresponds to

valueB b = \time -> b time

Note: The value is immediately available for pattern matching. Unfortunately, this means that valueB is unsuitable for use with value recursion in the Moment monad. If you need recursion, please use valueBLater instead.

valueBLater :: MonadMoment m => Behavior a -> m a

Obtain the value of the Behavior at a given moment in time. Semantically, it corresponds to

valueBLater b = \time -> b time

Note: To allow for more recursion, the value is returned lazily and not available for pattern matching immediately. It can be used safely with most combinators like stepper. If that doesn't work for you, please use valueB instead.

observeE :: Event (Moment a) -> Event a

Observe a value at those moments in time where event occurrences happen. Semantically,

observeE e = [(time, m time) | (time, m) <- e]

switchE :: MonadMoment m => Event a -> Event (Event a) -> m (Event a)

Dynamically switch between Event. Semantically,

switchE e0 ee0 time0 =
    concat [ trim t1 t2 e | (t1,t2,e) <- intervals ee ]
  where
    laterThan e time0  = [(timex,x) | (timex,x) <- e, time0 < timex ]
    ee                 = [(time0, e0)] ++ (ee0 `laterThan` time0)
    intervals ee       = [(time1, time2, e) | ((time1,e),(time2,_)) <- zip ee (tail ee)]
    trim time1 time2 e = [x | (timex,x) <- e, time1 < timex, timex <= time2]

switchB :: MonadMoment m => Behavior a -> Event (Behavior a) -> m (Behavior a)

Dynamically switch between Behavior. Semantically,

 switchB b0 eb = \time0 -> \time1 ->
    last (b0 : [b | (timeb,b) <- eb, time0 <= timeb, timeb < time1]) time1

Derived Combinators

Infix operators

(<@>) :: Behavior (a -> b) -> Event a -> Event b infixl 4

Infix synonym for the apply combinator. Similar to <*>.

infixl 4 <@>

(<@) :: Behavior b -> Event a -> Event b infixl 4

Tag all event occurrences with a time-varying value. Similar to <*.

infixl 4 <@

(@>) :: Event a -> Behavior b -> Event b infixl 4

Tag all event occurences with a time-varying value. Similar to *>.

This is the flipped version of <@, but can be useful when combined with ApplicativeDo to sample from multiple Behaviors:

reactimate $ onEvent @> do
  x <- behavior1
  y <- behavior2
  return (print (x + y))

Filtering

filterJust :: Event (Maybe a) -> Event a

Allow all event occurrences that are Just values, discard the rest. Variant of filterE.

filterApply :: Behavior (a -> Bool) -> Event a -> Event a

Allow all events that fulfill the time-varying predicate, discard the rest. Generalization of filterE.

whenE :: Behavior Bool -> Event a -> Event a

Allow events only when the behavior is True. Variant of filterApply.

split :: Event (Either a b) -> (Event a, Event b)

Split event occurrences according to a tag. The Left values go into the left component while the Right values go into the right component of the result.

once :: MonadMoment m => Event a -> m (Event a)

Keep only the next occurence of an event.

once also aids the garbage collector by indicating that the result event can be discarded after its only occurrence.

once e = \time0 -> take 1 [(t, a) | (t, a) <- e, time0 <= t]

Accumulation

Note: All accumulation functions are strict in the accumulated value!

Note: The order of arguments is acc -> (x,acc) which is also the convention used by unfoldr and State.

unions :: [Event (a -> a)] -> Event (a -> a)

Merge event streams whose values are functions. In case of simultaneous occurrences, the functions at the beginning of the list are applied after the functions at the end.

unions [] = never
unions xs = foldr1 (unionWith (.)) xs

Very useful in conjunction with accumulation functions like accumB and accumE.

accumB :: MonadMoment m => a -> Event (a -> a) -> m (Behavior a)

The accumB function accumulates event occurrences into a Behavior.

The value is accumulated using accumE and converted into a time-varying value using stepper.

Example:

accumB "x" [(time1,(++"y")),(time2,(++"z"))]
   = stepper "x" [(time1,"xy"),(time2,"xyz")]

Note: As with stepper, the value of the behavior changes "slightly after" the events occur. This allows for recursive definitions.

mapAccum :: MonadMoment m => acc -> Event (acc -> (x, acc)) -> m (Event x, Behavior acc)

Efficient combination of accumE and accumB.

Merging events

merge :: Event a -> Event b -> Event (These a b)

Merge two event streams of any type.

mergeWith

Arguments

:: (a -> c)

The function called when only the first event emits a value.

-> (b -> c)

The function called when only the second event emits a value.

-> (a -> b -> c)

The function called when both events emit values simultaneously.

-> Event a

-> Event b

-> Event c

Merge two event streams of any type.

This function generalizes unionWith.