git.iko.soy/reflex
on snapshot help sign in
reflex/Quickref.md
183 lines 9.5 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.
9Some 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```haskell
12[ ] -- Pure function
13[S] -- Function runs in any monad supporting MonadSample
14[H] -- Function runs in any monad supporting MonadHold
15```
17Since MonadHold depends on MonadSample, any [S] function also runs in [H] context.
19## Functions producing Event
21```haskell
22-- Trivial Event
23[ ] never :: Event a
25-- Extract Event from Dynamic
26[ ] updated :: Dynamic a -> Event a
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
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
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[ ] tagPromptlyDyn :: Dynamic a -> Event b -> Event a
43[ ] attach :: Behavior a -> Event b -> Event (a, b)
44[ ] attachPromptlyDyn :: Dynamic a -> Event b -> Event (a, b)
45[ ] attachWith :: (a -> b -> c) -> Behavior a -> Event b -> Event c
46[ ] attachPromptlyDynWith :: (a -> b -> c) -> Dynamic a -> Event b -> Event c
47[ ] attachWithMaybe :: (a -> b -> Maybe c) -> Behavior a -> Event b -> Event c
48[ ] attachPromptlyDynWithMaybe :: (a -> b -> Maybe c) -> Dynamic a -> Event b -> Event c
50-- Combine multiple Events
51[ ] <> :: Semigroup a => Event a -> Event a -> Event a
52[ ] difference :: Event a -> Event b -> Event a
53[ ] align :: Event a -> Event b -> Event (These a b)
54[ ] alignWith :: (These a b -> c) -> Event a -> Event b -> Event c
55[ ] mergeWith :: (a -> a -> a) -> [Event a] -> Event a
56[ ] leftmost :: [Event a] -> Event a
57[ ] mergeList :: [Event a] -> Event (NonEmpty a)
58[ ] merge :: GCompare k => DMap (WrapArg Event k) -> Event (DMap k)
59[ ] mergeMap :: Ord k => Map k (Event a) -> Event (Map k a)
61-- Efficient one-to-many fanout
62[ ] fanMap :: Ord k => Event (Map k a) -> EventSelector (Const2 k a)
63[ ] fan :: GCompare k => Event (DMap k) -> EventSelector k
64[ ] select :: EventSelector k -> k a -> Event a
65[ ] fanEither :: Event (Either a b) -> (Event a, Event b)
66[ ] fanThese :: Event (These a b) -> (Event a, Event b)
68-- Event to Event via function that can sample current values
69[ ] push :: (a -> m (Maybe b)) -> Event a -> Event b
70[ ] pushAlways :: (a -> m b ) -> Event a -> Event b
71 -- Note supplied function operates in [H] context
73-- Split Event into next occurrence and all other future occurrences, as of now.
74[H] headE :: Event a -> m (Event a)
75[H] tailE :: Event a -> m (Event a)
76[H] headTailE :: Event a -> m (Event a, Event a)
77```
79## Functions producing Behavior
81```haskell
82-- Trivial Behavior
83[ ] constant :: a -> Behavior a
85-- Extract Behavior from Dynamic
86[ ] current :: Dynamic a -> Behavior a
88-- Create Behavior with given initial value, updated when the Event fires.
89[H] hold :: a -> Event a -> m (Behavior a)
91-- Transform Behavior to Behavior using function
92[ ] fmap :: (a -> b) -> Behavior a -> Behavior b
93[ ] ffor :: Behavior a -> (a -> b) -> Behavior b
94[ ] <*> :: Behavior (a -> b) -> Behavior a -> Behavior b
95[ ] >>= :: Behavior a -> (a -> Behavior b) -> Behavior b
96[ ] <> :: Monoid a => Behavior a -> Behavior a -> Behavior a
97-- ... plus many more due to typeclass membership
99-- Behavior to Behavior by sampling current values
100[S] sample :: Behavior a -> m a
101[ ] pull :: m a -> Behavior a
102 -- Note supplied value is in [S] context
103```
105## Functions producing Dynamic
107```haskell
108-- Trivial Dynamic
109[ ] constDyn :: a -> Dynamic a
111-- Create Dynamic with given initial value, updated (various ways) when the Event fires.
112[H] holdDyn :: a -> Event a -> m (Dynamic a)
113[H] foldDyn :: (a -> b -> b ) -> b -> Event a -> m (Dynamic b)
114[H] foldDynMaybe :: (a -> b -> Maybe b ) -> b -> Event a -> m (Dynamic b)
115[H] foldDynM :: (a -> b -> m' b ) -> b -> Event a -> m (Dynamic b)
116[H] foldDynMaybeM :: (a -> b -> m' (Maybe b)) -> b -> Event a -> m (Dynamic b)
117 -- Note m' supplies [H] context
119-- Initial value is 0; counts Event firings from now.
120[H] count :: Num b => Event a -> m (Dynamic b)
121-- Initial Bool value is supplied; toggles at each Event firing.
122[H] toggle :: Bool -> Event a -> m (Dynamic Bool)
124-- Transform Dynamic to Dynamic using function
125[ ] ffor :: Dynamic a -> (a -> b) -> Dynamic b
126[ ] fmap :: (a -> b) -> Dynamic a -> Dynamic b
127[ ] splitDynPure :: Dynamic (a, b) -> (Dynamic a, Dynamic b)
129-- Combine multiple Dynamics
130[ ] mconcat :: Monoid a => [Dynamic a] -> Dynamic a
131[ ] distributeDMapOverDynPure :: GCompare k => DMap (WrapArg Dynamic k) -> Dynamic (DMap k)
132[ ] <*> :: Dynamic (a -> b) -> Dynamic a -> Dynamic b
133[ ] >>= :: Dynamic a -> (a -> Dynamic b) -> Dynamic b
134[ ] zipDynWith :: (a -> b -> c) -> Dynamic a -> Dynamic b -> Dynamic c
136-- Efficient one-to-many fanout
137[ ] demux :: Ord k => Dynamic k -> Demux k
138[ ] demuxed :: Eq k => Demux k -> k -> Dynamic Bool
140-- Dynamic to Dynamic, removing updates w/o value change
141[ ] uniqDyn :: Eq a => Dynamic a -> Dynamic a
143-- Dynamic to identical Dynamic with debug trace. (Only prints if Dynamic is ultimately used.)
144[ ] traceDyn :: Show a => String -> Dynamic a -> Dynamic a
145[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
146```
148## Flattening functions
150These functions flatten nested types such as Event-of-Event, Behavior-of-Event, Event-of-Behavior etc, removing the outer wrapper.
152For 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.
154```haskell
155-- Flatten Behavior-of-Event to Event. Old Event is used during switchover.
156[ ] switch :: Behavior (Event a) -> Event a
158-- Flatten Dyanmic-of-Event to Event. New Event is used immediately.
159[ ] switchPromptlyDyn :: Dynamic (Event a) -> Event a
161-- Flatten Event-of-Event to Event that fires when both wrapper AND new Event fire.
162[ ] coincidence :: Event (Event a) -> Event a
164-- Flatten Behavior-of-Behavior to Behavior. Behavior is an instance of Monad,
165-- so the 'join' function from 'Control.Monad' suffices. The output of 'join' is
166-- a Behavior whose value is equal to the current value of the current value of
167-- the input.
168[ ] join :: Behavior (Behavior a) -> Behavior a
171-- Flatten Dynamic-of-Dynamic to Dynamic. New Dynamic is used immediately.
172-- Output updated whenever inner OR outer Dynamic updates.
173[ ] join :: Dynamic (Dynamic a) -> Dynamic a
174[ ] joinDynThroughMap :: Ord k => Dynamic (Map k (Dynamic a)) -> Dynamic (Map k a)
176-- Analogous to 'hold': Create a Behavior that is initially identical to the
177-- supplied Behavior. Updated to track a new Behavior whenever the Event fires.
178[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
180-- Similar to above, for Events. Created Event initially tracks the first argument.
181-- At switchover, the output Event immediately tracks the new Event.
182[H] switchPromptly :: Event a -> Event (Event a) -> m (Event a)
183```