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


-- | Library for functional reactive programming (FRP).
--   
--   Reactive-banana is a 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. It promises to avoid the spaghetti code that is all too
--   common in traditional approaches to GUI programming.
--   
--   See the project homepage
--   <a>http://wiki.haskell.org/Reactive-banana</a> for more detailed
--   documentation and examples.
--   
--   <i>Stability forecast.</i> This is a stable library, though minor API
--   changes are still likely. It features an efficient, push-driven
--   implementation and has seen some optimization work.
--   
--   <i>API guide.</i> Start with the <a>Reactive.Banana</a> module.
@package reactive-banana
@version 1.3.2.0

module Control.Event.Handler

-- | An <i>event handler</i> is a function that takes an <i>event value</i>
--   and performs some computation.
type Handler a = a -> IO ()

-- | The type <a>AddHandler</a> represents a facility for registering event
--   handlers. These will be called whenever the event occurs.
--   
--   When registering an event handler, you will also be given an action
--   that unregisters this handler again.
--   
--   <pre>
--   do unregisterMyHandler &lt;- register addHandler myHandler
--   </pre>
newtype AddHandler a
AddHandler :: (Handler a -> IO (IO ())) -> AddHandler a
[register] :: AddHandler a -> Handler a -> IO (IO ())

-- | Build a facility to register and unregister event handlers. Also
--   yields a function that takes an event handler and runs all the
--   registered handlers.
--   
--   Example:
--   
--   <pre>
--   do
--       (addHandler, fire) &lt;- newAddHandler
--       register addHandler putStrLn
--       fire "Hello!"
--   </pre>
newAddHandler :: IO (AddHandler a, Handler a)

-- | Map the event value with an <a>IO</a> action.
mapIO :: (a -> IO b) -> AddHandler a -> AddHandler b

-- | Filter event values that don't return <a>True</a>.
filterIO :: (a -> IO Bool) -> AddHandler a -> AddHandler a
instance GHC.Internal.Base.Functor Control.Event.Handler.AddHandler
instance GHC.Internal.Base.Monoid (Control.Event.Handler.Callback a)
instance GHC.Internal.Base.Semigroup (Control.Event.Handler.Callback a)

module Reactive.Banana.Model

-- | Natural numbers (poorly represented).
type Nat = Int

-- | The FRP model used in this library is actually a model with continuous
--   time.
--   
--   However, it can be shown that this model is observationally equivalent
--   to a particular model with (seemingly) discrete time steps, which is
--   implemented here. The main reason for doing this is to be able to
--   handle recursion correctly. Details will be explained elsewhere.
type Time = Nat

-- | Event is modeled by an <i>infinite</i> list of <a>Maybe</a> values. It
--   is isomorphic to <tt>Time -&gt; Maybe a</tt>.
--   
--   <a>Nothing</a> indicates that no occurrence happens, while <a>Just</a>
--   indicates that an occurrence happens.
newtype Event a
E :: [Maybe a] -> Event a
[unE] :: Event a -> [Maybe a]

-- | Behavior is modeled by an <i>infinite</i> list of values. It is
--   isomorphic to <tt>Time -&gt; a</tt>.
newtype Behavior a
B :: [a] -> Behavior a
[unB] :: Behavior a -> [a]
interpret :: (Event a -> Moment (Event b)) -> [Maybe a] -> [Maybe b]
never :: Event a
unionWith :: (a -> a -> a) -> Event a -> Event a -> Event a
mergeWith :: (a -> c) -> (b -> c) -> (a -> b -> c) -> Event a -> Event b -> Event c
filterJust :: Event (Maybe a) -> Event a
apply :: Behavior (a -> b) -> Event a -> Event b
newtype Moment a
M :: (Time -> a) -> Moment a
[unM] :: Moment a -> Time -> a
accumE :: a -> Event (a -> a) -> Moment (Event a)
stepper :: a -> Event a -> Moment (Behavior a)
valueB :: Behavior a -> Moment a
observeE :: Event (Moment a) -> Event a
switchE :: Event a -> Event (Event a) -> Moment (Event a)
switchB :: Behavior a -> Event (Behavior a) -> Moment (Behavior a)
instance GHC.Internal.Base.Applicative Reactive.Banana.Model.Behavior
instance GHC.Internal.Base.Applicative Reactive.Banana.Model.Moment
instance GHC.Internal.Base.Functor Reactive.Banana.Model.Behavior
instance GHC.Internal.Base.Functor Reactive.Banana.Model.Event
instance GHC.Internal.Base.Functor Reactive.Banana.Model.Moment
instance GHC.Internal.Control.Monad.Fix.MonadFix Reactive.Banana.Model.Moment
instance GHC.Internal.Base.Monad Reactive.Banana.Model.Moment
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Reactive.Banana.Model.Behavior a)
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Reactive.Banana.Model.Event a)

module Reactive.Banana.Prim.High.Cached
data Cached (m :: Type -> Type) a
runCached :: Cached m a -> m a

-- | An action whose result will be cached. Executing the action the first
--   time in the monad will execute the side effects. From then on, only
--   the generated value will be returned.
cache :: (MonadFix m, MonadIO m) => m a -> Cached m a

-- | Return a pure value. Doesn't make use of the cache.
fromPure :: forall (m :: Type -> Type) a. Monad m => a -> Cached m a

-- | Lift an action that is <i>not</i> cached, for instance because it is
--   idempotent.
don'tCache :: Monad m => m a -> Cached m a
liftCached1 :: (MonadFix m, MonadIO m) => (a -> m b) -> Cached m a -> Cached m b
liftCached2 :: (MonadFix m, MonadIO m) => (a -> b -> m c) -> Cached m a -> Cached m b -> Cached m c

module Reactive.Banana.Prim.Low.Graph

-- | A directed graph whose set of vertices is the set of all values of the
--   type <tt>v</tt> and whose edges are associated with data of type
--   <tt>e</tt>.
--   
--   Note that a <a>Graph</a> does not have a notion of vertex membership —
--   by design, <i>all</i> values of the type <tt>v</tt> are vertices of
--   the <a>Graph</a>. The main purpose of <a>Graph</a> is to keep track of
--   directed edges between vertices; a vertex with at least one edge
--   incident on it is called a <i>connected vertex</i>. For efficiency,
--   only the connected vertices are stored.
data Graph v e

-- | The graph with no edges.
empty :: Graph v e

-- | Get all direct successors of a vertex in a <a>Graph</a>.
getOutgoing :: (Eq v, Hashable v) => Graph v e -> v -> [(e, v)]

-- | Get all direct predecessors of a vertex in a <a>Graph</a>.
getIncoming :: (Eq v, Hashable v) => Graph v e -> v -> [(v, e)]

-- | Number of connected vertices, i.e. vertices on which at least one edge
--   is incident.
size :: (Eq v, Hashable v) => Graph v e -> Int

-- | Number of edges.
edgeCount :: (Eq v, Hashable v) => Graph v e -> Int

-- | List all connected vertices, i.e. vertices on which at least one edge
--   is incident.
listConnectedVertices :: (Eq v, Hashable v) => Graph v e -> [v]

-- | Remove all edges incident on this vertex from the <a>Graph</a>.
deleteVertex :: (Eq v, Hashable v) => v -> Graph v e -> Graph v e

-- | Insert an edge from the first to the second vertex into the
--   <a>Graph</a>.
insertEdge :: (Eq v, Hashable v) => (v, v) -> e -> Graph v e -> Graph v e

-- | TODO: Not implemented.
deleteEdge :: (Eq v, Hashable v) => (v, v) -> Graph v e -> Graph v e

-- | Remove all the edges that connect the given vertex to its
--   predecessors.
clearPredecessors :: (Eq v, Hashable v) => v -> Graph v e -> Graph v e

-- | Apply <a>deleteVertex</a> to all vertices which are not predecessors
--   of any of the vertices in the given list.
collectGarbage :: (Eq v, Hashable v) => [v] -> Graph v e -> Graph v e

-- | If the <a>Graph</a> is acyclic, return a topological sort, that is a
--   linear ordering of its connected vertices such that each vertex occurs
--   before its successors.
--   
--   (Vertices that are not connected are not listed in the topological
--   sort.)
--   
--   <a>https://en.wikipedia.org/wiki/Topological_sorting</a>
topologicalSort :: (Eq v, Hashable v) => Graph v e -> [v]
data Step
Next :: Step
Stop :: Step

-- | Starting from a list of vertices without predecessors, walk through
--   all successors, but in such a way that every vertex is visited before
--   its predecessors. For every vertex, if the function returns
--   <a>Next</a>, then the successors are visited, otherwise the walk at
--   the vertex stops prematurely.
--   
--   <pre>
--   topologicalSort g =
--       runIdentity $ walkSuccessors (roots g) (pure Next) g
--   </pre>
walkSuccessors :: forall v e m. (Monad m, Eq v, Hashable v) => [v] -> (v -> m Step) -> Graph v e -> m [v]
walkSuccessors_ :: (Monad m, Eq v, Hashable v) => [v] -> (v -> m Step) -> Graph v e -> m ()

-- | <a>Level</a>s are used to keep track of the order of vertices — Lower
--   levels come first.
type Level = Int

-- | Get the <a>Level</a> of a vertex in a <a>Graph</a>.
getLevel :: (Eq v, Hashable v) => Graph v e -> v -> Level

-- | Map to a string in <tt>graphviz</tt> dot file format.
showDot :: (Eq v, Hashable v) => (v -> String) -> Graph v e -> String
instance (GHC.Classes.Eq v, GHC.Classes.Eq e) => GHC.Classes.Eq (Reactive.Banana.Prim.Low.Graph.Graph v e)
instance (GHC.Internal.Show.Show v, GHC.Internal.Show.Show e) => GHC.Internal.Show.Show (Reactive.Banana.Prim.Low.Graph.Graph v e)

module Reactive.Banana.Prim.Low.Ref

-- | A mutable reference which has a <a>Unique</a> associated with it.
data Ref a
getUnique :: Ref a -> Unique
new :: MonadIO m => a -> m (Ref a)
equal :: Ref a -> Ref b -> Bool
read :: MonadIO m => Ref a -> m a
put :: MonadIO m => Ref a -> a -> m ()

-- | Strictly modify a <a>Ref</a>.
modify' :: MonadIO m => Ref a -> (a -> a) -> m ()

-- | Add a finalizer to a <a>Ref</a>.
--   
--   See <a>addFinalizer</a>.
addFinalizer :: Ref v -> IO () -> IO ()
getWeakRef :: Ref a -> WeakRef a

-- | Weak pointer to a <a>Ref</a>.
type WeakRef v = Weak Ref v

-- | Create a weak pointer that associates a key with a value.
--   
--   See <a>mkWeak</a>.
mkWeak :: Ref k -> v -> Maybe (IO ()) -> IO (Weak v)

-- | Dereference a <a>WeakRef</a>.
--   
--   See <a>deRefWeak</a>.
deRefWeak :: Weak v -> IO (Maybe v)

-- | Dereference a list of weak pointers while discarding dead ones.
deRefWeaks :: [Weak v] -> IO [v]

-- | Finalize a <a>WeakRef</a>.
--   
--   See <a>finalize</a>.
finalize :: WeakRef v -> IO ()
instance GHC.Classes.Eq (Reactive.Banana.Prim.Low.Ref.Ref a)
instance Data.Hashable.Class.Hashable (Reactive.Banana.Prim.Low.Ref.Ref a)
instance Control.DeepSeq.NFData (Reactive.Banana.Prim.Low.Ref.Ref a)

module Reactive.Banana.Prim.Low.GraphGC

-- | A directed graph whose edges are mutable and whose vertices are
--   subject to garbage collection.
--   
--   The vertices of the graph are mutable references of type 'Ref v'.
--   
--   Generally, the vertices of the graph are not necessarily kept
--   reachable by the <a>GraphGC</a> data structure — they need to be kept
--   reachable by other parts of your program.
--   
--   That said, the edges in the graph do introduce additional reachability
--   between vertices: Specifically, when an edge (x,y) is present in the
--   graph, then the head <tt>y</tt> will keep the tail <tt>x</tt>
--   reachable. (But the liveness of <tt>y</tt> needs to come from
--   elsewhere, e.g. another edge.) Use <a>insertEdge</a> to insert an
--   edge.
--   
--   Moreover, when a vertex is removed because it is no longer reachable,
--   then all edges to and from that vertex will also be removed. In turn,
--   this may cause further vertices and edges to be removed.
--   
--   Concerning garbage collection: Note that vertices and edges will not
--   be removed automatically when the Haskell garbage collector runs —
--   they will be marked as garbage by the Haskell runtime, but the actual
--   removal of garbage needs to be done explicitly by calling
--   <a>removeGarbage</a>. This procedure makes it easier to reason about
--   the state of the <a>GraphGC</a> during a call to e.g.
--   <a>walkSuccessors</a>.
data GraphGC v

-- | List all vertices that are reachable and have at least one edge
--   incident on them. TODO: Is that really what the function does?
listReachableVertices :: GraphGC v -> IO [Ref v]
getSize :: GraphGC v -> IO Int

-- | Create a new <a>GraphGC</a>.
new :: IO (GraphGC v)

-- | Insert an edge from the first vertex to the second vertex.
insertEdge :: (Ref v, Ref v) -> GraphGC v -> IO ()

-- | Remove all the edges that connect the vertex to its predecessors.
clearPredecessors :: Ref v -> GraphGC v -> IO ()
data Step
Next :: Step
Stop :: Step

-- | Walk through all successors. See <a>walkSuccessors</a>.
walkSuccessors :: Monad m => [Ref v] -> (WeakRef v -> m Step) -> GraphGC v -> IO (m [WeakRef v])

-- | Walk through all successors. See <a>walkSuccessors_</a>.
walkSuccessors_ :: Monad m => [Ref v] -> (WeakRef v -> m Step) -> GraphGC v -> IO (m ())

-- | Explicitly remove all vertices and edges that have been marked as
--   garbage by the Haskell garbage collector.
removeGarbage :: GraphGC v -> IO ()

-- | Show the underlying graph in <tt>graphviz</tt> dot file format.
printDot :: (Unique -> WeakRef v -> IO String) -> GraphGC v -> IO String

module Reactive.Banana.Prim.Mid
type Step = EvalNetwork IO ()
type EvalNetwork a = Network -> IO (a, Network)

-- | A <a>Network</a> represents the state of a pulse/latch network,
data Network
emptyNetwork :: IO Network
getSize :: Network -> IO Int
type Build = ReaderWriterIOT BuildR BuildW IO
liftIOLater :: IO () -> Build ()
type BuildIO = Build
liftBuild :: Build a -> BuildIO a
buildLater :: Build () -> Build ()

-- | Pretend to return a value right now, but do not actually calculate it
--   until later.
--   
--   NOTE: Accessing the value before it's written leads to an error.
--   
--   FIXME: Is there a way to have the value calculate on demand?
buildLaterReadNow :: Build a -> Build a

-- | Change a <a>Network</a> of pulses and latches by executing a
--   <a>BuildIO</a> action.
compile :: BuildIO a -> Network -> IO (a, Network)

-- | Simple interpreter for pulse/latch networks.
--   
--   Mainly useful for testing functionality
--   
--   Note: The result is not computed lazily, for similar reasons that the
--   <a>sequence</a> function does not compute its result lazily.
interpret :: (Pulse a -> BuildIO (Pulse b)) -> [Maybe a] -> IO [Maybe b]

-- | <tt>mapAccum</tt> for a monad.
mapAccumM :: Monad m => (a -> s -> m (b, s)) -> s -> [a] -> m ([b], s)

-- | Strict <tt>mapAccum</tt> for a monad. Discards results.
mapAccumM_ :: Monad m => (a -> s -> m (b, s)) -> s -> [a] -> m ()

-- | Execute an FRP network with a sequence of inputs. Make sure that
--   outputs are evaluated, but don't display their values.
--   
--   Mainly useful for testing whether there are space leaks.
runSpaceProfile :: Show b => (Pulse a -> BuildIO (Pulse b)) -> [a] -> IO ()

-- | Create a new pulse in the network and a function to trigger it.
--   
--   Together with <a>addHandler</a>, this function can be used to operate
--   with pulses as with standard callback-based events.
newInput :: Build (Pulse a, a -> Step)

-- | Register a handler to be executed whenever a pulse occurs.
--   
--   The pulse may refer to future latch values.
addHandler :: Pulse (Future a) -> (a -> IO ()) -> Build ()

-- | Read the value of a <a>Latch</a> at a particular moment in time.
readLatch :: Latch a -> Build a
data Pulse a

-- | <a>Pulse</a> that never fires.
neverP :: Build (Pulse a)
alwaysP :: Build (Pulse ())
mapP :: (a -> b) -> Pulse a -> Build (Pulse b)
type Future = IO

-- | Tag a <a>Pulse</a> with future values of a <a>Latch</a>.
--   
--   This is in contrast to <a>applyP</a> which applies the current value
--   of a <a>Latch</a> to a pulse.
tagFuture :: Latch a -> Pulse b -> Build (Pulse (Future a))
unsafeMapIOP :: (a -> IO b) -> Pulse a -> Build (Pulse b)
filterJustP :: Pulse (Maybe a) -> Build (Pulse a)
mergeWithP :: (a -> Maybe c) -> (b -> Maybe c) -> (a -> b -> Maybe c) -> Pulse a -> Pulse b -> Build (Pulse c)
type Latch a = Ref LatchD a
pureL :: a -> Latch a
mapL :: (a -> b) -> Latch a -> Latch b
applyL :: Latch (a -> b) -> Latch a -> Latch b
accumL :: a -> Pulse (a -> a) -> Build (Latch a, Pulse a)
applyP :: Latch (a -> b) -> Pulse a -> Build (Pulse b)
switchL :: Latch a -> Pulse (Latch a) -> Build (Latch a)
executeP :: forall a b. Pulse (b -> Build a) -> b -> Build (Pulse a)
switchP :: Pulse a -> Pulse (Pulse a) -> Build (Pulse a)

-- | Show the graph of the <a>Network</a> in <tt>graphviz</tt> dot file
--   format.
printDot :: Network -> IO String

module Reactive.Banana.Combinators

-- | <tt>Event a</tt> represents a stream of events as they occur in time.
--   Semantically, you can think of <tt>Event a</tt> as an infinite list of
--   values that are tagged with their corresponding time of occurrence,
--   
--   <pre>
--   type Event a = [(Time,a)]
--   </pre>
--   
--   Each pair is called an <i>event occurrence</i>. Note that within a
--   single event stream, no two event occurrences may happen at the same
--   time.
--   
data Event a

-- | <tt>Behavior a</tt> represents a value that varies in time.
--   Semantically, you can think of it as a function
--   
--   <pre>
--   type Behavior a = Time -&gt; a
--   </pre>
--   
data Behavior a

-- | 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
--   <a>IO</a>, but it can't be helped. See source code for the sordid
--   details.
interpret :: (Event a -> Moment (Event b)) -> [Maybe a] -> IO [Maybe b]

-- | Event that never occurs. Semantically,
--   
--   <pre>
--   never = []
--   </pre>
never :: 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
--   
--   <pre>
--   unionWith f ((timex,x):xs) ((timey,y):ys)
--      | timex &lt;  timey = (timex,x)     : unionWith f xs ((timey,y):ys)
--      | timex &gt;  timey = (timey,y)     : unionWith f ((timex,x):xs) ys
--      | timex == timey = (timex,f x y) : unionWith f xs ys
--   </pre>
unionWith :: (a -> a -> a) -> Event a -> Event a -> Event a

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

-- | Apply a time-varying function to a stream of events. Semantically,
--   
--   <pre>
--   apply bf ex = [(time, bf time x) | (time, x) &lt;- ex]
--   </pre>
--   
--   This function is generally used in its infix variant <a>&lt;@&gt;</a>.
apply :: Behavior (a -> b) -> Event a -> Event b

-- | The <a>Moment</a> monad denotes a <i>pure</i> computation that happens
--   at one particular moment in time. Semantically, it is a reader monad
--   
--   <pre>
--   type Moment a = Time -&gt; a
--   </pre>
--   
--   When run, the argument tells the time at which this computation
--   happens.
--   
--   Note that in this context, <i>time</i> really means to <i>logical
--   time</i>. 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 <a>Event</a>s and <a>Behavior</a>s. We use the
--   fiction that every calculation within the <a>Moment</a> monad takes
--   zero <i>logical time</i> to perform.
data Moment a

-- | An instance of the <a>MonadMoment</a> class denotes a computation that
--   happens at one particular moment in time. Unlike the <a>Moment</a>
--   monad, it need not be pure anymore.
class MonadFix m => MonadMoment (m :: Type -> Type)
liftMoment :: MonadMoment m => Moment a -> m a

-- | The <a>accumE</a> function accumulates a stream of event values,
--   similar to a <i>strict</i> left scan, <tt>scanl'</tt>. 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:
--   
--   <pre>
--   accumE "x" [(time1,(++"y")),(time2,(++"z"))]
--       = trimE [(time1,"xy"),(time2,"xyz")]
--       where
--       trimE e start = [(time,x) | (time,x) &lt;- e, start &lt;= time]
--   </pre>
accumE :: MonadMoment m => a -> Event (a -> a) -> m (Event a)

-- | Construct a time-varying function from an initial value and a stream
--   of new values. The result will be a step function. Semantically,
--   
--   <pre>
--   stepper x0 ex = \time1 -&gt; \time2 -&gt;
--       last (x0 : [x | (timex,x) &lt;- ex, time1 &lt;= timex, timex &lt; time2])
--   </pre>
--   
--   Here is an illustration of the result Behavior at a particular time:
--   
--   
--   Note: The smaller-than-sign in the comparison <tt>timex &lt;
--   time2</tt> means that at time <tt>time2 == timex</tt>, 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.
stepper :: MonadMoment m => a -> Event a -> m (Behavior a)

-- | Obtain the value of the <a>Behavior</a> at a given moment in time.
--   Semantically, it corresponds to
--   
--   <pre>
--   valueB b = \time -&gt; b time
--   </pre>
--   
--   Note: The value is immediately available for pattern matching.
--   Unfortunately, this means that <tt>valueB</tt> is unsuitable for use
--   with value recursion in the <a>Moment</a> monad. If you need
--   recursion, please use <a>valueBLater</a> instead.
valueB :: MonadMoment m => Behavior a -> m a

-- | Obtain the value of the <a>Behavior</a> at a given moment in time.
--   Semantically, it corresponds to
--   
--   <pre>
--   valueBLater b = \time -&gt; b time
--   </pre>
--   
--   Note: To allow for more recursion, the value is returned <i>lazily</i>
--   and not available for pattern matching immediately. It can be used
--   safely with most combinators like <a>stepper</a>. If that doesn't work
--   for you, please use <a>valueB</a> instead.
valueBLater :: MonadMoment m => Behavior a -> m a

-- | Observe a value at those moments in time where event occurrences
--   happen. Semantically,
--   
--   <pre>
--   observeE e = [(time, m time) | (time, m) &lt;- e]
--   </pre>
observeE :: Event (Moment a) -> Event a

-- | Dynamically switch between <a>Event</a>. Semantically,
--   
--   <pre>
--   switchE e0 ee0 time0 =
--       concat [ trim t1 t2 e | (t1,t2,e) &lt;- intervals ee ]
--     where
--       laterThan e time0  = [(timex,x) | (timex,x) &lt;- e, time0 &lt; timex ]
--       ee                 = [(time0, e0)] ++ (ee0 `laterThan` time0)
--       intervals ee       = [(time1, time2, e) | ((time1,e),(time2,_)) &lt;- zip ee (tail ee)]
--       trim time1 time2 e = [x | (timex,x) &lt;- e, time1 &lt; timex, timex &lt;= time2]
--   </pre>
switchE :: MonadMoment m => Event a -> Event (Event a) -> m (Event a)

-- | Dynamically switch between <a>Behavior</a>. Semantically,
--   
--   <pre>
--   switchB b0 eb = \time0 -&gt; \time1 -&gt;
--      last (b0 : [b | (timeb,b) &lt;- eb, time0 &lt;= timeb, timeb &lt; time1]) time1
--   </pre>
switchB :: MonadMoment m => Behavior a -> Event (Behavior a) -> m (Behavior a)

-- | Infix synonym for the <a>apply</a> combinator. Similar to
--   <a>&lt;*&gt;</a>.
--   
--   <pre>
--   infixl 4 &lt;@&gt;
--   </pre>
(<@>) :: Behavior (a -> b) -> Event a -> Event b
infixl 4 <@>

-- | Tag all event occurrences with a time-varying value. Similar to
--   <a>&lt;*</a>.
--   
--   <pre>
--   infixl 4 &lt;@
--   </pre>
(<@) :: Behavior b -> Event a -> Event b
infixl 4 <@

-- | Tag all event occurences with a time-varying value. Similar to
--   <a>*&gt;</a>.
--   
--   This is the flipped version of <a>&lt;@</a>, but can be useful when
--   combined with <tt>ApplicativeDo</tt> to sample from multiple
--   <a>Behavior</a>s:
--   
--   <pre>
--   reactimate $ onEvent @&gt; do
--     x &lt;- behavior1
--     y &lt;- behavior2
--     return (print (x + y))
--   </pre>
(@>) :: Event a -> Behavior b -> Event b
infixl 4 @>

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

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

-- | Allow events only when the behavior is <a>True</a>. Variant of
--   <a>filterApply</a>.
whenE :: Behavior Bool -> Event a -> Event 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 (Either a b) -> (Event a, Event b)

-- | Keep only the next occurence of an event.
--   
--   <tt>once</tt> also aids the garbage collector by indicating that the
--   result event can be discarded after its only occurrence.
--   
--   <pre>
--   once e = \time0 -&gt; take 1 [(t, a) | (t, a) &lt;- e, time0 &lt;= t]
--   </pre>
once :: MonadMoment m => Event a -> m (Event a)

-- | Merge event streams whose values are functions. In case of
--   simultaneous occurrences, the functions at the beginning of the list
--   are applied <i>after</i> the functions at the end.
--   
--   <pre>
--   unions [] = never
--   unions xs = foldr1 (unionWith (.)) xs
--   </pre>
--   
--   Very useful in conjunction with accumulation functions like
--   <a>accumB</a> and <a>accumE</a>.
unions :: [Event (a -> a)] -> Event (a -> a)

-- | The <a>accumB</a> function accumulates event occurrences into a
--   <a>Behavior</a>.
--   
--   The value is accumulated using <a>accumE</a> and converted into a
--   time-varying value using <a>stepper</a>.
--   
--   Example:
--   
--   <pre>
--   accumB "x" [(time1,(++"y")),(time2,(++"z"))]
--      = stepper "x" [(time1,"xy"),(time2,"xyz")]
--   </pre>
--   
--   Note: As with <a>stepper</a>, the value of the behavior changes
--   "slightly after" the events occur. This allows for recursive
--   definitions.
accumB :: MonadMoment m => a -> Event (a -> a) -> m (Behavior a)

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

-- | Merge two event streams of any type.
merge :: Event a -> Event b -> Event (These a b)

-- | Merge two event streams of any type.
--   
--   This function generalizes <a>unionWith</a>.
mergeWith :: (a -> c) -> (b -> c) -> (a -> b -> c) -> Event a -> Event b -> Event c

module Reactive.Banana.Frameworks

-- | Simple way to write a single event handler with functional reactive
--   programming.
interpretAsHandler :: (Event a -> Moment (Event 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.
compile :: MomentIO () -> IO EventNetwork

-- | The <a>MomentIO</a> monad is used to add inputs and outputs to an
--   event network.
data MomentIO a

-- | 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 :: AddHandler a -> MomentIO (Event 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 :: a -> AddHandler a -> MomentIO (Behavior 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 :: IO a -> MomentIO (Behavior 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.
--   Fortunately, 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 :: Event (IO ()) -> MomentIO ()

-- | The <a>Future</a> monad is just a helper type for the <tt>changes</tt>
--   function.
--   
--   A value of type <tt>Future a</tt> is only available in the context of
--   a <tt>reactimate</tt> but not during event processing.
data Future a

-- | Output. Execute the <a>IO</a> action whenever the event occurs.
--   
--   This version of <a>reactimate</a> can deal with values obtained from
--   the <a>changes</a> function.
reactimate' :: Event (Future (IO ())) -> MomentIO ()

-- | Output, return an <a>Event</a> that is adapted to the changes of a
--   <a>Behavior</a>.
--   
--   Remember that semantically, a <a>Behavior</a> is a function
--   <tt>Behavior a = Time -&gt; a</tt>. This means that a Behavior does
--   not have a notion of "changes" associated with it. For instance, the
--   following Behaviors are equal:
--   
--   <pre>
--   stepper 0 []
--   = stepper 0 [(time1, 0), (time2, 0)]
--   = stepper 0 $ zip [time1,time2..] (repeat 0)
--   </pre>
--   
--   In principle, to perform IO actions with the value of a Behavior, one
--   has to sample it using an <a>Event</a> and the <a>apply</a> function.
--   
--   However, in practice, Behaviors are usually step functions. For
--   reasons of efficiency, the library provides a way to obtain an Event
--   that <i>mostly</i> coincides with the steps of a Behavior, so that
--   sampling is only done at a few select points in time. The idea is that
--   
--   <pre>
--   changes =&lt;&lt; stepper x e  =  return e
--   </pre>
--   
--   Please use <a>changes</a> only in a ways that do <i>not</i>
--   distinguish between the different expressions for the same Behavior
--   above.
--   
--   Note that the value of the event is actually the <i>new</i> value,
--   i.e. that value slightly after this point in time. (See the
--   documentation of <a>stepper</a>). This is more convenient. However,
--   the value will not become available until after event processing is
--   complete; this is indicated by the type <a>Future</a>. It can be used
--   only in the context of <a>reactimate'</a>.
changes :: Behavior a -> MomentIO (Event (Future a))

-- | Impose a different sampling event on a <a>Behavior</a>.
--   
--   The <a>Behavior</a> will have the same values as before, but the event
--   returned by the <a>changes</a> function will now happen simultaneously
--   with the imposed event.
--   
--   Note: This function is useful only in very specific circumstances.
imposeChanges :: Behavior a -> Event () -> Behavior a

-- | Dynamically add input and output to an existing event network.
--   
--   Note: You can perform <a>IO</a> actions here, which is useful if you
--   want to register additional event handlers dynamically.
--   
--   However, if two arguments to <a>execute</a> occur simultaneously, then
--   the order in which the <a>IO</a> therein are executed is unspecified.
--   For instance, in the following code
--   
--   <pre>
--   example e = do
--         e1 &lt;- execute (liftIO (putStrLn "A") &lt;$ e)
--         e2 &lt;- execute (liftIO (putStrLn "B") &lt;$ e)
--         return (e1,e2)
--   </pre>
--   
--   it is unspecified whether <tt>A</tt> or <tt>B</tt> are printed first.
--   
--   Moreover, if the result <a>Event</a> of this function has been garbage
--   collected, it may also happen that the actions are not executed at
--   all. In the example above, if the events <tt>e1</tt> and <tt>e2</tt>
--   are not used any further, then it can be that neither <tt>A</tt> nor
--   <tt>B</tt> will be printed.
--   
--   If your main goal is to reliably turn events into <a>IO</a> actions,
--   use the <a>reactimate</a> and <a>reactimate'</a> functions instead.
execute :: Event (MomentIO a) -> MomentIO (Event 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 :: IO () -> MomentIO ()

-- | Interpret an event processing function by building an
--   <a>EventNetwork</a> and running it. Useful for testing, but uses
--   <a>MomentIO</a>. See <a>interpret</a> for a plain variant.
interpretFrameworks :: (Event a -> MomentIO (Event b)) -> [Maybe a] -> IO [Maybe b]

-- | 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 :: MomentIO (Event a, Handler a)

-- | Build a new <a>Event</a> that contains the result of an IO
--   computation. The input and result events will <i>not</i> be
--   simultaneous anymore, the latter will occur <i>later</i> than the
--   former.
--   
--   Please use the <a>fmap</a> for <a>Event</a> if your computation is
--   pure.
--   
--   Implementation:
--   
--   <pre>
--   mapEventIO f e1 = do
--       (e2, handler) &lt;- newEvent
--       reactimate $ (\a -&gt; f a &gt;&gt;= handler) &lt;$&gt; e1
--       return e2
--   </pre>
mapEventIO :: (a -> IO b) -> Event a -> MomentIO (Event b)

-- | Build a <a>Behavior</a> together with an <a>IO</a> action that can
--   update this behavior with new values.
--   
--   Implementation:
--   
--   <pre>
--   newBehavior a = do
--       (e, fire) &lt;- newEvent
--       b         &lt;- stepper a e
--       return (b, fire)
--   </pre>
newBehavior :: a -> MomentIO (Behavior a, Handler 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. (In a
--   future version, it will also 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 ()

-- | PROVISIONAL. Measure of the number of events in the event network.
--   Useful for understanding space usage.
getSize :: EventNetwork -> IO Int

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.
compile :: MomentIO () -> IO EventNetwork
