-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Simple foundation for functional reactive programming -- -- Reactive is a simple foundation for programming reactive -- systems functionally. Like Fran/FRP, it has a notions of (reactive) -- behaviors and events. Like DataDriven, Reactive has a data-driven -- implementation. The main difference between Reactive and DataDriven is -- that Reactive builds on functional "futures" (using threading), while -- DataDriven builds on continuation-based computations. -- -- Please see the project wiki page: -- http://haskell.org/haskellwiki/reactive -- -- The module documentation pages have links to colorized source code and -- to wiki pages where you can read and contribute user comments. Enjoy! -- -- © 2007 by Conal Elliott; BSD3 license. @package reactive @version 0.5.0.1 -- | Functions, with constant functions optimized. With instances of -- Functor, Applicative, Monad, and Arrow module Data.Fun -- | Constant-optimized functions data Fun t a -- | constant function K :: a -> Fun t a -- | non-constant function Fun :: (t -> a) -> Fun t a -- | Fun as a function apply :: Fun t a -> (t -> a) instance Arrow Fun instance Category Fun instance Monad (Fun t) instance Applicative (Fun t) instance Functor (Fun t) instance Monoid a => Monoid (Fun t a) -- | A future value is a value that will become knowable only later. -- This module gives a way to manipulate them functionally. For instance, -- a+b becomes knowable when the later of a and -- b becomes knowable. See -- http://en.wikipedia.org/wiki/Futures_and_promises. -- -- Primitive futures can be things like /the value of the next key you -- press, or the value of LambdaPix stock at noon next Monday/. -- -- Composition is via standard type classes: Functor, -- Applicative, Monad, and Monoid. Some comments on -- the Future instances of these classes: -- --

Monoid: mempty is a future that never becomes knowable. -- a mappend b is whichever of a and b -- is knowable first.
Functor: apply a function to a future. The result is -- knowable when the given future is knowable.
Applicative: pure gives value knowable since the -- beginning of time. '(<*>)' applies a future function to a future -- argument. Result available when both are available, i.e., it -- becomes knowable when the later of the two futures becomes -- knowable.
Monad: return is the same as pure (as -- always). (>>=) cascades futures. join resolves a -- future future into a future.

-- -- The current implementation is nondeterministic in mappend for -- futures that become knowable at the same time or nearly the same time. -- I want to make a deterministic implementation. -- -- See Data.SFuture for a simple denotational semantics of -- futures. The current implementation does not quite implement -- this target semantics for mappend when futures are available -- simultaneously or nearly simultaneously. I'm still noodling how to -- implement that semantics. module Data.Future -- | Value available in the future. data Future a -- | Future that may arrive. The IO blocks until available. No -- side-effect. Future :: (IO a) -> Future a -- | Future that never arrives. Never :: Future a -- | Access a future value. Blocks until available. force :: Future a -> IO a -- | Make a Future and a way to fill it. The filler should be -- invoked only once. newFuture :: IO (Future a, a -> IO ()) -- | Make a Future, given a way to compute a value. future :: IO a -> Future a -- | Run an IO-action-valued Future. runFuture :: Future (IO ()) -> IO () instance Monoid (Future a) instance Monad Future instance Applicative Future instance Functor Future -- | Functional events and reactive values. An Event -- is stream of future values in time order. A Reactive value is a -- discretly time-varying value. These two types are closely linked: a -- reactive value is defined by an initial value and an event that yields -- future values; while an event is simply a future reactive value. -- -- Many of the operations on events and reactive values are packaged as -- instances of the standard type classes Monoid, Functor, -- Applicative, and Monad. -- -- Although the basic Reactive type describes -- discretely-changing values, continuously-changing values -- are modeled simply as reactive functions. For convenience, this module -- defines ReactiveB as a type composition of Reactive and -- a constant-optimized representation of functions of time. -- -- The exact packaging of discrete vs continuous will probably change -- with more experience. module Data.Reactive -- | Event, i.e., a stream of future values. Instances: -- --

Monoid: mempty is the event that never occurs, and -- e mappend e' is the event that combines occurrences -- from e and e'. (Fran's neverE and -- (.|.).)
Functor: fmap f e is the event that occurs -- whenever e occurs, and whose occurrence values come from -- applying f to the values from e. (Fran's -- (==>).)
Applicative: pure a is an event with a single -- occurrence, available from the beginning of time. ef <*> -- ex is an event whose occurrences are made from the product -- of the occurrences of ef and ex. For every -- occurrence f at time tf of ef and -- occurrence x at time tx of ex, ef -- <*> ex has an occurrence f x at time max tf -- tx.
Monad: return a is the same as pure a (as -- always). In e >>= f, each occurrence of e -- leads, through f, to a new event. Similarly for join -- ee, which is somehow simpler for me to think about. The -- occurrences of e >>= f (or join ee) correspond -- to the union of the occurrences of all such events. For example, -- suppose we're playing Asteroids and tracking collisions. Each -- collision can break an asteroid into more of them, each of which has -- to be tracked for more collisions. Another example: A chat room has an -- enter event, whose occurrences contain new events like -- speak. An especially useful monad-based function is -- joinMaybes, which filters a Maybe-valued event.

newtype Event a Event :: Future (Reactive a) -> Event a eFuture :: Event a -> Future (Reactive a) -- | Reactive value: a discretely changing value. Reactive values can be -- understood in terms of (a) a simple denotational semantics of reactive -- values as functions of time, and (b) the corresponding instances for -- functions. The semantics is given by the function (%$) :: Reactive -- a -> (Time -> a). A reactive value also has a current value -- and an event (stream of future values). -- -- Instances for Reactive -- --

Monoid: a typical lifted monoid. If o is a monoid, -- then Reactive o is a monoid, with mempty = pure -- mempty, and mappend = liftA2 mappend. In other words, -- mempty %$ t == mempty, and (r mappend s) %$ t == -- (r %$ t) mappend (s %$ t).
Functor: fmap f r %$ t == f (r %$ t).
Applicative: pure a %$ t == a, and (s -- <*> r) %$ t == (s %$ t) (r %$ t).
Monad: return a %$ t == a, and join rr %$ t == -- (rr %$ t) %$ t. As always, (r >>= f) == join (fmap f -- r).

data Reactive a Stepper :: a -> Event a -> Reactive a -- | initial value rInit :: Reactive a -> a -- | waiting for event rEvent :: Reactive a -> Event a -- | Compatibility synonym (for ease of transition from DataDriven) type Source = Reactive -- | Apply a unary function inside an Event representation. inEvent :: (Future (Reactive a) -> Future (Reactive b)) -> (Event a -> Event b) -- | Apply a unary function inside an Event representation. inEvent2 :: (Future (Reactive a) -> Future (Reactive b) -> Future (Reactive c)) -> (Event a -> Event b -> Event c) -- | Reactive value from an initial value and a new-value event. stepper :: a -> Event a -> Reactive a -- | Switch between reactive values. switcher :: Reactive a -> Event (Reactive a) -> Reactive a -- | Make an event and a sink for feeding the event. Each value sent to the -- sink becomes an occurrence of the event. mkEvent :: IO (Event a, Sink a) -- | Tracing variant of mkEvent mkEventTrace :: (a -> String) -> IO (Event a, Sink a) -- | Show specialization of mkEventTrace mkEventShow :: Show a => String -> IO (Event a, Sink a) -- | Run an event in the current thread. runE :: Event (IO b) -> IO a -- | Run an event in a new thread. forkE :: Event (IO b) -> IO ThreadId -- | Subscribe a listener to an event. Wrapper around forkE and -- fmap. subscribe :: Event a -> Sink a -> IO ThreadId -- | Run a reactive value in a new thread. The initial action happens in -- the current thread. forkR :: Reactive (IO b) -> IO ThreadId -- | Accumulating event, starting from an initial value and a -- update-function event. See also accumR. accumE :: a -> Event (a -> a) -> Event a -- | Like scanl for events. See also scanlR. scanlE :: (a -> b -> a) -> a -> Event b -> Event a -- | Accumulate values from a monoid-valued event. Specialization of -- scanlE, using mappend and mempty. See also -- monoidR. monoidE :: Monoid o => Event o -> Event o -- | Pair each event value with the previous one, given an initial value. withPrevE :: Event a -> Event (a, a) -- | Count occurrences of an event, remembering the occurrence values. See -- also countE_. countE :: Num n => Event b -> Event (b, n) -- | Count occurrences of an event, forgetting the occurrence values. See -- also countE. See also countR. countE_ :: Num n => Event b -> Event n -- | Difference of successive event occurrences. diffE :: Num n => Event n -> Event n -- | Snapshot a reactive value whenever an event occurs. snapshot :: Event a -> Reactive b -> Event (a, b) -- | Like snapshot but discarding event data (often a is -- ()). snapshot_ :: Event a -> Reactive b -> Event b -- | Filter an event according to whether a boolean source is true. whenE :: Event a -> Reactive Bool -> Event a -- | Just the first occurrence of an event. once :: Event a -> Event a -- | Tracing of events. traceE :: (a -> String) -> Unop (Event a) -- | Make an extensible event. The returned sink is a way to add new events -- to mix. You can often use '(>>=)' or join instead. -- Warning: this function might be removed at some point. eventX :: IO (Event a, Sink (Event a)) mkReactive :: a -> IO (Reactive a, Sink a) -- | Reactive value from an initial value and an updater event. See also -- accumE. accumR :: a -> Event (a -> a) -> Reactive a -- | Like scanl for reactive values. See also scanlE. scanlR :: (a -> b -> a) -> a -> Event b -> Reactive a -- | Accumulate values from a monoid-valued event. Specialization of -- scanlE, using mappend and mempty. See also -- monoidE. monoidR :: Monoid a => Event a -> Reactive a -- | Start out blank (Nothing), latching onto each new a, -- and blanking on each b. If you just want to latch and not -- blank, then use mempty for lose. maybeR :: Event a -> Event b -> Reactive (Maybe a) -- | Flip-flopping source. Turns true when ea occurs and false -- when eb occurs. flipFlop :: Event a -> Event b -> Reactive Bool -- | Count occurrences of an event. See also countE. countR :: Num n => Event a -> Reactive n -- | Tracing of reactive values traceR :: (a -> String) -> Unop (Reactive a) -- | Time for continuous behaviors type Time = Double -- | Reactive behaviors. Simply a reactive Function value. Wrapped -- in a type composition to get Functor and Applicative for -- free. type ReactiveB = Reactive :. Fun Time -- | Replace a functor value with a given one. replace :: Functor f => b -> f a -> f b -- | Forget a functor value, replace with () forget :: Functor f => f a -> f () -- | Convenient alias for dropping parentheses. type Action = IO () -- | Value sink type Sink a = a -> Action -- | Pass through Just occurrences. joinMaybes :: MonadPlus m => m (Maybe a) -> m a -- | Pass through values satisfying p. filterMP :: MonadPlus m => (a -> Bool) -> m a -> m a instance Unpair Event instance Copair f => Pair (Event :. f) instance Monoid_f (Event :. f) instance Monoid ((:.) Event f a) instance Monoid_f Event instance Unpair Reactive instance Pair f => Pair (Reactive :. f) instance Monoid_f f => Monoid_f (Reactive :. f) instance Pair Reactive instance Monad Reactive instance MonadPlus Event instance Monad Event instance Applicative Reactive instance Applicative Event instance Functor Reactive instance Functor Event instance Monoid a => Monoid (Reactive a) instance Monoid (Event a) -- | A sort of semantic prototype for functional futures, roughly as -- described at http://en.wikipedia.org/wiki/Futures_and_promises. -- -- A future is a value that will become knowable only later. This -- module gives a way to manipulate them functionally. For instance, -- a+b becomes knowable when the later of a and -- b becomes knowable. -- -- Primitive futures can be things like /the value of the next key you -- press, or the value of LambdaPix stock at noon next Monday/. -- -- Composition is via standard type classes: Ord, Functor, -- Applicative, Monad, and Monoid. Some comments on -- the Future instances of these classes: -- --

Ord: a min b is whichever of a and -- b is knowable first. a max b is whichever of -- a and b is knowable last.
Monoid: mempty is a future that never becomes knowable. -- mappend is the same as min.
Functor: apply a function to a future. The result is -- knowable when the given future is knowable.
Applicative: pure gives value knowable since the -- beginning of time. '(<*>)' applies a future function to a future -- argument. Result available when both are available, i.e., it -- becomes knowable when the later of the two futures becomes -- knowable.
Monad: return is the same as pure (as -- always). (>>=) cascades futures. join resolves -- a future future value into a future value.

-- -- Futures are parametric over time as well as value types. -- The time parameter can be any ordered type. -- -- Please keep in mind that this module specifies the interface and -- semantics, rather than a useful implementation. See Data.Future -- for an implementation that nearly implements the semantics described -- here. -- -- On second thought, I'm experimenting with using this module in an -- usable implementation of events. See Data.MEvent. module Data.SFuture -- | Time of some event occurrence, which can be any Ord type. In -- an actual implementation, we would not usually have access to the time -- value until (slightly after) that time. Extracting the actual time -- would block until the time is known. The added bounds represent -- -Infinity and +Infinity. Pure values have time minBound (-Infinity), -- while eternally unknowable values (non-occurring events) have time -- maxBound (+Infinity). type Time t = Max (AddBounds t) -- | A future value of type a with time type t. -- Semantically, just a time/value pair, but those values would not be -- available until forced, which could block. newtype Future t a Future :: (Time t, a) -> Future t a unFuture :: Future t a -> (Time t, a) -- | A future's time futTime :: Future t a -> Time t -- | A future's value futVal :: Future t a -> a -- | Make a future container into a container of futures. sequenceF :: Functor f => Future t (f a) -> f (Future t a) -- | Ordered monoid under max. newtype Max a Max :: a -> Max a getMax :: Max a -> a -- | Ordered monoid under min. newtype Min a Min :: a -> Min a getMin :: Min a -> a -- | Wrap a type into one having new least and greatest elements, -- preserving the existing ordering. data AddBounds a MinBound :: AddBounds a NoBound :: a -> AddBounds a MaxBound :: AddBounds a instance Eq a => Eq (Max a) instance Ord a => Ord (Max a) instance Read a => Read (Max a) instance Show a => Show (Max a) instance Bounded a => Bounded (Max a) instance Eq a => Eq (Min a) instance Ord a => Ord (Min a) instance Read a => Read (Min a) instance Show a => Show (Min a) instance Bounded a => Bounded (Min a) instance Eq a => Eq (AddBounds a) instance Ord a => Ord (AddBounds a) instance Read a => Read (AddBounds a) instance Show a => Show (AddBounds a) instance Functor (Future t) instance Ord t => Applicative (Future t) instance Ord t => Monad (Future t) instance (Show t, Show a) => Show (Future t a) instance Bounded (AddBounds a) instance Monoid o => Monad ((,) o) instance (Ord a, Bounded a) => Monoid (Min a) instance (Ord a, Bounded a) => Monoid (Max a) instance Ord t => Monoid (Future t a) instance Ord t => Ord (Future t a) instance Eq (Future t a)