git.iko.soy/patch
on 46ca8f6 help sign in
patch/Quickref.md
168 lines 7.8 kB history raw
1# Reflex Quick(ish) Reference
3## Typeclasses
5Many 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).
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.
9Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time".
11Other functions must operate in some monadic context, because they produce a result "as of now". The annotations are:
13```haskell
14[ ] -- Pure function
15[S] -- Function runs in any monad supporting MonadSample
16[H] -- Function runs in any monad supporting MonadHold
17```
19Since MonadHold depends on MonadSample, any [S] function also runs in [H] context.
21## Functions producing Event
23```haskell
24-- Trivial Event
25[ ] never :: Event a
27-- Extract Event from Dynamic
28[ ] updated :: Dynamic a -> Event a
30-- Transform Event to Event using function
31[ ] fmap :: (a -> b) -> Event a -> Event b
32[ ] fmapMaybe :: (a -> Maybe b) -> Event a -> Event b
33[ ] ffilter :: (a -> Bool) -> Event a -> Event a
34[ ] ffor :: Event a -> (a -> b) -> Event b
35[ ] fforMaybe :: Event a -> (a -> Maybe b) -> Event b
37-- Event to identical Event with debug trace.
38[ ] traceEvent :: Show a => String -> Event a -> Event a
39[ ] traceEventWith :: (a -> String) -> Event a -> Event a
41-- Transform Event to Event by sampling Behavior or Dynamic
42[ ] gate :: Behavior Bool -> Event a -> Event a
43[ ] tag :: Behavior a -> Event b -> Event a
44[ ] tagDyn :: Dynamic a -> Event b -> Event a
45[ ] attach :: Behavior a -> Event b -> Event (a, b)
46[ ] attachDyn :: Dynamic a -> Event b -> Event (a, b)
47[ ] attachWith :: (a -> b -> c) -> Behavior a -> Event b -> Event c
48[ ] attachDynWith :: (a -> b -> c) -> Dynamic a -> Event b -> Event c
49[ ] attachWithMaybe :: (a -> b -> Maybe c) -> Behavior a -> Event b -> Event c
50[ ] attachDynWithMaybe :: (a -> b -> Maybe c) -> Dynamic a -> Event b -> Event c
52-- Combine multiple Events
53[ ] <> :: Monoid a => Event a -> Event a -> Event a
54[ ] mergeWith :: (a -> a -> a) -> [Event a] -> Event a
55[ ] leftmost :: [Event a] -> Event a
56[ ] mergeList :: [Event a] -> Event (NonEmpty a)
57[ ] merge :: GCompare k => DMap (WrapArg Event k) -> Event (DMap k)
58[ ] mergeMap :: Ord k => Map k (Event a) -> Event (Map k a)
60-- Efficient one-to-many fanout
61[ ] fanMap :: Ord k => Event (Map k a) -> EventSelector (Const2 k a)
62[ ] fan :: GCompare k => Event (DMap k) -> EventSelector k
63[ ] select :: EventSelector k -> k a -> Event a
65-- Event to Event via monadic function
66[ ] push :: (a -> m (Maybe b)) -> Event a -> Event b
67[ ] pushAlways :: (a -> m b ) -> Event a -> Event b
68 -- Note supplied function operates in [H] context
70-- Event to monadic Event
71[H] headE :: Event a -> m (Event a)
72[H] tailE :: Event a -> m (Event a)
73[H] headTailE :: Event a -> m (Event a, Event a)
74```
76## Functions producing Behavior
78```haskell
79-- Trivial Behavior
80[ ] constant :: a -> Behavior a
82-- Extract Behavior from Dynamic
83[ ] current :: Dynamic a -> Behavior a
85-- Event to monadic Behavior
86[H] hold :: a -> Event a -> m (Behavior a)
88-- Transform Behavior to Behavior using function
89[ ] fmap :: (a -> b) -> Behavior a -> Behavior b
90[ ] ffor :: Behavior a -> (a -> b) -> Behavior b
91[ ] <*> :: Behavior (a -> b) -> Behavior a -> Behavior b
92[ ] >>= :: Behavior a -> (a -> Behavior b) -> Behavior b
93[ ] <> :: Monoid a => Behavior a -> Behavior a -> Behavior a
94-- ... plus many more due to typeclass membership
96-- Behavior to Behavior via monadic value
97[S] sample :: Behavior a -> m a
98[ ] pull :: m a -> Behavior a
99 -- Note supplied value is in [S] context
100```
102## Functions producing Dynamic
104```haskell
105-- Trivial Dynamic
106[ ] constDyn :: a -> Dynamic a
108-- Construct Dynamic from Event
109[H] holdDyn :: a -> Event a -> m (Dynamic a)
110[H] foldDyn :: (a -> b -> b ) -> b -> Event a -> m (Dynamic b)
111[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)
113[H] foldDynMaybeM :: (a -> b -> m' (Maybe b)) -> b -> Event a -> m (Dynamic b)
114 -- Note m' supplies [H] context
115[H] count :: Num b => Event a -> m (Dynamic b)
116[H] toggle :: Bool -> Event a -> m (Dynamic Bool)
118-- Transform Dynamic to Dynamic using function
119[H] forDyn :: Dynamic a -> (a -> b) -> m (Dynamic b)
120[H] mapDyn :: (a -> b) -> Dynamic a -> m (Dynamic b)
121[H] mapDynM :: (a -> m' b) -> Dynamic a -> m (Dynamic b)
122 -- Note m' supplies [S] context
123[H] splitDyn :: Dynamic (a, b) -> m (Dynamic a, Dynamic b)
125-- Combine multiple Dynamics
126[H] mconcatDyn :: Monoid a => [Dynamic a] -> m (Dynamic a)
127[H] distributeDMapOverDyn :: GCompare k => DMap (WrapArg Dynamic k) -> m (Dynamic (DMap k))
128[H] combineDyn :: (a -> b -> c) -> Dynamic a -> Dynamic b -> m (Dynamic c)
130-- Efficient one-to-many fanout
131[ ] demux :: Ord k => Dynamic k -> Demux k
132[H] getDemuxed :: Eq k => Demux k -> k -> m (Dynamic Bool)
134-- Dynamic to Dynamic, removing updates w/o value change
135[ ] nubDyn :: Eq a => Dynamic a -> Dynamic a
137-- Dynamic to identical Dynamic with debug trace.
138[ ] traceDyn :: Show a => String -> Dynamic a -> Dynamic a
139[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
140```
142## Flattening functions
144These functions flatten nested types such as Event-of-Event, Behavior-of-Event, Event-of-Behavior etc, removing the outer wrapper.
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.
148```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.
153[ ] switch :: Behavior (Event a) -> Event a
155-- Flatten Dyanmic-of-Event to Event. New Event is used immediately.
156[ ] switchPromptlyDyn :: Dynamic (Event a) -> Event a
158-- Flatten Event-of-Event to Event that fires when both wrapper AND new Event fire.
159[ ] coincidence :: Event (Event a) -> Event a
161-- Flatten Dynamic-of-Dynamic to Dynamic. New Dynamic is used immediately.
162-- Output updated whenever inner OR outer Dynamic updates.
163[ ] joinDyn :: Dynamic (Dynamic a) -> Dynamic a
164[ ] joinDynThroughMap :: Ord k => Dynamic (Map k (Dynamic a)) -> Dynamic (Map k a)
166-- Flatten Event-of-Behavior to monadic Behavior
167[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
168```