@@ -0,0 +1,171 @@
1+# Reflex Quick(ish) Reference
2+
3+## Typeclasses
4+
5+Many Reflex functions operate in monadic context `m a`, where the monad 'm' supports various additional typeclasses such as MonadWidget, MonadHold, or MonadSample in addition to Monad itself. The actual 'm' in use will be determined by the top-level entry point of the FRP host (such as Reflex-Dom -- see the bottom of the Reflex-Dom quick reference for details).
6+
7+The 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.
8+
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:
10+
11+```haskell
12+[ ] -- Pure function
13+[S] -- Function runs in any monad supporting MonadSample
14+[H] -- Function runs in any monad supporting MonadHold
15+```
16+
17+Since MonadHold depends on MonadSample, any [S] function also runs in [H] context.
18+
19+## Functions producing Event
20+
21+```haskell
22+-- Trivial Event
23+[ ] never :: Event a
24+
25+-- Extract Event from Dynamic
26+[ ] updated :: Dynamic a -> Event a
27+
28+-- Transform Event to Event using function
29+[ ] fmap :: (a -> b) -> Event a -> Event b
30+[ ] fmapMaybe :: (a -> Maybe b) -> Event a -> Event b
31+[ ] ffilter :: (a -> Bool) -> Event a -> Event a
32+[ ] ffor :: Event a -> (a -> b) -> Event b
33+[ ] fforMaybe :: Event a -> (a -> Maybe b) -> Event b
34+
35+-- Event to identical Event with debug trace. (Only prints if Event is ultimately used.)
36+[ ] traceEvent :: Show a => String -> Event a -> Event a
37+[ ] traceEventWith :: (a -> String) -> Event a -> Event a
38+
39+-- Transform Event to Event by sampling Behavior or Dynamic
40+[ ] gate :: Behavior Bool -> Event a -> Event a
41+[ ] tag :: Behavior a -> Event b -> Event a
42+[ ] tagDyn :: Dynamic a -> Event b -> Event a
43+[ ] attach :: Behavior a -> Event b -> Event (a, b)
44+[ ] attachDyn :: Dynamic a -> Event b -> Event (a, b)
45+[ ] attachWith :: (a -> b -> c) -> Behavior a -> Event b -> Event c
46+[ ] attachDynWith :: (a -> b -> c) -> Dynamic a -> Event b -> Event c
47+[ ] attachWithMaybe :: (a -> b -> Maybe c) -> Behavior a -> Event b -> Event c
48+[ ] attachDynWithMaybe :: (a -> b -> Maybe c) -> Dynamic a -> Event b -> Event c
49+
50+-- Combine multiple Events
51+[ ] <> :: Monoid a => Event a -> Event a -> Event a
52+[ ] mergeWith :: (a -> a -> a) -> [Event a] -> Event a
53+[ ] leftmost :: [Event a] -> Event a
54+[ ] mergeList :: [Event a] -> Event (NonEmpty a)
55+[ ] merge :: GCompare k => DMap (WrapArg Event k) -> Event (DMap k)
56+[ ] mergeMap :: Ord k => Map k (Event a) -> Event (Map k a)
57+
58+-- Efficient one-to-many fanout
59+[ ] fanMap :: Ord k => Event (Map k a) -> EventSelector (Const2 k a)
60+[ ] fan :: GCompare k => Event (DMap k) -> EventSelector k
61+[ ] select :: EventSelector k -> k a -> Event a
62+
63+-- Event to Event via function that can sample current values
64+[ ] push :: (a -> m (Maybe b)) -> Event a -> Event b
65+[ ] pushAlways :: (a -> m b ) -> Event a -> Event b
66+ -- Note supplied function operates in [H] context
67+
68+-- Split Event into next occurrence and all other future occurrences, as of now.
69+[H] headE :: Event a -> m (Event a)
70+[H] tailE :: Event a -> m (Event a)
71+[H] headTailE :: Event a -> m (Event a, Event a)
72+```
73+
74+## Functions producing Behavior
75+
76+```haskell
77+-- Trivial Behavior
78+[ ] constant :: a -> Behavior a
79+
80+-- Extract Behavior from Dynamic
81+[ ] current :: Dynamic a -> Behavior a
82+
83+-- Create Behavior with given initial value, updated when the Event fires.
84+[H] hold :: a -> Event a -> m (Behavior a)
85+
86+-- Transform Behavior to Behavior using function
87+[ ] fmap :: (a -> b) -> Behavior a -> Behavior b
88+[ ] ffor :: Behavior a -> (a -> b) -> Behavior b
89+[ ] <*> :: Behavior (a -> b) -> Behavior a -> Behavior b
90+[ ] >>= :: Behavior a -> (a -> Behavior b) -> Behavior b
91+[ ] <> :: Monoid a => Behavior a -> Behavior a -> Behavior a
92+-- ... plus many more due to typeclass membership
93+
94+-- Behavior to Behavior by sampling current values
95+[S] sample :: Behavior a -> m a
96+[ ] pull :: m a -> Behavior a
97+ -- Note supplied value is in [S] context
98+```
99+
100+## Functions producing Dynamic
101+
102+```haskell
103+-- Trivial Dynamic
104+[ ] constDyn :: a -> Dynamic a
105+
106+-- Create Dynamic with given initial value, updated (various ways) when the Event fires.
107+[H] holdDyn :: a -> Event a -> m (Dynamic a)
108+[H] foldDyn :: (a -> b -> b ) -> b -> Event a -> m (Dynamic b)
109+[H] foldDynMaybe :: (a -> b -> Maybe b ) -> b -> Event a -> m (Dynamic b)
110+[H] foldDynM :: (a -> b -> m' b ) -> b -> Event a -> m (Dynamic b)
111+[H] foldDynMaybeM :: (a -> b -> m' (Maybe b)) -> b -> Event a -> m (Dynamic b)
112+ -- Note m' supplies [H] context
113+
114+-- Initial value is 0; counts Event firings from now.
115+[H] count :: Num b => Event a -> m (Dynamic b)
116+-- Initial Bool value is supplied; toggles at each Event firing.
117+[H] toggle :: Bool -> Event a -> m (Dynamic Bool)
118+
119+-- Transform Dynamic to Dynamic using function
120+[H] forDyn :: Dynamic a -> (a -> b) -> m (Dynamic b)
121+[H] mapDyn :: (a -> b) -> Dynamic a -> m (Dynamic b)
122+[H] mapDynM :: (a -> m' b) -> Dynamic a -> m (Dynamic b)
123+ -- Note m' supplies [S] context
124+[H] splitDyn :: Dynamic (a, b) -> m (Dynamic a, Dynamic b)
125+
126+-- Combine multiple Dynamics
127+[H] mconcatDyn :: Monoid a => [Dynamic a] -> m (Dynamic a)
128+[H] distributeDMapOverDyn :: GCompare k => DMap (WrapArg Dynamic k) -> m (Dynamic (DMap k))
129+[H] combineDyn :: (a -> b -> c) -> Dynamic a -> Dynamic b -> m (Dynamic c)
130+
131+-- Efficient one-to-many fanout
132+[ ] demux :: Ord k => Dynamic k -> Demux k
133+[H] getDemuxed :: Eq k => Demux k -> k -> m (Dynamic Bool)
134+
135+-- Dynamic to Dynamic, removing updates w/o value change
136+[ ] nubDyn :: Eq a => Dynamic a -> Dynamic a
137+
138+-- Dynamic to identical Dynamic with debug trace. (Only prints if Dynamic is ultimately used.)
139+[ ] traceDyn :: Show a => String -> Dynamic a -> Dynamic a
140+[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
141+```
142+
143+## Flattening functions
144+
145+These functions flatten nested types such as Event-of-Event, Behavior-of-Event, Event-of-Behavior etc, removing the outer wrapper.
146+
147+For 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+
149+```haskell
150+-- Flatten Behavior-of-Event to Event. Old Event is used during switchover.
151+[ ] switch :: Behavior (Event a) -> Event a
152+
153+-- Flatten Dyanmic-of-Event to Event. New Event is used immediately.
154+[ ] switchPromptlyDyn :: Dynamic (Event a) -> Event a
155+
156+-- Flatten Event-of-Event to Event that fires when both wrapper AND new Event fire.
157+[ ] coincidence :: Event (Event a) -> Event a
158+
159+-- Flatten Dynamic-of-Dynamic to Dynamic. New Dynamic is used immediately.
160+-- Output updated whenever inner OR outer Dynamic updates.
161+[ ] joinDyn :: Dynamic (Dynamic a) -> Dynamic a
162+[ ] joinDynThroughMap :: Ord k => Dynamic (Map k (Dynamic a)) -> Dynamic (Map k a)
163+
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.
166+[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
167+
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)
171+```