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


-- | Monadic FRP library based on stm
--   
--   Read the homepage for more information.
@package Updater
@version 0.2

module Updater

-- | <a>Signal</a> is the portable Signal they can be exchanged between any
--   parts of your program. Internally, they are just a variable and a list
--   of change hooks.
data Signal a

-- | Creates a new signal. You can use this signal in any context you want
--   and share it freely between any number of different Updater monads.
newSignal :: a -> Updater (Signal a)
newSignalIO :: a -> IO (Signal a)

-- | Writes the value to the variable inside the signal and schedules the
--   listeners to run. The listeners will run in the same stm action and
--   with the value you gave. However, they do not run immediately. So you
--   are guaranteed that writeSignal will not have any immediate sideffects
--   other then writing the one single variable.
writeSignal :: Signal a -> a -> Updater ()

-- | Gets the current value.
readSignal :: Signal a -> Updater a

-- | This monad works very similar to a continuation monad on top of stm.
--   You can do any basic stm computation you want simply using
--   <a>liftSTM</a>. However, if you use <a>getEvent</a> everything after
--   that call will be executed everytime the <a>Signal</a> given to
--   <a>getEvent</a> is changed.
--   
--   You can also use the <a>Alternative</a> instance to make a union of
--   events.
--   
--   You can also use the <a>Applicative</a> instance to run two things
--   'parallel'. Parallel meaning that events on one side will not cause
--   the other side to be reevaluated completely.
data Updater a

-- | This will evaluate the <a>Updater</a> Monad. It will block until the
--   first run reaches the end. After that, it will return the result and
--   free everything. To prevent signals from reaching the end use
--   <a>stop</a> or <a>getEvent</a> with some exit signal.
runUpdater :: Updater a -> IO a

-- | Runs everything below it everytime its input signal is updated.
getEvent :: Signal a -> Updater a

-- | IO actions given here will be executed once a signal update has been
--   completed. They keep the order in which they are inserted.
onCommit :: IO () -> Updater ()

-- | is executed right before getEvent ... fire the next event
onCleanup :: Updater () -> Updater ()

-- | Just a synonym for <a>empty</a> from <a>Alternative</a>. It basically
--   prevents signals from ever progressing beyond this point. You can use
--   this to make a filter for instance
--   
--   <pre>
--   when (condition) stop
--   </pre>
stop :: Updater a

-- | simple combination of readSignal and writeSignal
modifySignal :: Signal a -> (a -> a) -> Updater ()

-- | Similar to <a>getEvent</a> except that it also fires an event
--   immediately, with the value of the current state.
--   
--   <pre>
--   getBehavior signal = liftSTM (readSignal signal) &lt;|&gt; getEvent signal
--   </pre>
getBehavior :: Signal a -> Updater a

-- | Returns immediately after registering the given computation. However,
--   events from inside will not spread outside, except for the initial
--   one.
--   
--   It is implemented like this
--   
--   <pre>
--   local computation = return () &lt;|&gt; (computation &gt;&gt; stop)
--   </pre>
local :: Updater a -> Updater ()
liftSTM :: STM a -> Updater a

-- | Just for some quick debugging
--   
--   <pre>
--   putLine = onCommit . putStrLn
--   </pre>
putLine :: String -> Updater ()

-- | this is just a convenience for use in ghci and in the test cases. It
--   will just run the updater it is given in it's own thread.
runGlobalUpdater :: Updater a -> IO ()