-- 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.1

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 and gives you a way to update it. It is important
--   to note that because the signal and the update function are separate,
--   you can easily have readonly, writeonly permissions.
newSignal :: Updater (a -> Updater (), Signal a)

-- | Gets the current value. Return Nothing if the signal is uninitialized.
getValue :: Signal a -> Updater (Maybe 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 ()

-- | doesn't really work yet
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

-- | Similar to <a>getEvent</a> except that it also fires an event
--   immediately, if the input signal is already initialized. It can be
--   created using <a>getEvent</a> and <a>Alternative</a>
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 ()