|
| 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 | +``` |
0 commit comments