-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Practical library for functional reactive programming (FRP).
--   
--   Reactive-banana is a practical library for Functional Reactive
--   Programming (FRP).
--   
--   FRP offers an elegant and concise way to express interactive programs
--   such as graphical user interfaces, animations, computer music or robot
--   controllers. Thus, the reactive-banana library promises to avoid the
--   spaghetti code commonly used in traditional GUI technologies.
--   
--   See the project homepage
--   <a>http://haskell.org/haskellwiki/Reactive-banana</a> for a more
--   detailed introduction and features.
--   
--   Stability forecast: No semantic bugs expected. Significant API changes
--   are likely in future versions, though the main interface is beginning
--   to stabilize. The <tt>Reactive.Banana.Switch</tt> module is quite
--   experimental. There is currently <i>no</i> garbage collection for
--   dynamically created events.
@package reactive-banana
@version 0.7.1.3

module Reactive.Banana.Model
type Event a = [Maybe a]
data Behavior a
never :: Event a
filterJust :: Event (Maybe a) -> Event a
unionWith :: (a -> a -> a) -> Event a -> Event a -> Event a
mapE :: (a -> b) -> Event a -> Event b
accumE :: a -> Event (a -> a) -> Event a
applyE :: Behavior (a -> b) -> Event a -> Event b
stepperB :: a -> Event a -> Behavior a
pureB :: a -> Behavior a
applyB :: Behavior (a -> b) -> Behavior a -> Behavior b
mapB :: (a -> b) -> Behavior a -> Behavior b
type Moment a = Time -> a
initialB :: Behavior a -> Moment a
trimE :: Event a -> Moment (Moment (Event a))
trimB :: Behavior a -> Moment (Moment (Behavior a))
observeE :: Event (Moment a) -> Event a
switchE :: Event (Moment (Event a)) -> Event a
switchB :: Behavior a -> Event (Moment (Behavior a)) -> Behavior a
interpret :: (Event a -> Moment (Event b)) -> [Maybe a] -> [Maybe b]

module Reactive.Banana.Frameworks.AddHandler

-- | A value of type <tt>AddHandler a</tt> is just a facility for
--   registering callback functions, also known as event handlers.
--   
--   The type is a bit mysterious, it works like this:
--   
--   <pre>
--   do unregisterMyHandler &lt;- addHandler myHandler
--   </pre>
--   
--   The argument is an event handler that will be registered. The return
--   value is an action that unregisters this very event handler again.
type AddHandler a = (a -> IO ()) -> IO (IO ())

-- | Build a facility to register and unregister event handlers.
newAddHandler :: IO (AddHandler a, a -> IO ())

-- | Apply a function with side effects to an <a>AddHandler</a>
mapIO :: (a -> IO b) -> AddHandler a -> AddHandler b

-- | Filter event occurrences that don't return <a>True</a>.
filterAddHandler :: (a -> IO Bool) -> AddHandler a -> AddHandler a

module Reactive.Banana.Combinators

-- | <tt>Event t a</tt> represents a stream of events as they occur in
--   time. Semantically, you can think of <tt>Event t a</tt> as an infinite
--   list of values that are tagged with their corresponding time of
--   occurence,
--   
--   <pre>
--   type Event t a = [(Time,a)]
--   </pre>
data Event t a

-- | <tt>Behavior t a</tt> represents a value that varies in time. Think of
--   it as
--   
--   <pre>
--   type Behavior t a = Time -&gt; a
--   </pre>
data Behavior t a

-- | Interpret an event processing function. Useful for testing.
interpret :: (forall t. Event t a -> Event t b) -> [[a]] -> IO [[b]]

-- | Event that never occurs. Think of it as <tt>never = []</tt>.
never :: Event t a

-- | Merge two event streams of the same type. In case of simultaneous
--   occurrences, the left argument comes first. Think of it as
--   
--   <pre>
--   union ((timex,x):xs) ((timey,y):ys)
--      | timex &lt;= timey = (timex,x) : union xs ((timey,y):ys)
--      | timex &gt;  timey = (timey,y) : union ((timex,x):xs) ys
--   </pre>
union :: Event t a -> Event t a -> Event t a

-- | Merge several event streams of the same type.
--   
--   <pre>
--   unions = foldr union never
--   </pre>
unions :: [Event t a] -> Event t a

-- | Allow all events that fulfill the predicate, discard the rest. Think
--   of it as
--   
--   <pre>
--   filterE p es = [(time,a) | (time,a) &lt;- es, p a]
--   </pre>
filterE :: (a -> Bool) -> Event t a -> Event t a

-- | Collect simultaneous event occurences. The result will never contain
--   an empty list. Example:
--   
--   <pre>
--   collect [(time1, e1), (time1, e2)] = [(time1, [e1,e2])]
--   </pre>
collect :: Event t a -> Event t [a]

-- | Emit simultaneous event occurrences. The first element in the list
--   will be emitted first, and so on.
--   
--   Up to strictness, we have
--   
--   <pre>
--   spill . collect = id
--   </pre>
spill :: Event t [a] -> Event t a

-- | The <a>accumE</a> function accumulates a stream of events. Example:
--   
--   <pre>
--   accumE "x" [(time1,(++"y")),(time2,(++"z"))]
--      = [(time1,"xy"),(time2,"xyz")]
--   </pre>
--   
--   Note that the output events are simultaneous with the input events,
--   there is no "delay" like in the case of <a>accumB</a>.
accumE :: a -> Event t (a -> a) -> Event t a

-- | Apply a time-varying function to a stream of events. Think of it as
--   
--   <pre>
--   apply bf ex = [(time, bf time x) | (time, x) &lt;- ex]
--   </pre>
apply :: Behavior t (a -> b) -> Event t a -> Event t b

-- | Construct a time-varying function from an initial value and a stream
--   of new values. Think of it as
--   
--   <pre>
--   stepper x0 ex = \time -&gt; last (x0 : [x | (timex,x) &lt;- ex, timex &lt; time])
--   </pre>
--   
--   Note that the smaller-than-sign in the comparision <tt>timex &lt;
--   time</tt> means that the value of the behavior changes "slightly
--   after" the event occurrences. This allows for recursive definitions.
--   
--   Also note that in the case of simultaneous occurrences, only the last
--   one is kept.
stepper :: a -> Event t a -> Behavior t a

-- | Allow all event occurrences that are <a>Just</a> values, discard the
--   rest. Variant of <a>filterE</a>.
filterJust :: Event t (Maybe a) -> Event t a

-- | Allow all events that fulfill the time-varying predicate, discard the
--   rest. Generalization of <a>filterE</a>.
filterApply :: Behavior t (a -> Bool) -> Event t a -> Event t a

-- | Allow events only when the behavior is <a>True</a>. Variant of
--   <a>filterApply</a>.
whenE :: Behavior t Bool -> Event t a -> Event t a

-- | Split event occurrences according to a tag. The <a>Left</a> values go
--   into the left component while the <a>Right</a> values go into the
--   right component of the result.
split :: Event t (Either a b) -> (Event t a, Event t b)

-- | The <a>accumB</a> function is similar to a <i>strict</i> left fold,
--   <tt>foldl'</tt>. It starts with an initial value and combines it with
--   incoming events. For example, think
--   
--   <pre>
--   accumB "x" [(time1,(++"y")),(time2,(++"z"))]
--      = stepper "x" [(time1,"xy"),(time2,"xyz")]
--   </pre>
--   
--   Note that the value of the behavior changes "slightly after" the
--   events occur. This allows for recursive definitions.
accumB :: a -> Event t (a -> a) -> Behavior t a

-- | Efficient combination of <a>accumE</a> and <a>accumB</a>.
mapAccum :: acc -> Event t (acc -> (x, acc)) -> (Event t x, Behavior t acc)

-- | Keep only the last occurrence when simultaneous occurrences happen.
calm :: Event t a -> Event t a

-- | Combine simultaneous event occurrences into a single occurrence.
--   
--   <pre>
--   unionWith f e1 e2 = fmap (foldr1 f) &lt;$&gt; collect (e1 `union` e2)
--   </pre>
unionWith :: (a -> a -> a) -> Event t a -> Event t a -> Event t a

-- | Class for overloading the <a>apply</a> function.
class (Functor f, Functor g) => Apply f g where f <@ g = (const <$> f) <@> g
(<@>) :: Apply f g => f (a -> b) -> g a -> g b
(<@) :: Apply f g => f a -> g b -> g a
instance Apply (Behavior t) (Event t)
instance Functor (Behavior t)
instance Applicative (Behavior t)
instance Functor (Event t)

module Reactive.Banana.Switch

-- | The <a>Moment</a> monad denotes a value at a particular <i>moment in
--   time</i>.
--   
--   This monad is not very interesting, it is mainly used for
--   book-keeping. In particular, the type parameter <tt>t</tt> is used to
--   disallow various unhealthy programs.
--   
--   This monad is also used to describe event networks in the
--   <a>Reactive.Banana.Frameworks</a> module. This only happens when the
--   type parameter <tt>t</tt> is constrained by the <a>Frameworks</a>
--   class.
--   
--   To be precise, an expression of type <tt>Moment t a</tt> denotes a
--   value of type <tt>a</tt> that is observed at a moment in time which is
--   indicated by the type parameter <tt>t</tt>.
data Moment t a

-- | Value present at any/every moment in time.
data AnyMoment f a
anyMoment :: (forall t. Moment t (f t a)) -> AnyMoment f a
now :: AnyMoment f a -> forall t. Moment t (f t a)

-- | Trim an <a>Event</a> to a variable start time.
trimE :: Event t a -> Moment t (AnyMoment Event a)

-- | Trim a <a>Behavior</a> to a variable start time.
trimB :: Behavior t a -> Moment t (AnyMoment Behavior a)

-- | Dynamically switch between <a>Event</a>.
switchE :: Event t (AnyMoment Event a) -> Event t a

-- | Dynamically switch between <a>Behavior</a>.
switchB :: Behavior t a -> Event t (AnyMoment Behavior a) -> Behavior t a

-- | Observe a value at those moments in time where event occurrences
--   happen.
observeE :: Event t (AnyMoment Identity a) -> Event t a

-- | Obtain the value of the <a>Behavior</a> at moment <tt>t</tt>.
valueB :: Behavior t a -> Moment t a

-- | Identity functor with a dummy argument. Unlike <a>Constant</a>, this
--   functor is constant in the <i>second</i> argument.
newtype Identity t a
Identity :: a -> Identity t a
getIdentity :: Identity t a -> a
instance Applicative (AnyMoment Behavior)
instance Functor (AnyMoment Behavior)
instance Monad (AnyMoment Identity)
instance Functor (Identity t)

module Reactive.Banana.Frameworks

-- | Simple way to write a single event handler with functional reactive
--   programming.
interpretAsHandler :: (forall t. Event t a -> Event t b) -> AddHandler a -> AddHandler b

-- | Compile the description of an event network into an
--   <a>EventNetwork</a> that you can <a>actuate</a>, <a>pause</a> and so
--   on.
--   
--   Event networks are described in the <a>Moment</a> monad and use the
--   <a>Frameworks</a> class constraint.
compile :: (forall t. Frameworks t => Moment t ()) -> IO EventNetwork

-- | Class constraint on the type parameter <tt>t</tt> of the
--   <tt>Moment</tt> monad.
--   
--   Indicates that we can add input and output to an event network.
class Frameworks t

-- | A value of type <tt>AddHandler a</tt> is just a facility for
--   registering callback functions, also known as event handlers.
--   
--   The type is a bit mysterious, it works like this:
--   
--   <pre>
--   do unregisterMyHandler &lt;- addHandler myHandler
--   </pre>
--   
--   The argument is an event handler that will be registered. The return
--   value is an action that unregisters this very event handler again.
type AddHandler a = (a -> IO ()) -> IO (IO ())

-- | Input, obtain an <a>Event</a> from an <a>AddHandler</a>.
--   
--   When the event network is actuated, this will register a callback
--   function such that an event will occur whenever the callback function
--   is called.
fromAddHandler :: Frameworks t => AddHandler a -> Moment t (Event t a)

-- | Input, obtain a <a>Behavior</a> from an <a>AddHandler</a> that
--   notifies changes.
--   
--   This is essentially just an application of the <a>stepper</a>
--   combinator.
fromChanges :: Frameworks t => a -> AddHandler a -> Moment t (Behavior t a)

-- | Input, obtain a <a>Behavior</a> by frequently polling mutable data,
--   like the current time.
--   
--   The resulting <a>Behavior</a> will be updated on whenever the event
--   network processes an input event.
--   
--   This function is occasionally useful, but the recommended way to
--   obtain <tt>Behaviors</tt> is by using <a>fromChanges</a>.
--   
--   Ideally, the argument IO action just polls a mutable variable, it
--   should not perform expensive computations. Neither should its side
--   effects affect the event network significantly.
fromPoll :: Frameworks t => IO a -> Moment t (Behavior t a)

-- | Output. Execute the <a>IO</a> action whenever the event occurs.
--   
--   Note: If two events occur very close to each other, there is no
--   guarantee that the <tt>reactimate</tt>s for one event will have
--   finished before the ones for the next event start executing. This does
--   <i>not</i> affect the values of events and behaviors, it only means
--   that the <tt>reactimate</tt> for different events may interleave.
--   Fortuantely, this is a very rare occurrence, and only happens if
--   
--   <ul>
--   <li>you call an event handler from inside <a>reactimate</a>,</li>
--   <li>or you use concurrency.</li>
--   </ul>
--   
--   In these cases, the <tt>reactimate</tt>s follow the control flow of
--   your event-based framework.
--   
--   Note: An event network essentially behaves like a single, huge
--   callback function. The <a>IO</a> action are not run in a separate
--   thread. The callback function will throw an exception if one of your
--   <a>IO</a> actions does so as well. Your event-based framework will
--   have to handle this situation.
reactimate :: Frameworks t => Event t (IO ()) -> Moment t ()

-- | Output, observe the initial value contained in a <a>Behavior</a>.
initial :: Behavior t a -> Moment t a

-- | Output, observe when a <a>Behavior</a> changes.
--   
--   Strictly speaking, a <a>Behavior</a> denotes a value that varies
--   <i>continuously</i> in time, so there is no well-defined event which
--   indicates when the behavior changes.
--   
--   Still, for reasons of efficiency, the library provides a way to
--   observe changes when the behavior is a step function, for instance as
--   created by <a>stepper</a>. There are no formal guarantees, but the
--   idea is that
--   
--   <pre>
--   changes (stepper x e) = return (calm e)
--   </pre>
--   
--   WARNING: The values of the event will not become available until event
--   processing is complete. Use them within <a>reactimate</a>. If you try
--   to access them before that, the program will be thrown into an
--   infinite loop.
changes :: Frameworks t => Behavior t a -> Moment t (Event t a)

-- | Dummy type needed to simulate impredicative polymorphism.
newtype FrameworksMoment a
FrameworksMoment :: (forall t. Frameworks t => Moment t a) -> FrameworksMoment a
runFrameworksMoment :: FrameworksMoment a -> forall t. Frameworks t => Moment t a

-- | Dynamically add input and output to an existing event network.
--   
--   Note: You can even do <a>IO</a> actions here, but there is no
--   guarantee about the order in which they are executed.
execute :: Frameworks t => Event t (FrameworksMoment a) -> Moment t (Event t a)

-- | Lift an <a>IO</a> action into the <a>Moment</a> monad, but defer its
--   execution until compilation time. This can be useful for recursive
--   definitions using <tt>MonadFix</tt>.
liftIOLater :: Frameworks t => IO () -> Moment t ()

-- | Deprecated. Use <a>liftIO</a> instead.

-- | <i>Deprecated: Use liftIO instead. </i>
liftIONow :: Frameworks t => IO a -> Moment t a

-- | Data type that represents a compiled event network. It may be paused
--   or already running.
data EventNetwork

-- | Actuate an event network. The inputs will register their event
--   handlers, so that the networks starts to produce outputs in response
--   to input events.
actuate :: EventNetwork -> IO ()

-- | Pause an event network. Immediately stop producing output and
--   unregister all event handlers for inputs. Hence, the network stops
--   responding to input events, but it's state will be preserved.
--   
--   You can resume the network with <a>actuate</a>.
--   
--   Note: You can stop a network even while it is processing events, i.e.
--   you can use <a>pause</a> as an argument to <a>reactimate</a>. The
--   network will <i>not</i> stop immediately though, only after the
--   current event has been processed completely.
pause :: EventNetwork -> IO ()

-- | Build a facility to register and unregister event handlers.
newAddHandler :: IO (AddHandler a, a -> IO ())

-- | Build an <a>Event</a> together with an <a>IO</a> action that can fire
--   occurrences of this event. Variant of <a>newAddHandler</a>.
--   
--   This function is mainly useful for passing callback functions inside a
--   <a>reactimate</a>.
newEvent :: Frameworks t => Moment t (Event t a, a -> IO ())

-- | Interpret by using a framework internally. Only useful for testing
--   library internals.
interpretFrameworks :: (forall t. Event t a -> Event t b) -> [a] -> IO [[b]]

module Reactive.Banana.Experimental.Calm
data Event t a
type Behavior t = Behavior t

-- | Convert event with possible simultaneous occurrences into an
--   <a>Event</a> with a single occurrence.
collect :: Event t a -> Event t [a]

-- | Convert event with single occurrences into event with possible
--   simultaneous occurrences
fromCalm :: Event t a -> Event t a

-- | Interpretation function. Useful for testing.
interpret :: (forall t. Event t a -> Event t b) -> [a] -> IO [Maybe b]

-- | Event that never occurs. Think of it as <tt>never = []</tt>.
never :: Event t a

-- | Merge two event streams of the same type. Combine simultaneous values
--   if necessary.
unionWith :: (a -> a -> a) -> Event t a -> Event t a -> Event t a

-- | Allow all events that fulfill the predicate, discard the rest.
filterE :: (a -> Bool) -> Event t a -> Event t a

-- | The <a>accumE</a> function accumulates a stream of events.
accumE :: a -> Event t (a -> a) -> Event t a

-- | Apply a time-varying function to a stream of events.
apply :: Behavior t (a -> b) -> Event t a -> Event t b

-- | Construct a time-varying function from an initial value and a stream
--   of new values.
stepper :: a -> Event t a -> Behavior t a

-- | Keep only the <a>Just</a> values. Variant of <a>filterE</a>.
filterJust :: Event t (Maybe a) -> Event t a

-- | The <a>accumB</a> function is similar to a <i>strict</i> left fold,
--   <tt>foldl'</tt>. It starts with an initial value and combines it with
--   incoming events.
accumB :: a -> Event t (a -> a) -> Behavior t a

-- | Efficient combination of <a>accumE</a> and <a>accumB</a>.
mapAccum :: acc -> Event t (acc -> (x, acc)) -> (Event t x, Behavior t acc)

-- | Class for overloading the <a>apply</a> function.
class (Functor f, Functor g) => Apply f g where f <@ g = (const <$> f) <@> g
(<@>) :: Apply f g => f (a -> b) -> g a -> g b
(<@) :: Apply f g => f a -> g b -> g a
instance Apply (Behavior t) (Event t)
instance Functor (Event t)

module Reactive.Banana

-- | Compile the description of an event network into an
--   <a>EventNetwork</a> that you can <a>actuate</a>, <a>pause</a> and so
--   on.
--   
--   Event networks are described in the <a>Moment</a> monad and use the
--   <a>Frameworks</a> class constraint.
compile :: (forall t. Frameworks t => Moment t ()) -> IO EventNetwork
