1# Reflex Quick(ish) Reference
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:
13[S] -- Function runs in any monad supporting MonadSample
14[H] -- Function runs in any monad supporting MonadHold
16Since MonadHold depends on MonadSample, any [S] function also runs in [H] context.
18## Functions producing Event
24-- Extract Event from Dynamic
25[ ] updated :: Dynamic a -> Event a
27-- Transform Event to Event using function
28[ ] fmap :: (a -> b) -> Event a -> Event b
29[ ] fmapMaybe :: (a -> Maybe b) -> Event a -> Event b
30[ ] ffilter :: (a -> Bool) -> Event a -> Event a
31[ ] ffor :: Event a -> (a -> b) -> Event b
32[ ] fforMaybe :: Event a -> (a -> Maybe b) -> Event b
33[ ] <$ :: a -> Event b -> Event a
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
49[ ] <@> :: Behavior (a -> b) -> Event a -> Event b
50[ ] <@ :: Behavior a -> Event b -> Event a
52-- Combine multiple Events
53[ ] <> :: Semigroup a => Event a -> Event a -> Event a
54[ ] difference :: Event a -> Event b -> Event a
55[ ] align :: Event a -> Event b -> Event (These a b)
56[ ] alignWith :: (These a b -> c) -> Event a -> Event b -> Event c
57[ ] mergeWith :: (a -> a -> a) -> [Event a] -> Event a
58[ ] leftmost :: [Event a] -> Event a
59[ ] mergeList :: [Event a] -> Event (NonEmpty a)
60[ ] merge :: GCompare k => DMap k Event -> Event (DMap k Identity)
61[ ] mergeMap :: Ord k => Map k (Event a) -> Event (Map k a)
63-- Efficient one-to-many fanout
64[ ] fanMap :: Ord k => Event (Map k a) -> EventSelector (Const2 k a)
65[ ] fan :: GCompare k => Event (DMap k Identity) -> EventSelector k
66[ ] select :: EventSelector k -> k a -> Event a
67[ ] fanEither :: Event (Either a b) -> (Event a, Event b)
68[ ] fanThese :: Event (These a b) -> (Event a, Event b)
70-- Event to Event via function that can sample current values
71[ ] push :: (a -> m (Maybe b)) -> Event a -> Event b
72[ ] pushAlways :: (a -> m b ) -> Event a -> Event b
73 -- Note supplied function operates in [H] context
75-- Split Event into next occurrence and all other future occurrences, as of now.
76[H] headE :: Event a -> m (Event a)
77[H] tailE :: Event a -> m (Event a)
78[H] headTailE :: Event a -> m (Event a, Event a)
81## Functions producing Behavior
85[ ] constant :: a -> Behavior a
87-- Extract Behavior from Dynamic
88[ ] current :: Dynamic a -> Behavior a
90-- Create Behavior with given initial value, updated when the Event fires.
91[H] hold :: a -> Event a -> m (Behavior a)
93-- Transform Behavior to Behavior using function
94[ ] fmap :: (a -> b) -> Behavior a -> Behavior b
95[ ] ffor :: Behavior a -> (a -> b) -> Behavior b
96[ ] <*> :: Behavior (a -> b) -> Behavior a -> Behavior b
97[ ] >>= :: Behavior a -> (a -> Behavior b) -> Behavior b
98[ ] <> :: Monoid a => Behavior a -> Behavior a -> Behavior a
99-- ... plus many more due to typeclass membership
101-- Combine multiple behaviors via applicative instance
102[ ] ffor2 :: Behavior a -> Behavior b -> (a -> b -> c) -> Behavior c
103[ ] ffor3 :: Behavior a -> Behavior b -> Behavior c -> (a -> b -> c -> d) -> Behavior d
105-- Behavior to Behavior by sampling current values
106[S] sample :: Behavior a -> m a
107[ ] pull :: m a -> Behavior a
108 -- Note supplied value is in [S] context
111## Functions producing Dynamic
115[ ] constDyn :: a -> Dynamic a
117-- Create Dynamic with given initial value, updated (various ways) when the Event fires.
118[H] holdDyn :: a -> Event a -> m (Dynamic a)
119[H] foldDyn :: (a -> b -> b ) -> b -> Event a -> m (Dynamic b)
120[H] foldDynMaybe :: (a -> b -> Maybe b ) -> b -> Event a -> m (Dynamic b)
121[H] foldDynM :: (a -> b -> m' b ) -> b -> Event a -> m (Dynamic b)
122[H] foldDynMaybeM :: (a -> b -> m' (Maybe b)) -> b -> Event a -> m (Dynamic b)
123 -- Note m' supplies [H] context
125-- Initial value is 0; counts Event firings from now.
126[H] count :: Num b => Event a -> m (Dynamic b)
127-- Initial Bool value is supplied; toggles at each Event firing.
128[H] toggle :: Bool -> Event a -> m (Dynamic Bool)
130-- Transform Dynamic to Dynamic using function
131[ ] ffor :: Dynamic a -> (a -> b) -> Dynamic b
132[ ] fmap :: (a -> b) -> Dynamic a -> Dynamic b
133[ ] splitDynPure :: Dynamic (a, b) -> (Dynamic a, Dynamic b)
135-- Combine multiple Dynamics
136[ ] mconcat :: Monoid a => [Dynamic a] -> Dynamic a
137[ ] distributeDMapOverDynPure :: GCompare k => DMap (WrapArg Dynamic k) -> Dynamic (DMap k)
138[ ] <*> :: Dynamic (a -> b) -> Dynamic a -> Dynamic b
139[ ] >>= :: Dynamic a -> (a -> Dynamic b) -> Dynamic b
140[ ] zipDynWith :: (a -> b -> c) -> Dynamic a -> Dynamic b -> Dynamic c
142-- Combine multiple dynamics via applicative instance
143[ ] ffor2 :: Dynamic a -> Dynamic b -> (a -> b -> c) -> Dynamic c
144[ ] ffor3 :: Dynamic a -> Dynamic b -> Dynamic c -> (a -> b -> c -> d) -> Dynamic d
146-- Efficient one-to-many fanout
147[ ] demux :: Ord k => Dynamic k -> Demux k
148[ ] demuxed :: Eq k => Demux k -> k -> Dynamic Bool
150-- Dynamic to Dynamic, removing updates w/o value change
151[H] holdUniqDyn :: Eq a => Dynamic a -> m (Dynamic a)
152[H] holdUniqDynBy :: (a -> a -> Bool) -> Dynamic t a -> m (Dynamic t a)
154-- Dynamic to identical Dynamic with debug trace. (Only prints if Dynamic is ultimately used.)
155[ ] traceDyn :: Show a => String -> Dynamic a -> Dynamic a
156[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
159## Flattening functions
161These functions flatten nested types such as Event-of-Event, Behavior-of-Event, Event-of-Behavior etc, removing the outer wrapper.
163For 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.
166-- Flatten Behavior-of-Event to Event. Old Event is used during switchover.
167[ ] switch :: Behavior (Event a) -> Event a
169-- Flatten Dynamic-of-Event to Event. New Event is used immediately.
170[ ] switchDyn :: Dynamic (Event a) -> Event a
172-- Flatten Event-of-Event to Event that fires when both wrapper AND new Event fire.
173[ ] coincidence :: Event (Event a) -> Event a
175-- Flatten Behavior-of-Behavior to Behavior. Behavior is an instance of Monad,
176-- so the 'join' function from 'Control.Monad' suffices. The output of 'join' is
177-- a Behavior whose value is equal to the current value of the current value of
179[ ] join :: Behavior (Behavior a) -> Behavior a
182-- Flatten Dynamic-of-Dynamic to Dynamic. New Dynamic is used immediately.
183-- Output updated whenever inner OR outer Dynamic updates.
184[ ] join :: Dynamic (Dynamic a) -> Dynamic a
185[ ] joinDynThroughMap :: Ord k => Dynamic (Map k (Dynamic a)) -> Dynamic (Map k a)
187-- Analogous to 'hold': Create a Behavior that is initially identical to the
188-- supplied Behavior. Updated to track a new Behavior whenever the Event fires.
189[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
191-- Similar to above, for Events. Created Event initially tracks the first argument.
192-- At switchover, the output Event immediately tracks the new Event.
193[H] switchHold :: Event a -> Event (Event a) -> m (Event a)
196## Typeclasses to introspect and modify an FRP network.
198The functions mentioned above are used to create a static FRP network.
199There are additional typeclasses that can be used to modify the FRP network, to have it interact with IO action, or to introspect the building of the network.
201The typeclasses and their associated annotations include:
204 Fire an Event when an FRP network has been set up.
206 [B] -- Function runs in any monad supporting PostBuild
210 Use Events to add or remove pieces of an FRP network.
212 [A] -- Function runs in any monad supporting Adjustable
216 Create new externally-fired Events from within an FRP network.
218 [T] -- Function runs in any monad supporting TriggerEvent
222 Use Events to trigger IO actions and to collect their results.
224 [P] -- Function runs in any monad supporting PerformEvent
230-- One-shot Event that is triggered once the FRP network has been built
231[B] getPostBuild :: m (Event ())
234## Collection management functions
237-- Turn a Dynamic key/value map into a set of dynamically-changing widgets.
238[H,A,B] listWithKey :: Ord k =>
239 Dynamic (Map k v) -> (k -> Dynamic v -> m a ) -> m (Dynamic (Map k a))
241-- Same as above where the widget constructor doesn't care about the key.
242[H,A,B] list :: Ord k =>
243 Dynamic (Map k v) -> ( Dynamic v -> m a ) -> m (Dynamic (Map k a))
245-- Even simpler version where there are no keys and we just use a list.
247 Dynamic [v] -> ( Dynamic v -> m a ) -> m (Dynamic [a])
249-- Like listWithKey specialized for widgets returning (Event a).
250[H,A,B] listViewWithKey :: Ord k =>
251 Dynamic (Map k v) -> (k -> Dynamic v -> m (Event a)) -> m (Event (Map k a))
253-- Create a dynamically-changing set of widgets, one of which is selected at any time.
254[H,A,B] selectViewListWithKey_ :: Ord k => Dynamic k ->
255 Dynamic (Map k v) -> (k -> Dynamic v -> Dynamic Bool -> m (Event a)) -> m (Event k)
257-- Same as listWithKey, but takes initial values and an updates Event instead of a Dynamic.
258[H,A] listWithKeyShallowDiff :: Ord k =>
259 Map k v -> Event (Map k (Maybe v)) -> (k -> v -> Event v -> m a) -> m (Dynamic (Map k a))
262## Creating new events from within an FRP network.
265-- Create a new Event and a function that will cause the Event to fire, from within an FRP network
266[T] newTriggerEvent :: m (Event a, a -> IO ())
269## Connecting to the real world (I/O)
272-- Run side-effecting actions in Event when it occurs; returned Event contains
273-- results. Side effects run in the (Performable m) monad which is associated with
274-- the (PerformEvent t m) typeclass constraint.
275-- This allows for working with IO when a ((MonadIO (Performable m)) constraint is available.
276[P] performEvent :: Event (Performable m a ) -> m (Event a)
278-- Just run side-effects; no return Event
279[P] performEvent_ :: Event (Performable m ()) -> m ()
281-- Actions run asynchronously; actions are given a callback to send return values
282[P,T] performEventAsync :: Event ((a -> IO ()) -> Performable m ()) -> m (Event a)
288-- Create Event at given interval with given basis time.
289[P,T] tickLossy :: NominalDiffTime -> UTCTime -> m (Event t TickInfo)
291-- Delay an Event's occurrences by a given amount in seconds.
292[P,T] delay :: NominalDiffTime -> Event t a -> m (Event t a)
298-- Functions from Reflex.Adjustable / Reflex.Network used to deal with Dynamics/Events carrying (m a)
300[A] runWithReplace :: m a -> Event t (m b) -> m (a, Event t b)
302-- Given a Dynamic of network-creating actions, create a network that is recreated whenever the Dynamic updates.
303-- The returned Event of network results occurs when the Dynamic does. Note: Often, the type a is an Event,
304-- in which case the return value is an Event-of-Events that would typically be flattened (via switchHold).
305[P,A] networkView :: Dynamic (m a) -> m (Event a)
307-- Given an initial network and an Event of network-creating actions, create a network that is recreated whenever the
308-- Event fires. The returned Dynamic of network results occurs when the Event does. Note: Often, the type a is an
309-- Event, in which case the return value is a Dynamic-of-Events that would typically be flattened.
310[H,A] networkHold :: m a -> Event (m a) -> m (Dynamic a)
312-- Render a placeholder network to be shown while another network is not yet done building
313[P,A] untilReady :: m a -> m b -> m (a, Event b)
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list