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


-- | Arrowized FRP implementation
--   
--   This library provides an arrowized functional reactive programming
--   (FRP) implementation. It is similar to Yampa and Animas, but has a
--   much simpler internal representation and a lot of new features.
@package netwire
@version 1.1.0


-- | The module contains the main <a>Wire</a> type.
module FRP.NetWire.Wire

-- | A wire is a network of signal transformers.
data Wire :: (* -> *) -> * -> * -> *
WArr :: (a -> b) -> Wire m a b
WConst :: b -> Wire m a b
WGen :: (WireState m -> a -> m (Output b, Wire m a b)) -> Wire m a b
WId :: Wire m a a

-- | The state of the wire.
data WireState :: (* -> *) -> *
ImpureState :: Double -> MTGen -> TVar Int -> WireState m

-- | Time difference for current instant.
wsDTime :: WireState m -> Double

-- | Random number generator.
wsRndGen :: WireState m -> MTGen

-- | Request counter.
wsReqVar :: WireState m -> TVar Int
PureState :: Double -> WireState m

-- | Time difference for current instant.
wsDTime :: WireState m -> Double

-- | Events are signals, which can be absent. They usually denote discrete
--   occurences of certain events.
type Event = Maybe

-- | Inhibition exception with an informative message. This exception is
--   the result of signal inhibition, where no further exception
--   information is available.
data InhibitException

-- | The output of a wire. When the wire inhibits, then this will be a
--   <a>Left</a> value with an exception.
type Output = Either SomeException

-- | Signal functions are wires over the identity monad.
type SF = Wire Identity

-- | Time.
type Time = Double

-- | Clean up wire state.
cleanupWireState :: WireState m -> IO ()

-- | Construct an <a>InhibitException</a> wrapped in a
--   <a>SomeException</a>.
inhibitEx :: String -> SomeException

-- | Initialize wire state.
initWireState :: MonadIO m => IO (WireState m)

-- | Create a generic wire from the given function. This is a smart
--   constructor. Please use it instead of the <a>WGen</a> constructor.
mkGen :: (WireState m -> a -> m (Output b, Wire m a b)) -> Wire m a b

-- | Extract the transition function of a wire.
toGen :: Monad m => Wire m a b -> WireState m -> a -> m (Output b, Wire m a b)
instance Typeable InhibitException
instance Read InhibitException
instance Show InhibitException
instance Monad m => Functor (Wire m a)
instance Monad m => Category (Wire m)
instance Monad m => ArrowZero (Wire m)
instance Monad m => ArrowPlus (Wire m)
instance Monad m => ArrowChoice (Wire m)
instance Monad m => Arrow (Wire m)
instance Monad m => Applicative (Wire m a)
instance Monad m => Alternative (Wire m a)
instance Exception InhibitException


-- | Wire sessions.
module FRP.NetWire.Session

-- | Reactive sessions with the given time type.
data Session a b
Session :: TVar Bool -> IORef (WireState IO) -> IORef UTCTime -> IORef (Wire IO a b) -> Session a b

-- | False, if in use.
sessFreeVar :: Session a b -> TVar Bool

-- | State of the last instant.
sessStateRef :: Session a b -> IORef (WireState IO)

-- | Time of the last instant.
sessTimeRef :: Session a b -> IORef UTCTime

-- | Wire for the next instant.
sessWireRef :: Session a b -> IORef (Wire IO a b)

-- | Feed the given input value into the reactive system performing the
--   next instant using real time.
stepWire :: a -> Session a b -> IO (Output b)

-- | Feed the given input value into the reactive system performing the
--   next instant using the given time delta.
stepWireDelta :: NominalDiffTime -> a -> Session a b -> IO (Output b)

-- | Feed the given input value into the reactive system performing the
--   next instant, which is at the given time. This function is
--   thread-safe.
stepWireTime :: UTCTime -> a -> Session a b -> IO (Output b)

-- | Feed the given input value into the reactive system performing the
--   next instant, which is at the given time. This function is *not*
--   thread-safe.
stepWireTime' :: UTCTime -> a -> Session a b -> IO (Output b)

-- | Initialize a reactive session and pass it to the given continuation.
withWire :: Wire IO a b -> (Session a b -> IO c) -> IO c


-- | Pure wire sessions.
module FRP.NetWire.Pure

-- | Perform the next instant of a pure wire over the identity monad.
stepSF :: Time -> a -> SF a b -> (Output b, SF a b)

-- | Perform the next instant of a pure wire.
stepWirePure :: Monad m => Time -> a -> Wire m a b -> m (Output b, Wire m a b)


-- | The usual FRP tools you'll want to work with.
module FRP.NetWire.Tools

-- | The constant wire. Please use this function instead of <tt>arr (const
--   c)</tt>.
constant :: b -> Wire m a b

-- | Identity signal transformer. Outputs its input.
identity :: Monad m => Wire m a a

-- | Get the local time.
time :: Monad m => Wire m a Time

-- | Get the local time, assuming it starts from the given value.
timeFrom :: Monad m => Time -> Wire m a Time

-- | Turn a continuous signal into a discrete one. This transformer picks
--   values from the right signal at intervals of the left signal.
--   
--   The interval length is followed in real time. If it's zero, then this
--   wire acts like <tt>second id</tt>.
discrete :: Monad m => Wire m (Time, a) a

-- | Keep the value in the first instant forever.
keep :: Monad m => Wire m a a

-- | Unconditional inhibition with the given inhibition exception.
inhibit :: (Exception e, Monad m) => Wire m e b

-- | Inhibit right signal, when the left signal is false.
require :: Monad m => Wire m (Bool, a) a

-- | This function corresponds to <a>try</a> for exceptions, allowing you
--   to observe inhibited signals.
exhibit :: Monad m => Wire m a b -> Wire m a (Output b)

-- | Effectively prevent a wire from rewiring itself. This function will
--   turn any stateful wire into a stateless wire, rendering most wires
--   useless.
--   
--   Note: This function should not be used normally. Use it only, if you
--   know exactly what you're doing.
freeze :: Monad m => Wire m a b -> Wire m a b

-- | Sample the given wire at specific intervals. Use this instead of
--   <a>discrete</a>, if you want to prevent the signal from passing
--   through the wire all the time.
--   
--   The left signal interval is allowed to become zero, at which point the
--   signal is passed through the wire at every instant.
sample :: Monad m => Wire m a b -> Wire m (Time, a) b

-- | Wait for the first signal from the given wire and keep it forever.
swallow :: Monad m => Wire m a b -> Wire m a b

-- | Override the output value at the first non-inhibited instant.
(-->) :: Monad m => b -> Wire m a b -> Wire m a b

-- | Override the input value, until the wire starts producing.
(>--) :: Monad m => a -> Wire m a b -> Wire m a b

-- | Apply a function to the wire's output at the first non-inhibited
--   instant.
(-=>) :: Monad m => (b -> b) -> Wire m a b -> Wire m a b

-- | Apply a function to the wire's input, until the wire starts producing.
(>=-) :: Monad m => (a -> a) -> Wire m a b -> Wire m a b

-- | Produce the value of the second argument at the first instant. Then
--   produce the second value forever.
constantAfter :: Monad m => b -> b -> Wire m a b

-- | Produce the argument value at the first instant. Then act as the
--   identity signal transformer forever.
initially :: Monad m => a -> Wire m a a

-- | Apply an arrow to a list of inputs.
mapA :: ArrowChoice a => a b c -> a [b] [c]

-- | Duplicate a value to a tuple.
dup :: a -> (a, a)

-- | Floating point modulo operation. Note that <tt>fmod n 0</tt> = 0.
fmod :: Double -> Double -> Double

-- | Swap the values in a tuple.
swap :: (a, b) -> (b, a)


-- | Switching combinators. Note that <a>Wire</a> also provides a
--   state-preserving <tt>Control.Arrow.ArrowApply</tt> instance, which may
--   be more convenient than these combinators in many cases.
module FRP.NetWire.Switch

-- | This is the most basic switching combinator. It is an event-based
--   one-time switch.
--   
--   The first argument is the initial wire, which may produce a switching
--   event at some point. When this event is produced, then the signal path
--   switches to the wire produced by the second argument function.
switch :: Monad m => Wire m a (b, Event c) -> (c -> Wire m a b) -> Wire m a b

-- | Decoupled variant of <a>switch</a>.
dSwitch :: Monad m => Wire m a (b, Event c) -> (c -> Wire m a b) -> Wire m a b

-- | Combinator for recurrent switches. The wire produced by this switch
--   takes switching events and switches to the wires contained in the
--   events. The first argument is the initial wire.
rSwitch :: Monad m => Wire m a b -> Wire m (a, Event (Wire m a b)) b

-- | Decoupled variant of <a>rSwitch</a>.
drSwitch :: Monad m => Wire m a b -> Wire m (a, Event (Wire m a b)) b

-- | Broadcast signal to a collection of signal functions. If any of the
--   wires inhibits, then the whole parallel network inhibits.
parB :: (Applicative m, Monad m, Traversable f) => f (Wire m a b) -> Wire m a (f b)

-- | Recurrent parallel broadcast switch. This combinator acts like
--   <a>parB</a>, but takes an additional event signal, which can transform
--   the set of wires.
--   
--   Just like <a>parB</a> if any of the wires inhibits, the whole network
--   inhibits.
rpSwitchB :: (Applicative m, Monad m, Traversable f) => f (Wire m a b) -> Wire m (a, Event (f (Wire m a b) -> f (Wire m a b))) (f b)

-- | Decoupled variant of <a>rpSwitchB</a>.
drpSwitchB :: (Applicative m, Monad m, Traversable f) => f (Wire m a b) -> Wire m (a, Event (f (Wire m a b) -> f (Wire m a b))) (f b)

-- | Route signal to a collection of signal functions using the supplied
--   routing function. If any of the wires inhibits, the whole network
--   inhibits.
par :: (Applicative m, Monad m, Traversable f) => (forall w. a -> f w -> f (b, w)) -> f (Wire m b c) -> Wire m a (f c)

-- | Recurrent parallel routing switch. This combinator acts like
--   <a>par</a>, but takes an additional event signal, which can transform
--   the set of wires. This is the most powerful switch.
--   
--   Just like <a>par</a> if any of the wires inhibits, the whole network
--   inhibits.
rpSwitch :: (Applicative m, Monad m, Traversable f) => (forall w. a -> f w -> f (b, w)) -> f (Wire m b c) -> Wire m (a, Event (f (Wire m b c) -> f (Wire m b c))) (f c)

-- | Decoupled variant of <a>rpSwitch</a>.
drpSwitch :: (Applicative m, Monad m, Traversable f) => (forall w. a -> f w -> f (b, w)) -> f (Wire m b c) -> Wire m (a, Event (f (Wire m b c) -> f (Wire m b c))) (f c)


-- | Unique identifiers.
module FRP.NetWire.Request

-- | Choose a unique identifier when switching in and keep it.
identifier :: MonadIO m => Wire m a Int


-- | Noise generators.
module FRP.NetWire.Random

-- | Impure noise between 0 (inclusive) and 1 (exclusive).
noise :: MonadIO m => Wire m a Double

-- | Impure noise between -1 (inclusive) and 1 (exclusive).
noise1 :: MonadIO m => Wire m a Double

-- | Impure noise.
noiseGen :: (MonadIO m, MTRandom b) => Wire m a b

-- | Impure noise between 0 (inclusive) and the input signal (exclusive).
--   Note: The noise is generated by multiplying a <a>Double</a>, hence the
--   precision is limited.
noiseR :: (MonadIO m, Real a, Integral b) => Wire m a b

-- | Impure random boolean.
wackelkontakt :: MonadIO m => Wire m a Bool

-- | Pure noise. For impure wires it's recommended to use the impure noise
--   generators.
pureNoise :: (Monad m, RandomGen g, Random b) => g -> Wire m a b

-- | Pure noise in a range. For impure wires it's recommended to use the
--   impure noise generators.
pureNoiseR :: (Monad m, RandomGen g, Random b) => g -> Wire m (b, b) b


-- | Access the rest of the universe.
module FRP.NetWire.IO

-- | Execute the IO action in the input signal at every instant.
--   
--   Note: If the action throws an exception, then this wire inhibits the
--   signal.
execute :: MonadControlIO m => Wire m (m a) a

-- | Executes the IO action in the right input signal periodically keeping
--   its most recent result value.
executeEvery :: MonadControlIO m => Wire m (Time, m a) a

-- | Executes the IO action in the input signal and inhibits, until it
--   succeeds without an exception. Keeps the result forever.
executeOnce :: MonadControlIO m => Wire m (m a) a


-- | Events.
module FRP.NetWire.Event

-- | Produce an event once after the specified delay and never again. The
--   event's value will be the input signal at that point.
after :: Monad m => Time -> Wire m a (Event a)

-- | Produce an event according to the given list of time deltas and event
--   values. The time deltas are relative to each other, hence from the
--   perspective of switching in <tt>[(1, <tt>a</tt>), (2, <tt>b</tt>), (3,
--   <tt>c</tt>)]</tt> produces the event <tt><tt>a</tt></tt> after one
--   second, <tt><tt>b</tt></tt> after three seconds and
--   <tt><tt>c</tt></tt> after six seconds.
afterEach :: Monad m => [(Time, b)] -> Wire m a (Event b)

-- | Produce a single event with the right signal whenever the left signal
--   switches from <a>False</a> to <a>True</a>.
edge :: Monad m => Wire m (Bool, a) (Event a)

-- | Whenever the predicate in the first argument switches from
--   <a>False</a> to <a>True</a> for the input signal, produce an event
--   carrying the value given by applying the second argument function to
--   the input signal.
edgeBy :: Monad m => (a -> Bool) -> (a -> b) -> Wire m a (Event b)

-- | Produce a single event carrying the value of the input signal,
--   whenever the input signal switches to <a>Just</a>.
edgeJust :: Monad m => Wire m (Maybe a) (Event a)

-- | Never produce an event.
never :: Monad m => Wire m a (Event b)

-- | Produce an event at the first instant and never again.
now :: Monad m => b -> Wire m a (Event b)

-- | Pass the first event occurence through and suppress all future events.
once :: Monad m => Wire m (Event a) (Event a)

-- | Emit the right signal event each time the left signal interval passes.
repeatedly :: Monad m => Wire m (Time, a) (Event a)

-- | Each time the signal interval passes emit the next element from the
--   given list.
repeatedlyList :: Monad m => [a] -> Wire m Time (Event a)

-- | Inhibit the signal, unless an event occurs.
wait :: Monad m => Wire m (Event a) a

-- | Event dam. Collects all values from the input list and emits one value
--   at each instant.
--   
--   Note that this combinator can cause event congestion. If you feed
--   values faster than it can produce, it will leak memory.
dam :: Monad m => Wire m [a] (Event a)

-- | Delay events by the time interval in the left signal.
--   
--   Note that this event transformer has to keep all delayed events in
--   memory, which can cause event congestion. If events are fed in faster
--   than they can be produced (for example when the framerate starts to
--   drop), it will leak memory. Use <tt>delayEventSafe</tt> to prevent
--   this.
delayEvents :: Monad m => Wire m (Time, Event a) (Event a)

-- | Delay events by the time interval in the left signal. The event queue
--   is limited to the maximum number of events given by middle signal. If
--   the current queue grows to this size, then temporarily no further
--   events are queued.
--   
--   As suggested by the type, this maximum can change over time. However,
--   if it's decreased below the number of currently queued events, the
--   events are not deleted.
delayEventsSafe :: Monad m => Wire m (Time, Int, Event a) (Event a)

-- | Drop the given number of events, before passing events through.
dropEvents :: Monad m => Int -> Wire m (Event a) (Event a)

-- | Timed event gate for the right signal, which begins closed and opens
--   after the time interval in the left signal has passed.
dropFor :: Monad m => Wire m (Time, Event a) (Event a)

-- | Suppress the first event occurence.
notYet :: Monad m => Wire m (Event a) (Event a)

-- | Pass only the first given number of events. Then suppress events
--   forever.
takeEvents :: Monad m => Int -> Wire m (Event a) (Event a)

-- | Timed event gate for the right signal, which starts open and slams
--   shut after the left signal time interval passed.
takeFor :: Monad m => Wire m (Time, Event a) (Event a)

-- | This function corresponds to the <a>iterate</a> function for lists.
--   Begins with an initial output value, which is not emitted. Each time
--   an input event is received, its function is applied to the current
--   accumulator and the new value is emitted.
accum :: Monad m => a -> Wire m (Event (a -> a)) (Event a)

-- | Turn discrete events into continuous signals. Initially produces the
--   argument value. Each time an event occurs, the produced value is
--   switched to the event's value.
hold :: Monad m => a -> Wire m (Event a) a

-- | Decoupled variant of <a>hold</a>.
dHold :: Monad m => a -> Wire m (Event a) a


-- | Wire concurrency. Send signals through multiple wires concurrently.
--   This module is *highly experimental* and subject to change entirely in
--   future revisions. Please use it with care.
module FRP.NetWire.Concurrent

-- | Concurrent version of '(***)'. Passes its input signals to both
--   argument wires concurrently.
(~*~) :: Wire IO a c -> Wire IO b d -> Wire IO (a, b) (c, d)

-- | Concurrent version of '(&amp;&amp;&amp;)'. Passes its input signal to
--   both argument wires concurrently.
(~&~) :: Wire IO a b -> Wire IO a c -> Wire IO a (b, c)

-- | Concurrent version of '(<a>+</a>)'. Passes its input signal to both
--   argument wires concurrently, returning the result of the first wire
--   which does not inhibit.
(~+~) :: NFData b => Wire IO a b -> Wire IO a b -> Wire IO a b


-- | Calculus functions.
module FRP.NetWire.Calculus

-- | Differentiate over time. Inhibits at first instant.
derivative :: (Monad m, NFData v, VectorSpace v, (Scalar v) ~ Double) => Wire m v v

-- | Differentiate over time. The argument is the value before the first
--   instant.
derivativeFrom :: (Monad m, NFData v, VectorSpace v, (Scalar v) ~ Double) => v -> Wire m v v

-- | Integrate over time. The argument is the integration constant.
integral :: (Monad m, NFData v, VectorSpace v, (Scalar v) ~ Double) => v -> Wire m v v


-- | Signal analysis.
module FRP.NetWire.Analyze

-- | Emits an event, whenever the input signal changes. The event contains
--   the last input value and the time elapsed since the last change.
diff :: (Eq a, Monad m) => Wire m a (Event (a, Time))

-- | Calculate the average of the signal over the given number of last
--   samples. This wire has O(n) space complexity and O(1) time complexity.
--   
--   If you need an average over all samples ever produced, consider using
--   <a>avgAll</a> instead.
avg :: (Fractional v, Monad m, NFData v, Unbox v) => Int -> Wire m v v

-- | Calculate the average of the signal over all samples.
--   
--   Please note that somewhat surprisingly this wire runs in constant
--   space and is generally faster than <a>avg</a>, but most applications
--   will benefit from averages over only the last few samples.
avgAll :: (Fractional v, Monad m, NFData v) => Wire m v v

-- | Calculate the average number of frames per virtual second for the last
--   given number of frames.
--   
--   Please note that this wire uses the clock, which you give the network
--   using the stepping functions in <a>FRP.NetWire.Session</a>. If this
--   clock doesn't represent real time, then the output of this wire won't
--   either.
avgFps :: Monad m => Int -> Wire m a Double

-- | Return the high peak.
highPeak :: (Monad m, NFData a, Ord a) => Wire m a a

-- | Return the low peak.
lowPeak :: (Monad m, NFData a, Ord a) => Wire m a a

-- | Return the high peak with the given comparison function.
peakBy :: (Monad m, NFData a) => (a -> a -> Ordering) -> Wire m a a


-- | Arrowized FRP implementation for networking applications. The aim of
--   this library is to provide a convenient FRP implementation, which
--   should enable you to write entirely pure network sessions.
module FRP.NetWire

-- | A wire is a network of signal transformers.
data Wire :: (* -> *) -> * -> * -> *

-- | Events are signals, which can be absent. They usually denote discrete
--   occurences of certain events.
type Event = Maybe

-- | The output of a wire. When the wire inhibits, then this will be a
--   <a>Left</a> value with an exception.
type Output = Either SomeException

-- | Time.
type Time = Double

-- | Reactive sessions with the given time type.
data Session a b

-- | Feed the given input value into the reactive system performing the
--   next instant using real time.
stepWire :: a -> Session a b -> IO (Output b)

-- | Feed the given input value into the reactive system performing the
--   next instant using the given time delta.
stepWireDelta :: NominalDiffTime -> a -> Session a b -> IO (Output b)

-- | Feed the given input value into the reactive system performing the
--   next instant, which is at the given time. This function is
--   thread-safe.
stepWireTime :: UTCTime -> a -> Session a b -> IO (Output b)

-- | Initialize a reactive session and pass it to the given continuation.
withWire :: Wire IO a b -> (Session a b -> IO c) -> IO c

-- | Signal functions are wires over the identity monad.
type SF = Wire Identity

-- | Perform the next instant of a pure wire over the identity monad.
stepSF :: Time -> a -> SF a b -> (Output b, SF a b)

-- | Perform the next instant of a pure wire.
stepWirePure :: Monad m => Time -> a -> Wire m a b -> m (Output b, Wire m a b)