{-# LANGUAGE Arrows     #-}
{-# LANGUAGE CPP        #-}
{-# LANGUAGE RankNTypes #-}
-- The following warning is disabled so that we do not see warnings due to
-- using ListT on an MSF to implement parallelism with broadcasting.
#if __GLASGOW_HASKELL__ < 800
{-# OPTIONS_GHC -fno-warn-warnings-deprecations #-}
#else
{-# OPTIONS_GHC -Wno-deprecations #-}
#endif
{-# OPTIONS_HADDOCK ignore-exports #-}
-- Copyright  : (c) Ivan Perez, 2019-2022
--              (c) Ivan Perez and Manuel Baerenz, 2016-2018
-- License    : BSD3
-- Maintainer : ivan.perez@keera.co.uk
module FRP.BearRiver
  (module FRP.BearRiver, module X)
 where
-- This is an implementation of Yampa using our Monadic Stream Processing
-- library. We focus only on core Yampa. We will use this module later to
-- reimplement an example of a Yampa system.
--
-- While we may not introduce all the complexity of Yampa today (all kinds of
-- switches, etc.) our goal is to show that the approach is promising and that
-- there do not seem to exist any obvious limitations.

-- External imports
import           Control.Applicative
import           Control.Arrow             as X
import qualified Control.Category          as Category
import           Control.DeepSeq           (NFData (..))
import           Control.Monad             (mapM)
import qualified Control.Monad.Fail        as Fail
import           Control.Monad.Random
import           Control.Monad.Trans.Maybe
import           Data.Functor.Identity
import           Data.Maybe
import           Data.Traversable          as T
import           Data.VectorSpace          as X

-- Internal imports
import           Control.Monad.Trans.MSF                 hiding (dSwitch,
                                                          switch)
import qualified Control.Monad.Trans.MSF                 as MSF
import           Control.Monad.Trans.MSF.Except          as MSF hiding (dSwitch,
                                                                 switch)
import           Control.Monad.Trans.MSF.List            (sequenceS, widthFirst)
import           Control.Monad.Trans.MSF.Random
import           Data.MonadicStreamFunction              as X hiding (dSwitch,
                                                               reactimate,
                                                               repeatedly, sum,
                                                               switch, trace)
import qualified Data.MonadicStreamFunction              as MSF
import           Data.MonadicStreamFunction.InternalCore

-- Internal imports (instances)
import Data.MonadicStreamFunction.Instances.ArrowLoop

infixr 0 -->, -:>, >--, >=-

-- * Basic definitions

-- | Time is used both for time intervals (duration), and time w.r.t. some
-- agreed reference point in time.
type Time  = Double

-- | DTime is the time type for lengths of sample intervals. Conceptually,
-- DTime = R+ = { x in R | x > 0 }. Don't assume Time and DTime have the
-- same representation.
type DTime = Double

-- | Extensible signal function (signal function with a notion of time, but
-- which can be extended with actions).
-- Signal function that transforms a signal carrying values of some type 'a'
-- into a signal carrying values of some type 'b'. You can think of it as
-- (Signal a -> Signal b). A signal is, conceptually, a
-- function from 'Time' to value.
type SF m        = MSF (ClockInfo m)

-- | Information on the progress of time.
type ClockInfo m = ReaderT DTime m

-- | A single possible event occurrence, that is, a value that may or may not
-- occur. Events are used to represent values that are not produced
-- continuously, such as mouse clicks (only produced when the mouse is clicked,
-- as opposed to mouse positions, which are always defined).
data Event a = Event a | NoEvent
 deriving (Event a -> Event a -> Bool
forall a. Eq a => Event a -> Event a -> Bool
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: Event a -> Event a -> Bool
$c/= :: forall a. Eq a => Event a -> Event a -> Bool
== :: Event a -> Event a -> Bool
$c== :: forall a. Eq a => Event a -> Event a -> Bool
Eq, Event a -> Event a -> Bool
Event a -> Event a -> Ordering
forall a.
Eq a
-> (a -> a -> Ordering)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> a)
-> (a -> a -> a)
-> Ord a
forall {a}. Ord a => Eq (Event a)
forall a. Ord a => Event a -> Event a -> Bool
forall a. Ord a => Event a -> Event a -> Ordering
forall a. Ord a => Event a -> Event a -> Event a
min :: Event a -> Event a -> Event a
$cmin :: forall a. Ord a => Event a -> Event a -> Event a
max :: Event a -> Event a -> Event a
$cmax :: forall a. Ord a => Event a -> Event a -> Event a
>= :: Event a -> Event a -> Bool
$c>= :: forall a. Ord a => Event a -> Event a -> Bool
> :: Event a -> Event a -> Bool
$c> :: forall a. Ord a => Event a -> Event a -> Bool
<= :: Event a -> Event a -> Bool
$c<= :: forall a. Ord a => Event a -> Event a -> Bool
< :: Event a -> Event a -> Bool
$c< :: forall a. Ord a => Event a -> Event a -> Bool
compare :: Event a -> Event a -> Ordering
$ccompare :: forall a. Ord a => Event a -> Event a -> Ordering
Ord, Int -> Event a -> ShowS
forall a. Show a => Int -> Event a -> ShowS
forall a. Show a => [Event a] -> ShowS
forall a. Show a => Event a -> String
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
showList :: [Event a] -> ShowS
$cshowList :: forall a. Show a => [Event a] -> ShowS
show :: Event a -> String
$cshow :: forall a. Show a => Event a -> String
showsPrec :: Int -> Event a -> ShowS
$cshowsPrec :: forall a. Show a => Int -> Event a -> ShowS
Show)

-- | The type 'Event' is isomorphic to 'Maybe'. The 'Functor' instance of
-- 'Event' is analogous to the 'Functo' instance of 'Maybe', where the given
-- function is applied to the value inside the 'Event', if any.
instance Functor Event where
  fmap :: forall a b. (a -> b) -> Event a -> Event b
fmap a -> b
_ Event a
NoEvent   = forall a. Event a
NoEvent
  fmap a -> b
f (Event a
c) = forall a. a -> Event a
Event (a -> b
f a
c)

-- | The type 'Event' is isomorphic to 'Maybe'. The 'Applicative' instance of
-- 'Event' is analogous to the 'Applicative' instance of 'Maybe', where the
-- lack of a value (i.e., 'NoEvent') causes '(<*>)' to produce no value
-- ('NoEvent').
instance Applicative Event where
  pure :: forall a. a -> Event a
pure = forall a. a -> Event a
Event

  Event a -> b
f <*> :: forall a b. Event (a -> b) -> Event a -> Event b
<*> Event a
x = forall a. a -> Event a
Event (a -> b
f a
x)
  Event (a -> b)
_       <*> Event a
_       = forall a. Event a
NoEvent

-- | The type 'Event' is isomorphic to 'Maybe'. The 'Monad' instance of 'Event'
-- is analogous to the 'Monad' instance of 'Maybe', where the lack of a value
-- (i.e., 'NoEvent') causes bind to produce no value ('NoEvent').
instance Monad Event where
  return :: forall a. a -> Event a
return = forall (f :: * -> *) a. Applicative f => a -> f a
pure

  Event a
x >>= :: forall a b. Event a -> (a -> Event b) -> Event b
>>= a -> Event b
f = a -> Event b
f a
x
  Event a
NoEvent >>= a -> Event b
_ = forall a. Event a
NoEvent

-- | MonadFail instance
instance Fail.MonadFail Event where
  -- | Fail with 'NoEvent'.
  fail :: forall a. String -> Event a
fail String
_ = forall a. Event a
NoEvent

-- | Alternative instance
instance Alternative Event where
  -- | An empty alternative carries no event, so it is ignored.
  empty :: forall a. Event a
empty = forall a. Event a
NoEvent
  -- | Merge favouring the left event ('NoEvent' only if both are
  -- 'NoEvent').
  Event a
NoEvent <|> :: forall a. Event a -> Event a -> Event a
<|> Event a
r = Event a
r
  Event a
l       <|> Event a
_ = Event a
l

-- | NFData instance
instance NFData a => NFData (Event a) where
  -- | Evaluate value carried by event.
  rnf :: Event a -> ()
rnf Event a
NoEvent   = ()
  rnf (Event a
a) = forall a. NFData a => a -> ()
rnf a
a seq :: forall a b. a -> b -> b
`seq` ()

-- ** Lifting

-- | Lifts a pure function into a signal function (applied pointwise).
arrPrim :: Monad m => (a -> b) -> SF m a b
arrPrim :: forall (m :: * -> *) a b. Monad m => (a -> b) -> SF m a b
arrPrim = forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr

-- | Lifts a pure function into a signal function applied to events (applied
-- pointwise).
arrEPrim :: Monad m => (Event a -> b) -> SF m (Event a) b
arrEPrim :: forall (m :: * -> *) a b.
Monad m =>
(Event a -> b) -> SF m (Event a) b
arrEPrim = forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr

-- * Signal functions

-- ** Basic signal functions

-- | Identity: identity = arr id
--
-- Using 'identity' is preferred over lifting id, since the arrow combinators
-- know how to optimise certain networks based on the transformations being
-- applied.
identity :: Monad m => SF m a a
identity :: forall (m :: * -> *) a. Monad m => SF m a a
identity = forall {k} (cat :: k -> k -> *) (a :: k). Category cat => cat a a
Category.id

-- | Identity: constant b = arr (const b)
--
-- Using 'constant' is preferred over lifting const, since the arrow combinators
-- know how to optimise certain networks based on the transformations being
-- applied.
constant :: Monad m => b -> SF m a b
constant :: forall (m :: * -> *) b a. Monad m => b -> SF m a b
constant = forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall a b. a -> b -> a
const

-- | Outputs the time passed since the signal function instance was started.
localTime :: Monad m => SF m a Time
localTime :: forall (m :: * -> *) a. Monad m => SF m a Time
localTime = forall (m :: * -> *) b a. Monad m => b -> SF m a b
constant Time
1.0 forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
SF m a a
integral

-- | Alternative name for localTime.
time :: Monad m => SF m a Time
time :: forall (m :: * -> *) a. Monad m => SF m a Time
time = forall (m :: * -> *) a. Monad m => SF m a Time
localTime

-- ** Initialization

-- | Initialization operator (cf. Lustre/Lucid Synchrone).
--
-- The output at time zero is the first argument, and from
-- that point on it behaves like the signal function passed as
-- second argument.
(-->) :: Monad m => b -> SF m a b -> SF m a b
b
b0 --> :: forall (m :: * -> *) b a. Monad m => b -> SF m a b -> SF m a b
--> SF m a b
sf = SF m a b
sf forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (m :: * -> *) a. Monad m => a -> SF m a a
replaceOnce b
b0

-- | Output pre-insert operator.
--
-- Insert a sample in the output, and from that point on, behave
-- like the given sf.
(-:>) :: Monad m => b -> SF m a b -> SF m a b
b
b -:> :: forall (m :: * -> *) b a. Monad m => b -> SF m a b -> SF m a b
-:> SF m a b
sf = forall (m :: * -> *) b a. Monad m => b -> MSF m a b -> MSF m a b
iPost b
b SF m a b
sf

-- | Input initialization operator.
--
-- The input at time zero is the first argument, and from
-- that point on it behaves like the signal function passed as
-- second argument.
(>--) :: Monad m => a -> SF m a b -> SF m a b
a
a0 >-- :: forall (m :: * -> *) a b. Monad m => a -> SF m a b -> SF m a b
>-- SF m a b
sf = forall (m :: * -> *) a. Monad m => a -> SF m a a
replaceOnce a
a0 forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> SF m a b
sf

(>=-) :: Monad m => (a -> a) -> SF m a b -> SF m a b
a -> a
f >=- :: forall (m :: * -> *) a b.
Monad m =>
(a -> a) -> SF m a b -> SF m a b
>=- SF m a b
sf = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \a
a -> do
  (b
b, SF m a b
sf') <- forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF SF m a b
sf (a -> a
f a
a)
  forall (m :: * -> *) a. Monad m => a -> m a
return (b
b, SF m a b
sf')

initially :: Monad m => a -> SF m a a
initially :: forall (m :: * -> *) a. Monad m => a -> SF m a a
initially = (forall (m :: * -> *) b a. Monad m => b -> SF m a b -> SF m a b
--> forall (m :: * -> *) a. Monad m => SF m a a
identity)

-- * Simple, stateful signal processing

-- | Applies a function point-wise, using the last output as next input. This
-- creates a well-formed loop based on a pure, auxiliary function.
sscan :: Monad m => (b -> a -> b) -> b -> SF m a b
sscan :: forall (m :: * -> *) b a. Monad m => (b -> a -> b) -> b -> SF m a b
sscan b -> a -> b
f b
b_init = forall (m :: * -> *) c a b.
Monad m =>
c -> MSF m (a, c) (b, c) -> MSF m a b
feedback b
b_init forall {a}. a
u
  where u :: a
u = forall a. HasCallStack => a
undefined -- (arr f >>^ dup)

-- | Generic version of 'sscan', in which the auxiliary function produces
-- an internal accumulator and an "held" output.
--
-- Applies a function point-wise, using the last known 'Just' output to form
-- the output, and next input accumulator. If the output is 'Nothing', the last
-- known accumulators are used. This creates a well-formed loop based on a
-- pure, auxiliary function.
sscanPrim :: Monad m => (c -> a -> Maybe (c, b)) -> c -> b -> SF m a b
sscanPrim :: forall (m :: * -> *) c a b.
Monad m =>
(c -> a -> Maybe (c, b)) -> c -> b -> SF m a b
sscanPrim c -> a -> Maybe (c, b)
f c
c_init b
b_init = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \a
a -> do
  let o :: Maybe (c, b)
o = c -> a -> Maybe (c, b)
f c
c_init a
a
  case Maybe (c, b)
o of
    Maybe (c, b)
Nothing       -> forall (m :: * -> *) a. Monad m => a -> m a
return (b
b_init, forall (m :: * -> *) c a b.
Monad m =>
(c -> a -> Maybe (c, b)) -> c -> b -> SF m a b
sscanPrim c -> a -> Maybe (c, b)
f c
c_init b
b_init)
    Just (c
c', b
b') -> forall (m :: * -> *) a. Monad m => a -> m a
return (b
b',     forall (m :: * -> *) c a b.
Monad m =>
(c -> a -> Maybe (c, b)) -> c -> b -> SF m a b
sscanPrim c -> a -> Maybe (c, b)
f c
c' b
b')


-- | Event source that never occurs.
never :: Monad m => SF m a (Event b)
never :: forall (m :: * -> *) a b. Monad m => SF m a (Event b)
never = forall (m :: * -> *) b a. Monad m => b -> SF m a b
constant forall a. Event a
NoEvent

-- | Event source with a single occurrence at time 0. The value of the event
-- is given by the function argument.
now :: Monad m => b -> SF m a (Event b)
now :: forall (m :: * -> *) b a. Monad m => b -> SF m a (Event b)
now b
b0 = forall a. a -> Event a
Event b
b0 forall (m :: * -> *) b a. Monad m => b -> SF m a b -> SF m a b
--> forall (m :: * -> *) a b. Monad m => SF m a (Event b)
never

-- | Event source with a single occurrence at or as soon after (local) time /q/
-- as possible.
after :: Monad m
      => Time -- ^ The time /q/ after which the event should be produced
      -> b    -- ^ Value to produce at that time
      -> SF m a (Event b)
after :: forall (m :: * -> *) b a. Monad m => Time -> b -> SF m a (Event b)
after Time
q b
x = forall (m :: * -> *) c a b.
Monad m =>
c -> MSF m (a, c) (b, c) -> MSF m a b
feedback Time
q forall {a}. MSF (ClockInfo m) (a, Time) (Event b, Time)
go
 where go :: MSF (ClockInfo m) (a, Time) (Event b, Time)
go = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \(a
_, Time
t) -> do
              Time
dt <- forall (m :: * -> *) r. Monad m => ReaderT r m r
ask
              let t' :: Time
t' = Time
t forall a. Num a => a -> a -> a
- Time
dt
                  e :: Event b
e  = if Time
t forall a. Ord a => a -> a -> Bool
> Time
0 Bool -> Bool -> Bool
&& Time
t' forall a. Ord a => a -> a -> Bool
< Time
0 then forall a. a -> Event a
Event b
x else forall a. Event a
NoEvent
                  ct :: MSF (ClockInfo m) (a, Time) (Event b, Time)
ct = if Time
t' forall a. Ord a => a -> a -> Bool
< Time
0 then forall (m :: * -> *) b a. Monad m => b -> SF m a b
constant (forall a. Event a
NoEvent, Time
t') else MSF (ClockInfo m) (a, Time) (Event b, Time)
go
              forall (m :: * -> *) a. Monad m => a -> m a
return ((Event b
e, Time
t'), MSF (ClockInfo m) (a, Time) (Event b, Time)
ct)

-- | Event source with repeated occurrences with interval q.
-- Note: If the interval is too short w.r.t. the sampling intervals,
-- the result will be that events occur at every sample. However, no more
-- than one event results from any sampling interval, thus avoiding an
-- "event backlog" should sampling become more frequent at some later
-- point in time.
repeatedly :: Monad m => Time -> b -> SF m a (Event b)
repeatedly :: forall (m :: * -> *) b a. Monad m => Time -> b -> SF m a (Event b)
repeatedly Time
q b
x
    | Time
q forall a. Ord a => a -> a -> Bool
> Time
0     = forall (m :: * -> *) b a.
Monad m =>
[(Time, b)] -> SF m a (Event b)
afterEach [(Time, b)]
qxs
    | Bool
otherwise = forall a. HasCallStack => String -> a
error String
"bearriver: repeatedly: Non-positive period."
  where
    qxs :: [(Time, b)]
qxs = (Time
q,b
x)forall a. a -> [a] -> [a]
:[(Time, b)]
qxs

-- | Event source with consecutive occurrences at the given intervals.
-- Should more than one event be scheduled to occur in any sampling interval,
-- only the first will in fact occur to avoid an event backlog.

-- After all, after, repeatedly etc. are defined in terms of afterEach.
afterEach :: Monad m => [(Time,b)] -> SF m a (Event b)
afterEach :: forall (m :: * -> *) b a.
Monad m =>
[(Time, b)] -> SF m a (Event b)
afterEach [(Time, b)]
qxs = forall (m :: * -> *) b a.
Monad m =>
[(Time, b)] -> SF m a (Event [b])
afterEachCat [(Time, b)]
qxs forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a. [a] -> a
head)

-- | Event source with consecutive occurrences at the given intervals.
-- Should more than one event be scheduled to occur in any sampling interval,
-- the output list will contain all events produced during that interval.
afterEachCat :: Monad m => [(Time,b)] -> SF m a (Event [b])
afterEachCat :: forall (m :: * -> *) b a.
Monad m =>
[(Time, b)] -> SF m a (Event [b])
afterEachCat = forall (m :: * -> *) b a.
Monad m =>
Time -> [(Time, b)] -> SF m a (Event [b])
afterEachCat' Time
0
  where
    afterEachCat' :: Monad m => Time -> [(Time,b)] -> SF m a (Event [b])
    afterEachCat' :: forall (m :: * -> *) b a.
Monad m =>
Time -> [(Time, b)] -> SF m a (Event [b])
afterEachCat' Time
_ [] = forall (m :: * -> *) a b. Monad m => SF m a (Event b)
never
    afterEachCat' Time
t [(Time, b)]
qxs = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \a
_ -> do
      Time
dt <- forall (m :: * -> *) r. Monad m => ReaderT r m r
ask
      let ([b]
ev, Time
t', [(Time, b)]
qxs') = forall b. [b] -> Time -> [(Time, b)] -> ([b], Time, [(Time, b)])
fireEvents [] (Time
t forall a. Num a => a -> a -> a
+ Time
dt) [(Time, b)]
qxs
          ev' :: Event [b]
ev' = if forall (t :: * -> *) a. Foldable t => t a -> Bool
null [b]
ev
                  then forall a. Event a
NoEvent
                  else forall a. a -> Event a
Event (forall a. [a] -> [a]
reverse [b]
ev)

      forall (m :: * -> *) a. Monad m => a -> m a
return (Event [b]
ev', forall (m :: * -> *) b a.
Monad m =>
Time -> [(Time, b)] -> SF m a (Event [b])
afterEachCat' Time
t' [(Time, b)]
qxs')

    fireEvents :: [b] -> Time -> [(Time,b)] -> ([b], Time, [(Time,b)])
    fireEvents :: forall b. [b] -> Time -> [(Time, b)] -> ([b], Time, [(Time, b)])
fireEvents [b]
ev Time
t [] = ([b]
ev, Time
t, [])
    fireEvents [b]
ev Time
t ((Time, b)
qx:[(Time, b)]
qxs)
      | forall a b. (a, b) -> a
fst (Time, b)
qx forall a. Ord a => a -> a -> Bool
< Time
0 = forall a. HasCallStack => String -> a
error String
"bearriver: afterEachCat: Non-positive period."
      | Bool
otherwise =
          let overdue :: Time
overdue = Time
t forall a. Num a => a -> a -> a
- forall a b. (a, b) -> a
fst (Time, b)
qx in
          if Time
overdue forall a. Ord a => a -> a -> Bool
>= Time
0
            then forall b. [b] -> Time -> [(Time, b)] -> ([b], Time, [(Time, b)])
fireEvents (forall a b. (a, b) -> b
snd (Time, b)
qxforall a. a -> [a] -> [a]
:[b]
ev) Time
overdue [(Time, b)]
qxs
            else ([b]
ev, Time
t, (Time, b)
qxforall a. a -> [a] -> [a]
:[(Time, b)]
qxs)

-- * Events

-- | Apply an 'MSF' to every input. Freezes temporarily if the input is
-- 'NoEvent', and continues as soon as an 'Event' is received.
mapEventS :: Monad m => MSF m a b -> MSF m (Event a) (Event b)
mapEventS :: forall (m :: * -> *) a b.
Monad m =>
MSF m a b -> MSF m (Event a) (Event b)
mapEventS MSF m a b
msf = proc Event a
eventA -> case Event a
eventA of
  Event a
a -> forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall a. a -> Event a
Event forall {k} (cat :: k -> k -> *) (b :: k) (c :: k) (a :: k).
Category cat =>
cat b c -> cat a b -> cat a c
<<< MSF m a b
msf -< a
a
  Event a
NoEvent -> forall (a :: * -> * -> *) b. Arrow a => a b b
returnA           -< forall a. Event a
NoEvent

-- ** Relation to other types

eventToMaybe :: Event a -> Maybe a
eventToMaybe = forall a b. a -> (b -> a) -> Event b -> a
event forall a. Maybe a
Nothing forall a. a -> Maybe a
Just

boolToEvent :: Bool -> Event ()
boolToEvent :: Bool -> Event ()
boolToEvent Bool
True  = forall a. a -> Event a
Event ()
boolToEvent Bool
False = forall a. Event a
NoEvent

-- * Hybrid SF m combinators

-- | A rising edge detector. Useful for things like detecting key presses.
-- It is initialised as /up/, meaning that events occurring at time 0 will
-- not be detected.
edge :: Monad m => SF m Bool (Event ())
edge :: forall (m :: * -> *). Monad m => SF m Bool (Event ())
edge = forall (m :: * -> *). Monad m => Bool -> SF m Bool (Event ())
edgeFrom Bool
True

-- | A rising edge detector that can be initialized as up ('True', meaning
-- that events occurring at time 0 will not be detected) or down
-- ('False', meaning that events occurring at time 0 will be detected).
iEdge :: Monad m => Bool -> SF m Bool (Event ())
iEdge :: forall (m :: * -> *). Monad m => Bool -> SF m Bool (Event ())
iEdge = forall (m :: * -> *). Monad m => Bool -> SF m Bool (Event ())
edgeFrom

-- | Like 'edge', but parameterized on the tag value.
--
-- From Yampa
edgeTag :: Monad m => a -> SF m Bool (Event a)
edgeTag :: forall (m :: * -> *) a. Monad m => a -> SF m Bool (Event a)
edgeTag a
a = forall (m :: * -> *). Monad m => SF m Bool (Event ())
edge forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr (forall a b. Event a -> b -> Event b
`tag` a
a)

-- | Edge detector particularized for detecting transtitions
--   on a 'Maybe' signal from 'Nothing' to 'Just'.
--
-- From Yampa

-- !!! 2005-07-09: To be done or eliminated
-- !!! Maybe could be kept as is, but could be easy to implement directly
-- !!! in terms of sscan?
edgeJust :: Monad m => SF m (Maybe a) (Event a)
edgeJust :: forall (m :: * -> *) a. Monad m => SF m (Maybe a) (Event a)
edgeJust = forall (m :: * -> *) a b.
Monad m =>
(a -> a -> Maybe b) -> a -> SF m a (Event b)
edgeBy forall {a} {a}. Maybe a -> Maybe a -> Maybe a
isJustEdge (forall a. a -> Maybe a
Just forall a. HasCallStack => a
undefined)
    where
        isJustEdge :: Maybe a -> Maybe a -> Maybe a
isJustEdge Maybe a
Nothing  Maybe a
Nothing     = forall a. Maybe a
Nothing
        isJustEdge Maybe a
Nothing  ma :: Maybe a
ma@(Just a
_) = Maybe a
ma
        isJustEdge (Just a
_) (Just a
_)    = forall a. Maybe a
Nothing
        isJustEdge (Just a
_) Maybe a
Nothing     = forall a. Maybe a
Nothing

-- | Edge detector parameterized on the edge detection function and initial
-- state, i.e., the previous input sample. The first argument to the
-- edge detection function is the previous sample, the second the current one.
edgeBy :: Monad m => (a -> a -> Maybe b) -> a -> SF m a (Event b)
edgeBy :: forall (m :: * -> *) a b.
Monad m =>
(a -> a -> Maybe b) -> a -> SF m a (Event b)
edgeBy a -> a -> Maybe b
isEdge a
a_prev = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \a
a ->
  forall (m :: * -> *) a. Monad m => a -> m a
return (forall a. Maybe a -> Event a
maybeToEvent (a -> a -> Maybe b
isEdge a
a_prev a
a), forall (m :: * -> *) a b.
Monad m =>
(a -> a -> Maybe b) -> a -> SF m a (Event b)
edgeBy a -> a -> Maybe b
isEdge a
a)

-- | Convert a maybe value into a event ('Event' is isomorphic to 'Maybe').
maybeToEvent :: Maybe a -> Event a
maybeToEvent :: forall a. Maybe a -> Event a
maybeToEvent = forall b a. b -> (a -> b) -> Maybe a -> b
maybe forall a. Event a
NoEvent forall a. a -> Event a
Event

edgeFrom :: Monad m => Bool -> SF m Bool (Event())
edgeFrom :: forall (m :: * -> *). Monad m => Bool -> SF m Bool (Event ())
edgeFrom Bool
prev = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \Bool
a -> do
  let res :: Event ()
res | Bool
prev      = forall a. Event a
NoEvent
          | Bool
a         = forall a. a -> Event a
Event ()
          | Bool
otherwise = forall a. Event a
NoEvent
      ct :: MSF (ReaderT Time m) Bool (Event ())
ct  = forall (m :: * -> *). Monad m => Bool -> SF m Bool (Event ())
edgeFrom Bool
a
  forall (m :: * -> *) a. Monad m => a -> m a
return (Event ()
res, MSF (ReaderT Time m) Bool (Event ())
ct)

-- * Stateful event suppression

-- | Suppression of initial (at local time 0) event.
notYet :: Monad m => SF m (Event a) (Event a)
notYet :: forall (m :: * -> *) a. Monad m => SF m (Event a) (Event a)
notYet = forall (m :: * -> *) c a b.
Monad m =>
c -> MSF m (a, c) (b, c) -> MSF m a b
feedback Bool
False forall a b. (a -> b) -> a -> b
$ forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr (\(Event a
e,Bool
c) ->
  if Bool
c then (Event a
e, Bool
True) else (forall a. Event a
NoEvent, Bool
True))

-- | Suppress all but the first event.
once :: Monad m => SF m (Event a) (Event a)
once :: forall (m :: * -> *) a. Monad m => SF m (Event a) (Event a)
once = forall (m :: * -> *) a. Monad m => Int -> SF m (Event a) (Event a)
takeEvents Int
1

-- | Suppress all but the first n events.
takeEvents :: Monad m => Int -> SF m (Event a) (Event a)
takeEvents :: forall (m :: * -> *) a. Monad m => Int -> SF m (Event a) (Event a)
takeEvents Int
n | Int
n forall a. Ord a => a -> a -> Bool
<= Int
0 = forall (m :: * -> *) a b. Monad m => SF m a (Event b)
never
takeEvents Int
n = forall (m :: * -> *) a b c.
Monad m =>
SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
dSwitch (forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall {b}. b -> (b, b)
dup) (forall a b. a -> b -> a
const (forall a. Event a
NoEvent forall (m :: * -> *) a b. Monad m => a -> SF m a b -> SF m a b
>-- forall (m :: * -> *) a. Monad m => Int -> SF m (Event a) (Event a)
takeEvents (Int
n forall a. Num a => a -> a -> a
- Int
1)))

-- | Suppress first n events.

-- Here dSwitch or switch does not really matter.
dropEvents :: Monad m => Int -> SF m (Event a) (Event a)
dropEvents :: forall (m :: * -> *) a. Monad m => Int -> SF m (Event a) (Event a)
dropEvents Int
n | Int
n forall a. Ord a => a -> a -> Bool
<= Int
0  = forall (m :: * -> *) a. Monad m => SF m a a
identity
dropEvents Int
n = forall (m :: * -> *) a b c.
Monad m =>
SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
dSwitch (forall (m :: * -> *) a b. Monad m => SF m a (Event b)
never forall (a :: * -> * -> *) b c c'.
Arrow a =>
a b c -> a b c' -> a b (c, c')
&&& forall (m :: * -> *) a. Monad m => SF m a a
identity)
                             (forall a b. a -> b -> a
const (forall a. Event a
NoEvent forall (m :: * -> *) a b. Monad m => a -> SF m a b -> SF m a b
>-- forall (m :: * -> *) a. Monad m => Int -> SF m (Event a) (Event a)
dropEvents (Int
n forall a. Num a => a -> a -> a
- Int
1)))

-- * Pointwise functions on events

-- | Make the NoEvent constructor available. Useful e.g. for initialization,
-- ((-->) & friends), and it's easily available anyway (e.g. mergeEvents []).
noEvent :: Event a
noEvent :: forall a. Event a
noEvent = forall a. Event a
NoEvent

-- | Suppress any event in the first component of a pair.
noEventFst :: (Event a, b) -> (Event c, b)
noEventFst :: forall a b c. (Event a, b) -> (Event c, b)
noEventFst (Event a
_, b
b) = (forall a. Event a
NoEvent, b
b)


-- | Suppress any event in the second component of a pair.
noEventSnd :: (a, Event b) -> (a, Event c)
noEventSnd :: forall a b c. (a, Event b) -> (a, Event c)
noEventSnd (a
a, Event b
_) = (a
a, forall a. Event a
NoEvent)

-- | An event-based version of the maybe function.
event :: a -> (b -> a) -> Event b -> a
event :: forall a b. a -> (b -> a) -> Event b -> a
event a
_ b -> a
f (Event b
x) = b -> a
f b
x
event a
x b -> a
_ Event b
NoEvent   = a
x

-- | Extract the value from an event. Fails if there is no event.
fromEvent :: Event a -> a
fromEvent (Event a
x) = a
x
fromEvent Event a
_         = forall a. HasCallStack => String -> a
error String
"fromEvent NoEvent"

-- | Tests whether the input represents an actual event.
isEvent :: Event a -> Bool
isEvent (Event a
_) = Bool
True
isEvent Event a
_         = Bool
False

-- | Negation of 'isEvent'.
isNoEvent :: Event a -> Bool
isNoEvent (Event a
_) = Bool
False
isNoEvent Event a
_         = Bool
True

-- | Tags an (occurring) event with a value ("replacing" the old value).
--
-- Applicative-based definition:
-- tag = ($>)
tag :: Event a -> b -> Event b
tag :: forall a b. Event a -> b -> Event b
tag Event a
NoEvent   b
_ = forall a. Event a
NoEvent
tag (Event a
_) b
b = forall a. a -> Event a
Event b
b

-- | Tags an (occurring) event with a value ("replacing" the old value). Same
-- as 'tag' with the arguments swapped.
--
-- Applicative-based definition:
-- tagWith = (<$)
tagWith :: b -> Event a -> Event b
tagWith :: forall a b. a -> Event b -> Event a
tagWith = forall a b c. (a -> b -> c) -> b -> a -> c
flip forall a b. Event a -> b -> Event b
tag

-- | Attaches an extra value to the value of an occurring event.
attach :: Event a -> b -> Event (a, b)
Event a
e attach :: forall a b. Event a -> b -> Event (a, b)
`attach` b
b = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (\a
a -> (a
a, b
b)) Event a
e

-- | Left-biased event merge (always prefer left event, if present).
lMerge :: Event a -> Event a -> Event a
lMerge :: forall a. Event a -> Event a -> Event a
lMerge = forall a. (a -> a -> a) -> Event a -> Event a -> Event a
mergeBy (\a
e1 a
_ -> a
e1)

-- | Right-biased event merge (always prefer right event, if present).
rMerge :: Event a -> Event a -> Event a
rMerge :: forall a. Event a -> Event a -> Event a
rMerge = forall a b c. (a -> b -> c) -> b -> a -> c
flip forall a. Event a -> Event a -> Event a
lMerge

-- | Unbiased event merge: simultaneous occurrence is an error.
merge :: Event a -> Event a -> Event a
merge :: forall a. Event a -> Event a -> Event a
merge = forall a. (a -> a -> a) -> Event a -> Event a -> Event a
mergeBy forall a b. (a -> b) -> a -> b
$ forall a. HasCallStack => String -> a
error String
"Bearriver: merge: Simultaneous event occurrence."

-- Applicative-based definition:
-- mergeBy f le re = (f <$> le <*> re) <|> le <|> re
mergeBy :: (a -> a -> a) -> Event a -> Event a -> Event a
mergeBy :: forall a. (a -> a -> a) -> Event a -> Event a -> Event a
mergeBy a -> a -> a
_       Event a
NoEvent      Event a
NoEvent      = forall a. Event a
NoEvent
mergeBy a -> a -> a
_       le :: Event a
le@(Event a
_) Event a
NoEvent      = Event a
le
mergeBy a -> a -> a
_       Event a
NoEvent      re :: Event a
re@(Event a
_) = Event a
re
mergeBy a -> a -> a
resolve (Event a
l)    (Event a
r)    = forall a. a -> Event a
Event (a -> a -> a
resolve a
l a
r)

-- | A generic event merge-map utility that maps event occurrences,
-- merging the results. The first three arguments are mapping functions,
-- the third of which will only be used when both events are present.
-- Therefore, 'mergeBy' = 'mapMerge' 'id' 'id'
--
-- Applicative-based definition:
-- mapMerge lf rf lrf le re = (f <$> le <*> re) <|> (lf <$> le) <|> (rf <$> re)
mapMerge :: (a -> c) -> (b -> c) -> (a -> b -> c)
            -> Event a -> Event b -> Event c
mapMerge :: forall a c b.
(a -> c)
-> (b -> c) -> (a -> b -> c) -> Event a -> Event b -> Event c
mapMerge a -> c
_  b -> c
_  a -> b -> c
_   Event a
NoEvent   Event b
NoEvent   = forall a. Event a
NoEvent
mapMerge a -> c
lf b -> c
_  a -> b -> c
_   (Event a
l) Event b
NoEvent   = forall a. a -> Event a
Event (a -> c
lf a
l)
mapMerge a -> c
_  b -> c
rf a -> b -> c
_   Event a
NoEvent   (Event b
r) = forall a. a -> Event a
Event (b -> c
rf b
r)
mapMerge a -> c
_  b -> c
_  a -> b -> c
lrf (Event a
l) (Event b
r) = forall a. a -> Event a
Event (a -> b -> c
lrf a
l b
r)

-- | Merge a list of events; foremost event has priority.
--
-- Foldable-based definition:
-- mergeEvents :: Foldable t => t (Event a) -> Event a
-- mergeEvents =  asum
mergeEvents :: [Event a] -> Event a
mergeEvents :: forall a. [Event a] -> Event a
mergeEvents = forall (t :: * -> *) a b.
Foldable t =>
(a -> b -> b) -> b -> t a -> b
foldr forall a. Event a -> Event a -> Event a
lMerge forall a. Event a
NoEvent

-- | Collect simultaneous event occurrences; no event if none.
--
-- Traverable-based definition:
-- catEvents :: Foldable t => t (Event a) -> Event (t a)
-- carEvents e  = if (null e) then NoEvent else (sequenceA e)
catEvents :: [Event a] -> Event [a]
catEvents :: forall a. [Event a] -> Event [a]
catEvents [Event a]
eas = case [ a
a | Event a
a <- [Event a]
eas ] of
                    [] -> forall a. Event a
NoEvent
                    [a]
as -> forall a. a -> Event a
Event [a]
as

-- | Join (conjunction) of two events. Only produces an event
-- if both events exist.
--
-- Applicative-based definition:
-- joinE = liftA2 (,)
joinE :: Event a -> Event b -> Event (a,b)
joinE :: forall a b. Event a -> Event b -> Event (a, b)
joinE Event a
NoEvent   Event b
_         = forall a. Event a
NoEvent
joinE Event a
_         Event b
NoEvent   = forall a. Event a
NoEvent
joinE (Event a
l) (Event b
r) = forall a. a -> Event a
Event (a
l,b
r)

-- | Split event carrying pairs into two events.
splitE :: Event (a,b) -> (Event a, Event b)
splitE :: forall a b. Event (a, b) -> (Event a, Event b)
splitE Event (a, b)
NoEvent       = (forall a. Event a
NoEvent, forall a. Event a
NoEvent)
splitE (Event (a
a,b
b)) = (forall a. a -> Event a
Event a
a, forall a. a -> Event a
Event b
b)

------------------------------------------------------------------------------
-- Event filtering
------------------------------------------------------------------------------

-- | Filter out events that don't satisfy some predicate.
filterE :: (a -> Bool) -> Event a -> Event a
filterE :: forall a. (a -> Bool) -> Event a -> Event a
filterE a -> Bool
p e :: Event a
e@(Event a
a) = if a -> Bool
p a
a then Event a
e else forall a. Event a
NoEvent
filterE a -> Bool
_ Event a
NoEvent     = forall a. Event a
NoEvent


-- | Combined event mapping and filtering. Note: since 'Event' is a 'Functor',
-- see 'fmap' for a simpler version of this function with no filtering.
mapFilterE :: (a -> Maybe b) -> Event a -> Event b
mapFilterE :: forall a b. (a -> Maybe b) -> Event a -> Event b
mapFilterE a -> Maybe b
_ Event a
NoEvent   = forall a. Event a
NoEvent
mapFilterE a -> Maybe b
f (Event a
a) = case a -> Maybe b
f a
a of
                            Maybe b
Nothing -> forall a. Event a
NoEvent
                            Just b
b  -> forall a. a -> Event a
Event b
b


-- | Enable/disable event occurences based on an external condition.
gate :: Event a -> Bool -> Event a
Event a
_ gate :: forall a. Event a -> Bool -> Event a
`gate` Bool
False = forall a. Event a
NoEvent
Event a
e `gate` Bool
True  = Event a
e

-- * Switching

-- ** Basic switchers

-- | Basic switch.
--
-- By default, the first signal function is applied. Whenever the second value
-- in the pair actually is an event, the value carried by the event is used to
-- obtain a new signal function to be applied *at that time and at future
-- times*. Until that happens, the first value in the pair is produced in the
-- output signal.
--
-- Important note: at the time of switching, the second signal function is
-- applied immediately. If that second SF can also switch at time zero, then a
-- double (nested) switch might take place. If the second SF refers to the
-- first one, the switch might take place infinitely many times and never be
-- resolved.
--
-- Remember: The continuation is evaluated strictly at the time
-- of switching!
switch :: Monad m => SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
switch :: forall (m :: * -> *) a b c.
Monad m =>
SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
switch SF m a (b, Event c)
sf c -> SF m a b
sfC = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \a
a -> do
  ((b, Event c)
o, SF m a (b, Event c)
ct) <- forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF SF m a (b, Event c)
sf a
a
  case (b, Event c)
o of
    (b
_, Event c
c) -> forall r (m :: * -> *) a.
(r -> r) -> ReaderT r m a -> ReaderT r m a
local (forall a b. a -> b -> a
const Time
0) (forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF (c -> SF m a b
sfC c
c) a
a)
    (b
b, Event c
NoEvent) -> forall (m :: * -> *) a. Monad m => a -> m a
return (b
b, forall (m :: * -> *) a b c.
Monad m =>
SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
switch SF m a (b, Event c)
ct c -> SF m a b
sfC)

-- | Switch with delayed observation.
--
-- By default, the first signal function is applied.
--
-- Whenever the second value in the pair actually is an event,
-- the value carried by the event is used to obtain a new signal
-- function to be applied *at future times*.
--
-- Until that happens, the first value in the pair is produced
-- in the output signal.
--
-- Important note: at the time of switching, the second
-- signal function is used immediately, but the current
-- input is fed by it (even though the actual output signal
-- value at time 0 is discarded).
--
-- If that second SF can also switch at time zero, then a
-- double (nested) -- switch might take place. If the second SF refers to the
-- first one, the switch might take place infinitely many times and never be
-- resolved.
--
-- Remember: The continuation is evaluated strictly at the time
-- of switching!
dSwitch ::  Monad m => SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
dSwitch :: forall (m :: * -> *) a b c.
Monad m =>
SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
dSwitch SF m a (b, Event c)
sf c -> SF m a b
sfC = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \a
a -> do
  ((b, Event c)
o, SF m a (b, Event c)
ct) <- forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF SF m a (b, Event c)
sf a
a
  case (b, Event c)
o of
    (b
b, Event c
c) -> do (b
_,SF m a b
ct') <- forall r (m :: * -> *) a.
(r -> r) -> ReaderT r m a -> ReaderT r m a
local (forall a b. a -> b -> a
const Time
0) (forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF (c -> SF m a b
sfC c
c) a
a)
                       forall (m :: * -> *) a. Monad m => a -> m a
return (b
b, SF m a b
ct')
    (b
b, Event c
NoEvent) -> forall (m :: * -> *) a. Monad m => a -> m a
return (b
b, forall (m :: * -> *) a b c.
Monad m =>
SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
dSwitch SF m a (b, Event c)
ct c -> SF m a b
sfC)


-- * Parallel composition and switching

-- ** Parallel composition and switching over collections with broadcasting

#if MIN_VERSION_base(4,8,0)
parB :: (Monad m) => [SF m a b] -> SF m a [b]
#else
parB :: (Functor m, Monad m) => [SF m a b] -> SF m a [b]
#endif
-- ^ Spatial parallel composition of a signal function collection.
-- Given a collection of signal functions, it returns a signal
-- function that broadcasts its input signal to every element
-- of the collection, to return a signal carrying a collection
-- of outputs. See 'par'.
--
-- For more information on how parallel composition works, check
-- <https://www.antonycourtney.com/pubs/hw03.pdf>
parB :: forall (m :: * -> *) a b. Monad m => [SF m a b] -> SF m a [b]
parB = forall (m :: * -> *) a b.
(Functor m, Monad m) =>
MSF (ListT m) a b -> MSF m a [b]
widthFirst forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: * -> *) a b.
Monad m =>
[MSF m a b] -> MSF (ListT m) a b
sequenceS

-- | Decoupled parallel switch with broadcasting (dynamic collection of
-- signal functions spatially composed in parallel). See 'dpSwitch'.
--
-- For more information on how parallel composition works, check
-- <https://www.antonycourtney.com/pubs/hw03.pdf>
dpSwitchB :: (Functor m, Monad m , Traversable col)
          => col (SF m a b) -> SF m (a, col b) (Event c) -> (col (SF m a b) -> c -> SF m a (col b))
          -> SF m a (col b)
dpSwitchB :: forall (m :: * -> *) (col :: * -> *) a b c.
(Functor m, Monad m, Traversable col) =>
col (SF m a b)
-> SF m (a, col b) (Event c)
-> (col (SF m a b) -> c -> SF m a (col b))
-> SF m a (col b)
dpSwitchB col (SF m a b)
sfs SF m (a, col b) (Event c)
sfF col (SF m a b) -> c -> SF m a (col b)
sfCs = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \a
a -> do
  col (b, SF m a b)
res <- forall (t :: * -> *) (m :: * -> *) a b.
(Traversable t, Monad m) =>
(a -> m b) -> t a -> m (t b)
T.mapM (forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
`unMSF` a
a) col (SF m a b)
sfs
  let bs :: col b
bs   = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a b. (a, b) -> a
fst col (b, SF m a b)
res
      sfs' :: col (SF m a b)
sfs' = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a b. (a, b) -> b
snd col (b, SF m a b)
res
  (Event c
e,SF m (a, col b) (Event c)
sfF') <- forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF SF m (a, col b) (Event c)
sfF (a
a, col b
bs)
  SF m a (col b)
ct <- case Event c
e of
          Event c
c -> forall a b. (a, b) -> b
snd forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF (col (SF m a b) -> c -> SF m a (col b)
sfCs col (SF m a b)
sfs c
c) a
a
          Event c
NoEvent -> forall (m :: * -> *) a. Monad m => a -> m a
return (forall (m :: * -> *) (col :: * -> *) a b c.
(Functor m, Monad m, Traversable col) =>
col (SF m a b)
-> SF m (a, col b) (Event c)
-> (col (SF m a b) -> c -> SF m a (col b))
-> SF m a (col b)
dpSwitchB col (SF m a b)
sfs' SF m (a, col b) (Event c)
sfF' col (SF m a b) -> c -> SF m a (col b)
sfCs)
  forall (m :: * -> *) a. Monad m => a -> m a
return (col b
bs, SF m a (col b)
ct)

-- ** Parallel composition over collections

-- | Apply an SF to every element of a list.
--
--   Example:
--
--   >>> embed (parC integral) (deltaEncode 0.1 [[1, 2], [2, 4], [3, 6], [4.0, 8.0 :: Float]])
--   [[0.0,0.0],[0.1,0.2],[0.3,0.6],[0.6,1.2]]
--
--   The number of SFs or expected inputs is determined by the first input
--   list, and not expected to vary over time.
--
--   If more inputs come in a subsequent list, they are ignored.
--
--   >>> embed (parC (arr (+1))) (deltaEncode 0.1 [[0], [1, 1], [3, 4], [6, 7, 8], [1, 1], [0, 0], [1, 9, 8]])
--   [[1],[2],[4],[7],[2],[1],[2]]
--
--   If less inputs come in a subsequent list, an exception is thrown.
--
--   >>> embed (parC (arr (+1))) (deltaEncode 0.1 [[0, 0], [1, 1], [3, 4], [6, 7, 8], [1, 1], [0, 0], [1, 9, 8]])
--   [[1,1],[2,2],[4,5],[7,8],[2,2],[1,1],[2,10]]
parC :: Monad m => SF m a b -> SF m [a] [b]
parC :: forall (m :: * -> *) a b. Monad m => SF m a b -> SF m [a] [b]
parC SF m a b
sf = forall (m :: * -> *) a b. Monad m => SF m a b -> SF m [a] [b]
parC0 SF m a b
sf
  where
    parC0 :: Monad m => SF m a b -> SF m [a] [b]
    parC0 :: forall (m :: * -> *) a b. Monad m => SF m a b -> SF m [a] [b]
parC0 SF m a b
sf0 = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \[a]
as -> do
      [(b, SF m a b)]
os <- forall (t :: * -> *) (m :: * -> *) a b.
(Traversable t, Monad m) =>
(a -> m b) -> t a -> m (t b)
T.mapM (\(a
a,SF m a b
sf) -> forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF SF m a b
sf a
a) forall a b. (a -> b) -> a -> b
$ forall a b. [a] -> [b] -> [(a, b)]
zip [a]
as (forall a. Int -> a -> [a]
replicate (forall (t :: * -> *) a. Foldable t => t a -> Int
length [a]
as) SF m a b
sf0)
      let bs :: [b]
bs  = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a b. (a, b) -> a
fst [(b, SF m a b)]
os
          cts :: [SF m a b]
cts = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a b. (a, b) -> b
snd [(b, SF m a b)]
os
      forall (m :: * -> *) a. Monad m => a -> m a
return ([b]
bs, forall (m :: * -> *) a b. Monad m => [SF m a b] -> SF m [a] [b]
parC' [SF m a b]
cts)

    parC' :: Monad m => [SF m a b] -> SF m [a] [b]
    parC' :: forall (m :: * -> *) a b. Monad m => [SF m a b] -> SF m [a] [b]
parC' [SF m a b]
sfs = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \[a]
as -> do
      [(b, SF m a b)]
os <- forall (t :: * -> *) (m :: * -> *) a b.
(Traversable t, Monad m) =>
(a -> m b) -> t a -> m (t b)
T.mapM (\(a
a,SF m a b
sf) -> forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF SF m a b
sf a
a) forall a b. (a -> b) -> a -> b
$ forall a b. [a] -> [b] -> [(a, b)]
zip [a]
as [SF m a b]
sfs
      let bs :: [b]
bs  = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a b. (a, b) -> a
fst [(b, SF m a b)]
os
          cts :: [SF m a b]
cts = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a b. (a, b) -> b
snd [(b, SF m a b)]
os
      forall (m :: * -> *) a. Monad m => a -> m a
return ([b]
bs, forall (m :: * -> *) a b. Monad m => [SF m a b] -> SF m [a] [b]
parC' [SF m a b]
cts)

-- * Discrete to continuous-time signal functions

-- ** Wave-form generation

-- | Zero-order hold.
--
-- Converts a discrete-time signal into a continuous-time signal, by holding
-- the last value until it changes in the input signal. The given parameter
-- may be used for time zero, and until the first event occurs in the input
-- signal, so hold is always well-initialized.
--
-- >>> embed (hold 1) (deltaEncode 0.1 [NoEvent, NoEvent, Event 2, NoEvent, Event 3, NoEvent])
-- [1,1,2,2,3,3]
hold :: Monad m => a -> SF m (Event a) a
hold :: forall (m :: * -> *) a. Monad m => a -> SF m (Event a) a
hold a
a = forall (m :: * -> *) c a b.
Monad m =>
c -> MSF m (a, c) (b, c) -> MSF m a b
feedback a
a forall a b. (a -> b) -> a -> b
$ forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall a b. (a -> b) -> a -> b
$ \(Event a
e,a
a') ->
    forall {b}. b -> (b, b)
dup (forall a b. a -> (b -> a) -> Event b -> a
event a
a' forall a. a -> a
id Event a
e)

-- ** Accumulators

-- | Accumulator parameterized by the accumulation function.
accumBy :: Monad m => (b -> a -> b) -> b -> SF m (Event a) (Event b)
accumBy :: forall (m :: * -> *) b a.
Monad m =>
(b -> a -> b) -> b -> SF m (Event a) (Event b)
accumBy b -> a -> b
f b
b = forall (m :: * -> *) a b.
Monad m =>
MSF m a b -> MSF m (Event a) (Event b)
mapEventS forall a b. (a -> b) -> a -> b
$ forall (m :: * -> *) a s.
Monad m =>
(a -> s -> s) -> s -> MSF m a s
accumulateWith (forall a b c. (a -> b -> c) -> b -> a -> c
flip b -> a -> b
f) b
b

-- | Zero-order hold accumulator parameterized by the accumulation function.
accumHoldBy :: Monad m => (b -> a -> b) -> b -> SF m (Event a) b
accumHoldBy :: forall (m :: * -> *) b a.
Monad m =>
(b -> a -> b) -> b -> SF m (Event a) b
accumHoldBy b -> a -> b
f b
b = forall (m :: * -> *) c a b.
Monad m =>
c -> MSF m (a, c) (b, c) -> MSF m a b
feedback b
b forall a b. (a -> b) -> a -> b
$ forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall a b. (a -> b) -> a -> b
$ \(Event a
a, b
b') ->
  let b'' :: b
b'' = forall a b. a -> (b -> a) -> Event b -> a
event b
b' (b -> a -> b
f b
b') Event a
a
  in (b
b'', b
b'')

-- * State keeping combinators

-- ** Loops with guaranteed well-defined feedback

-- | Loop with an initial value for the signal being fed back.
loopPre :: Monad m => c -> SF m (a, c) (b, c) -> SF m a b
loopPre :: forall (m :: * -> *) c a b.
Monad m =>
c -> SF m (a, c) (b, c) -> SF m a b
loopPre = forall (m :: * -> *) c a b.
Monad m =>
c -> MSF m (a, c) (b, c) -> MSF m a b
feedback

-- * Integration and differentiation

-- | Integration using the rectangle rule.
integral :: (Monad m, Fractional s, VectorSpace a s) => SF m a a
integral :: forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
SF m a a
integral = forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
a -> SF m a a
integralFrom forall v a. VectorSpace v a => v
zeroVector


-- | Integrate using an auxiliary function that takes the current and the last
-- input, the time between those samples, and the last output, and returns a
-- new output.
integralFrom :: (Monad m, Fractional s, VectorSpace a s) => a -> SF m a a
integralFrom :: forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
a -> SF m a a
integralFrom a
a0 = proc a
a -> do
  Time
dt <- forall (m :: * -> *) b a. Monad m => m b -> MSF m a b
constM forall (m :: * -> *) r. Monad m => ReaderT r m r
ask         -< ()
  forall (m :: * -> *) a s.
Monad m =>
(a -> s -> s) -> s -> MSF m a s
accumulateWith forall v a. VectorSpace v a => v -> v -> v
(^+^) a
a0 -< forall a b. (Real a, Fractional b) => a -> b
realToFrac Time
dt forall v a. VectorSpace v a => a -> v -> v
*^ a
a

-- | A very crude version of a derivative. It simply divides the
-- value difference by the time difference. Use at your own risk.
derivative :: (Monad m, Fractional s, VectorSpace a s) => SF m a a
derivative :: forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
SF m a a
derivative = forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
a -> SF m a a
derivativeFrom forall v a. VectorSpace v a => v
zeroVector

derivativeFrom :: (Monad m, Fractional s, VectorSpace a s) => a -> SF m a a
derivativeFrom :: forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
a -> SF m a a
derivativeFrom a
a0 = proc a
a -> do
  Time
dt   <- forall (m :: * -> *) b a. Monad m => m b -> MSF m a b
constM forall (m :: * -> *) r. Monad m => ReaderT r m r
ask   -< ()
  a
aOld <- forall (m :: * -> *) a. Monad m => a -> MSF m a a
MSF.iPre a
a0 -< a
a
  forall (a :: * -> * -> *) b. Arrow a => a b b
returnA             -< (a
a forall v a. VectorSpace v a => v -> v -> v
^-^ a
aOld) forall v a. VectorSpace v a => v -> a -> v
^/ forall a b. (Real a, Fractional b) => a -> b
realToFrac Time
dt

-- NOTE: BUG in this function, it needs two a's but we
-- can only provide one
iterFrom :: Monad m => (a -> a -> DTime -> b -> b) -> b -> SF m a b
iterFrom :: forall (m :: * -> *) a b.
Monad m =>
(a -> a -> Time -> b -> b) -> b -> SF m a b
iterFrom a -> a -> Time -> b -> b
f b
b = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \a
a -> do
  Time
dt <- forall (m :: * -> *) r. Monad m => ReaderT r m r
ask
  let b' :: b
b' = a -> a -> Time -> b -> b
f a
a a
a Time
dt b
b
  forall (m :: * -> *) a. Monad m => a -> m a
return (b
b, forall (m :: * -> *) a b.
Monad m =>
(a -> a -> Time -> b -> b) -> b -> SF m a b
iterFrom a -> a -> Time -> b -> b
f b
b')

-- * Noise (random signal) sources and stochastic event sources

-- | Stochastic event source with events occurring on average once every t_avg
-- seconds. However, no more than one event results from any one sampling
-- interval in the case of relatively sparse sampling, thus avoiding an
-- "event backlog" should sampling become more frequent at some later
-- point in time.
occasionally :: MonadRandom m
             => Time -- ^ The time /q/ after which the event should be produced on average
             -> b    -- ^ Value to produce at time of event
             -> SF m a (Event b)
occasionally :: forall (m :: * -> *) b a.
MonadRandom m =>
Time -> b -> SF m a (Event b)
occasionally Time
tAvg b
b
  | Time
tAvg forall a. Ord a => a -> a -> Bool
<= Time
0 = forall a. HasCallStack => String -> a
error String
"bearriver: Non-positive average interval in occasionally."
  | Bool
otherwise = proc a
_ -> do
      Time
r   <- forall (m :: * -> *) b a.
(MonadRandom m, Random b) =>
(b, b) -> MSF m a b
getRandomRS (Time
0, Time
1) -< ()
      Time
dt  <- forall (m :: * -> *) a. Monad m => SF m a Time
timeDelta          -< ()
      let p :: Time
p = Time
1 forall a. Num a => a -> a -> a
- forall a. Floating a => a -> a
exp (-(Time
dt forall a. Fractional a => a -> a -> a
/ Time
tAvg))
      forall (a :: * -> * -> *) b. Arrow a => a b b
returnA -< if Time
r forall a. Ord a => a -> a -> Bool
< Time
p then forall a. a -> Event a
Event b
b else forall a. Event a
NoEvent
 where
  timeDelta :: Monad m => SF m a DTime
  timeDelta :: forall (m :: * -> *) a. Monad m => SF m a Time
timeDelta = forall (m :: * -> *) b a. Monad m => m b -> MSF m a b
constM forall (m :: * -> *) r. Monad m => ReaderT r m r
ask

-- * Execution/simulation

-- ** Reactimation

-- | Convenience function to run a signal function indefinitely, using a IO
-- actions to obtain new input and process the output.
--
-- This function first runs the initialization action, which provides the
-- initial input for the signal transformer at time 0.
--
-- Afterwards, an input sensing action is used to obtain new input (if any) and
-- the time since the last iteration. The argument to the input sensing
-- function indicates if it can block. If no new input is received, it is
-- assumed to be the same as in the last iteration.
--
-- After applying the signal function to the input, the actuation IO action is
-- executed. The first argument indicates if the output has changed, the second
-- gives the actual output). Actuation functions may choose to ignore the first
-- argument altogether. This action should return True if the reactimation must
-- stop, and False if it should continue.
--
-- Note that this becomes the program's /main loop/, which makes using this
-- function incompatible with GLUT, Gtk and other graphics libraries. It may
-- also impose a sizeable constraint in larger projects in which different
-- subparts run at different time steps. If you need to control the main loop
-- yourself for these or other reasons, use 'reactInit' and 'react'.
reactimate :: Monad m => m a -> (Bool -> m (DTime, Maybe a)) -> (Bool -> b -> m Bool) -> SF Identity a b -> m ()
reactimate :: forall (m :: * -> *) a b.
Monad m =>
m a
-> (Bool -> m (Time, Maybe a))
-> (Bool -> b -> m Bool)
-> SF Identity a b
-> m ()
reactimate m a
senseI Bool -> m (Time, Maybe a)
sense Bool -> b -> m Bool
actuate SF Identity a b
sf = do
  -- runMaybeT $ MSF.reactimate $ liftMSFTrans (senseSF >>> sfIO) >>> actuateSF
  forall (m :: * -> *). Monad m => MSF m () Bool -> m ()
MSF.reactimateB forall a b. (a -> b) -> a -> b
$ forall {a}. MSF m a (Time, a)
senseSF forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> MSF m (Time, a) b
sfIO forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> MSF m b Bool
actuateSF
  forall (m :: * -> *) a. Monad m => a -> m a
return ()
 where sfIO :: MSF m (Time, a) b
sfIO        = forall (m2 :: * -> *) (m1 :: * -> *) a b.
(Monad m2, Monad m1) =>
(forall c. m1 c -> m2 c) -> MSF m1 a b -> MSF m2 a b
morphS (forall (m :: * -> *) a. Monad m => a -> m a
returnforall b c a. (b -> c) -> (a -> b) -> a -> c
.forall a. Identity a -> a
runIdentity) (forall (m :: * -> *) r a b.
Monad m =>
MSF (ReaderT r m) a b -> MSF m (r, a) b
runReaderS SF Identity a b
sf)

       -- Sense
       senseSF :: MSF m a (Time, a)
senseSF     = forall (m :: * -> *) a b c.
Monad m =>
MSF m a (b, Maybe c) -> (c -> MSF m a b) -> MSF m a b
MSF.dSwitch forall {a}. MSF m a ((Time, a), Maybe a)
senseFirst forall {a}. a -> MSF m a (Time, a)
senseRest

       -- Sense: First sample
       senseFirst :: MSF m a ((Time, a), Maybe a)
senseFirst = forall (m :: * -> *) b a. Monad m => m b -> MSF m a b
constM m a
senseI forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr (\a
x -> ((Time
0, a
x), forall a. a -> Maybe a
Just a
x))

       -- Sense: Remaining samples
       senseRest :: a -> MSF m a (Time, a)
senseRest a
a = forall (m :: * -> *) b a. Monad m => m b -> MSF m a b
constM (Bool -> m (Time, Maybe a)
sense Bool
True) forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> (forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall a. a -> a
id forall (a :: * -> * -> *) b c b' c'.
Arrow a =>
a b c -> a b' c' -> a (b, b') (c, c')
*** forall (m :: * -> *) a. Monad m => a -> MSF m (Maybe a) a
keepLast a
a)

       keepLast :: Monad m => a -> MSF m (Maybe a) a
       keepLast :: forall (m :: * -> *) a. Monad m => a -> MSF m (Maybe a) a
keepLast a
a = forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF forall a b. (a -> b) -> a -> b
$ \Maybe a
ma -> let a' :: a
a' = forall a. a -> Maybe a -> a
fromMaybe a
a Maybe a
ma in a
a' seq :: forall a b. a -> b -> b
`seq` forall (m :: * -> *) a. Monad m => a -> m a
return (a
a', forall (m :: * -> *) a. Monad m => a -> MSF m (Maybe a) a
keepLast a
a')

       -- Consume/render
       -- actuateSF :: MSF IO b ()
       -- actuateSF    = arr (\x -> (True, x)) >>> liftMSF (lift . uncurry actuate) >>> exitIf
       actuateSF :: MSF m b Bool
actuateSF    = forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr (\b
x -> (Bool
True, b
x)) forall {k} (cat :: k -> k -> *) (a :: k) (b :: k) (c :: k).
Category cat =>
cat a b -> cat b c -> cat a c
>>> forall (m :: * -> *) a b. Monad m => (a -> m b) -> MSF m a b
arrM (forall a b c. (a -> b -> c) -> (a, b) -> c
uncurry Bool -> b -> m Bool
actuate)

-- * Debugging / Step by step simulation

-- | Evaluate an SF, and return an output and an initialized SF.
--
--   /WARN/: Do not use this function for standard simulation. This function is
--   intended only for debugging/testing. Apart from being potentially slower
--   and consuming more memory, it also breaks the FRP abstraction by making
--   samples discrete and step based.
evalAtZero :: SF Identity a b -> a -> (b, SF Identity a b)
evalAtZero :: forall a b. SF Identity a b -> a -> (b, SF Identity a b)
evalAtZero SF Identity a b
sf a
a = forall a. Identity a -> a
runIdentity forall a b. (a -> b) -> a -> b
$ forall r (m :: * -> *) a. ReaderT r m a -> r -> m a
runReaderT (forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF SF Identity a b
sf a
a) Time
0

-- | Evaluate an initialized SF, and return an output and a continuation.
--
--   /WARN/: Do not use this function for standard simulation. This function is
--   intended only for debugging/testing. Apart from being potentially slower
--   and consuming more memory, it also breaks the FRP abstraction by making
--   samples discrete and step based.
evalAt :: SF Identity a b -> DTime -> a -> (b, SF Identity a b)
evalAt :: forall a b. SF Identity a b -> Time -> a -> (b, SF Identity a b)
evalAt SF Identity a b
sf Time
dt a
a = forall a. Identity a -> a
runIdentity forall a b. (a -> b) -> a -> b
$ forall r (m :: * -> *) a. ReaderT r m a -> r -> m a
runReaderT (forall (m :: * -> *) a b. MSF m a b -> a -> m (b, MSF m a b)
unMSF SF Identity a b
sf a
a) Time
dt

-- | Given a signal function and time delta, it moves the signal function into
--   the future, returning a new uninitialized SF and the initial output.
--
--   While the input sample refers to the present, the time delta refers to the
--   future (or to the time between the current sample and the next sample).
--
--   /WARN/: Do not use this function for standard simulation. This function is
--   intended only for debugging/testing. Apart from being potentially slower
--   and consuming more memory, it also breaks the FRP abstraction by making
--   samples discrete and step based.
--
evalFuture :: SF Identity a b -> a -> DTime -> (b, SF Identity a b)
evalFuture :: forall a b. SF Identity a b -> a -> Time -> (b, SF Identity a b)
evalFuture SF Identity a b
sf = forall a b c. (a -> b -> c) -> b -> a -> c
flip (forall a b. SF Identity a b -> Time -> a -> (b, SF Identity a b)
evalAt SF Identity a b
sf)

-- * Auxiliary functions

-- ** Event handling
replaceOnce :: Monad m => a -> SF m a a
replaceOnce :: forall (m :: * -> *) a. Monad m => a -> SF m a a
replaceOnce a
a = forall (m :: * -> *) a b c.
Monad m =>
SF m a (b, Event c) -> (c -> SF m a b) -> SF m a b
dSwitch (forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall a b. (a -> b) -> a -> b
$ forall a b. a -> b -> a
const (a
a, forall a. a -> Event a
Event ())) (forall a b. a -> b -> a
const forall a b. (a -> b) -> a -> b
$ forall (a :: * -> * -> *) b c. Arrow a => (b -> c) -> a b c
arr forall a. a -> a
id)

-- ** Tuples
dup :: b -> (b, b)
dup  b
x     = (b
x,b
x)