@@ -6,9 +6,7 @@ Many Reflex functions operate in monadic context `m a`, where the monad 'm' supp
7The function signatures here have been simplified by removing many typeclass constraints and adding simple annotations to each function. Also the ubiquitous 't' type parameter has been removed.
7The function signatures here have been simplified by removing many typeclass constraints and adding simple annotations to each function. Also the ubiquitous 't' type parameter has been removed.
9−Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time".
9+Some of these functions are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time". Other functions must operate in some monadic context, because they produce a result "as of now" (e.g., any function that takes an "initial" value, or returns a "current" value). Annotations are used to distinguish these cases:
11−Other functions must operate in some monadic context, because they produce a result "as of now". The annotations are:
14[ ] -- Pure function
12[ ] -- Pure function
@@ -34,7 +32,7 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
34[ ] ffor :: Event a -> (a -> b) -> Event b
32[ ] ffor :: Event a -> (a -> b) -> Event b
35[ ] fforMaybe :: Event a -> (a -> Maybe b) -> Event b
33[ ] fforMaybe :: Event a -> (a -> Maybe b) -> Event b
37−-- Event to identical Event with debug trace.
35+-- Event to identical Event with debug trace. (Only prints if Event is ultimately used.)
38[ ] traceEvent :: Show a => String -> Event a -> Event a
36[ ] traceEvent :: Show a => String -> Event a -> Event a
39[ ] traceEventWith :: (a -> String) -> Event a -> Event a
37[ ] traceEventWith :: (a -> String) -> Event a -> Event a
@@ -62,12 +60,12 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
62[ ] fan :: GCompare k => Event (DMap k) -> EventSelector k
60[ ] fan :: GCompare k => Event (DMap k) -> EventSelector k
63[ ] select :: EventSelector k -> k a -> Event a
61[ ] select :: EventSelector k -> k a -> Event a
65−-- Event to Event via monadic function
63+-- Event to Event via function that can sample current values
66[ ] push :: (a -> m (Maybe b)) -> Event a -> Event b
64[ ] push :: (a -> m (Maybe b)) -> Event a -> Event b
67[ ] pushAlways :: (a -> m b ) -> Event a -> Event b
65[ ] pushAlways :: (a -> m b ) -> Event a -> Event b
68 -- Note supplied function operates in [H] context
66 -- Note supplied function operates in [H] context
70−-- Event to monadic Event
68+-- Split Event into next occurrence and all other future occurrences, as of now.
71[H] headE :: Event a -> m (Event a)
69[H] headE :: Event a -> m (Event a)
72[H] tailE :: Event a -> m (Event a)
70[H] tailE :: Event a -> m (Event a)
73[H] headTailE :: Event a -> m (Event a, Event a)
71[H] headTailE :: Event a -> m (Event a, Event a)
@@ -82,7 +80,7 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
82-- Extract Behavior from Dynamic
80-- Extract Behavior from Dynamic
83[ ] current :: Dynamic a -> Behavior a
81[ ] current :: Dynamic a -> Behavior a
85−-- Event to monadic Behavior
83+-- Create Behavior with given initial value, updated when the Event fires.
86[H] hold :: a -> Event a -> m (Behavior a)
84[H] hold :: a -> Event a -> m (Behavior a)
88-- Transform Behavior to Behavior using function
86-- Transform Behavior to Behavior using function
@@ -93,7 +91,7 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
93[ ] <> :: Monoid a => Behavior a -> Behavior a -> Behavior a
91[ ] <> :: Monoid a => Behavior a -> Behavior a -> Behavior a
94-- ... plus many more due to typeclass membership
92-- ... plus many more due to typeclass membership
96−-- Behavior to Behavior via monadic value
94+-- Behavior to Behavior by sampling current values
97[S] sample :: Behavior a -> m a
95[S] sample :: Behavior a -> m a
98[ ] pull :: m a -> Behavior a
96[ ] pull :: m a -> Behavior a
99 -- Note supplied value is in [S] context
97 -- Note supplied value is in [S] context
@@ -105,14 +103,17 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
105-- Trivial Dynamic
103-- Trivial Dynamic
106[ ] constDyn :: a -> Dynamic a
104[ ] constDyn :: a -> Dynamic a
108−-- Construct Dynamic from Event
106+-- Create Dynamic with given initial value, updated (various ways) when the Event fires.
109[H] holdDyn :: a -> Event a -> m (Dynamic a)
107[H] holdDyn :: a -> Event a -> m (Dynamic a)
110[H] foldDyn :: (a -> b -> b ) -> b -> Event a -> m (Dynamic b)
108[H] foldDyn :: (a -> b -> b ) -> b -> Event a -> m (Dynamic b)
111[H] foldDynMaybe :: (a -> b -> Maybe b ) -> b -> Event a -> m (Dynamic b)
109[H] foldDynMaybe :: (a -> b -> Maybe b ) -> b -> Event a -> m (Dynamic b)
112[H] foldDynM :: (a -> b -> m' b ) -> b -> Event a -> m (Dynamic b)
110[H] foldDynM :: (a -> b -> m' b ) -> b -> Event a -> m (Dynamic b)
113[H] foldDynMaybeM :: (a -> b -> m' (Maybe b)) -> b -> Event a -> m (Dynamic b)
111[H] foldDynMaybeM :: (a -> b -> m' (Maybe b)) -> b -> Event a -> m (Dynamic b)
114 -- Note m' supplies [H] context
112 -- Note m' supplies [H] context
114+-- Initial value is 0; counts Event firings from now.
115[H] count :: Num b => Event a -> m (Dynamic b)
115[H] count :: Num b => Event a -> m (Dynamic b)
116+-- Initial Bool value is supplied; toggles at each Event firing.
116[H] toggle :: Bool -> Event a -> m (Dynamic Bool)
117[H] toggle :: Bool -> Event a -> m (Dynamic Bool)
118-- Transform Dynamic to Dynamic using function
119-- Transform Dynamic to Dynamic using function
@@ -134,7 +135,7 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
134-- Dynamic to Dynamic, removing updates w/o value change
135-- Dynamic to Dynamic, removing updates w/o value change
135[ ] nubDyn :: Eq a => Dynamic a -> Dynamic a
136[ ] nubDyn :: Eq a => Dynamic a -> Dynamic a
137−-- Dynamic to identical Dynamic with debug trace.
138+-- Dynamic to identical Dynamic with debug trace. (Only prints if Dynamic is ultimately used.)
138[ ] traceDyn :: Show a => String -> Dynamic a -> Dynamic a
139[ ] traceDyn :: Show a => String -> Dynamic a -> Dynamic a
139[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
140[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
@@ -146,9 +147,6 @@ These functions flatten nested types such as Event-of-Event, Behavior-of-Event,
146For Events, the returned Event fires whenever the latest Event supplied by the wrapper fires. There are differences in how the functions handle *coincidences* -- situations where the old or new Event fires at the same instant that we switch from old to new. In some cases, the output Event tracks the old Event at the instant of switchover, while in other cases it tracks the new Event.
147For Events, the returned Event fires whenever the latest Event supplied by the wrapper fires. There are differences in how the functions handle *coincidences* -- situations where the old or new Event fires at the same instant that we switch from old to new. In some cases, the output Event tracks the old Event at the instant of switchover, while in other cases it tracks the new Event.
148```haskell
149```haskell
149−-- Flatten Event-of-Event to monadic Event. New Event is used immediately.
150−[H] switchPromptly :: Event a -> Event (Event a) -> m (Event a)
152-- Flatten Behavior-of-Event to Event. Old Event is used during switchover.
150-- Flatten Behavior-of-Event to Event. Old Event is used during switchover.
153[ ] switch :: Behavior (Event a) -> Event a
151[ ] switch :: Behavior (Event a) -> Event a
@@ -163,6 +161,11 @@ For Events, the returned Event fires whenever the latest Event supplied by the w
163[ ] joinDyn :: Dynamic (Dynamic a) -> Dynamic a
161[ ] joinDyn :: Dynamic (Dynamic a) -> Dynamic a
164[ ] joinDynThroughMap :: Ord k => Dynamic (Map k (Dynamic a)) -> Dynamic (Map k a)
162[ ] joinDynThroughMap :: Ord k => Dynamic (Map k (Dynamic a)) -> Dynamic (Map k a)
166−-- Flatten Event-of-Behavior to monadic Behavior
164+-- Analogous to 'hold': Create a Behavior that is initially identical to the
165+-- supplied Behavior. Updated to track a new Behavior whenever the Event fires.
167[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
166[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
168+-- Similar to above, for Events. Created Event initially tracks the first argument.
169+-- At switchover, the output Event immediately tracks the new Event.
170+[H] switchPromptly :: Event a -> Event (Event a) -> m (Event a)