@@ -1,10 +1,28 @@
1−# Reflex Quick Reference
1+# Reflex / Reflex-Dom Quick(ish) Reference
5+Many Reflex functions operate in monadic context `X a`, where the monadic type X supports various additional typeclasses such as MonadWidget, MonadHold, or MonadSample in addition to Monad itself. For Reflex-Dom users, the type X will generally be `Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider))`, from the Reflex-Dom main entry point:
8+mainWidget :: Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
3−Note that function signatures have been simplified by removing most typeclass constraints.
11+The function signatures here have been simplified by removing many typeclass constraints and adding simple annotations to each function.
5Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time".
13Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time".
7−Other functions must operate in some monadic context, because they produce a result "as of now". Functions annotated with "[H]" run in any monad supporting MonadHold. For Reflex-Dom users, this will typically be MonadWidget. Functions with "[S]" (of which there is only one) operate in MonadSample. Again, for Reflex-Dom users this is likely MonadWidget (because any MonadHold context also supports MonadSample).
15+Other functions must operate in some monadic context, because they produce a result "as of now". The annotations are:
18+[S] -- Function runs in any monad supporting MonadSample
19+[H] -- Function runs in any monad supporting MonadHold
20+[W] -- Function runs in any monad supporting MonadWidget
23+Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any [S] function also runs in [H] or [W] context, and any [H] function also runs in [W].
9### Functions producing Event
27### Functions producing Event
@@ -75,11 +93,10 @@ Other functions must operate in some monadic context, because they produce a res
75[ ] <*> :: Behavior t (a -> b) -> Behavior t a -> Behavior t b
93[ ] <*> :: Behavior t (a -> b) -> Behavior t a -> Behavior t b
76[ ] >>= :: Behavior t a -> (a -> Behavior t b) -> Behavior t b
94[ ] >>= :: Behavior t a -> (a -> Behavior t b) -> Behavior t b
77[ ] <> :: Monoid a => Behavior t a -> Behavior t a -> Behavior t a
95[ ] <> :: Monoid a => Behavior t a -> Behavior t a -> Behavior t a
78−-- Monadic value to Behavior
96+-- Behavior to Behavior via monadic value
97+[S] sample :: Behavior t a -> m a
79[ ] pull :: m a -> Behavior t a
98[ ] pull :: m a -> Behavior t a
80 -- Note supplied value is in [S] context
99 -- Note supplied value is in [S] context
81−-- Behavior to monadic value
82−[S] sample :: Behavior t a -> m a
83-- Event to monadic Behavior
100-- Event to monadic Behavior
84[H] hold :: a -> Event t a -> m (Behavior t a)
101[H] hold :: a -> Event t a -> m (Behavior t a)
85-- Unwrap Event-of-Behavior to monadic Behavior
102-- Unwrap Event-of-Behavior to monadic Behavior
@@ -91,14 +108,14 @@ Other functions must operate in some monadic context, because they produce a res
91```haskell
108```haskell
92-- Trivial Dynamic
109-- Trivial Dynamic
93[ ] constDyn :: a -> Dynamic t a
110[ ] constDyn :: a -> Dynamic t a
94−-- Construct monadic Dynamic from Event
111+-- Construct Dynamic from Event
95[H] holdDyn :: a -> Event t a -> m (Dynamic t a)
112[H] holdDyn :: a -> Event t a -> m (Dynamic t a)
96[H] foldDyn :: (a -> b -> b) -> b -> Event t a -> m (Dynamic t b)
113[H] foldDyn :: (a -> b -> b) -> b -> Event t a -> m (Dynamic t b)
97[H] foldDynM :: (a -> b -> m' b) -> b -> Event t a -> m (Dynamic t b)
114[H] foldDynM :: (a -> b -> m' b) -> b -> Event t a -> m (Dynamic t b)
98 -- Note supplied function operates in [H] context
115 -- Note supplied function operates in [H] context
99[H] count :: Num b => Event t a -> m (Dynamic t b)
116[H] count :: Num b => Event t a -> m (Dynamic t b)
100[H] toggle :: Bool -> Event t a -> m (Dynamic t Bool)
117[H] toggle :: Bool -> Event t a -> m (Dynamic t Bool)
101−-- Transform Dynamic to monadic Dynamic using function
118+-- Transform Dynamic to Dynamic using function
102[H] mapDyn :: (a -> b) -> Dynamic t a -> m (Dynamic t b)
119[H] mapDyn :: (a -> b) -> Dynamic t a -> m (Dynamic t b)
103[H] forDyn :: Dynamic t a -> (a -> b) -> m (Dynamic t b)
120[H] forDyn :: Dynamic t a -> (a -> b) -> m (Dynamic t b)
104[H] mapDynM :: (a -> m' b) -> Dynamic t a -> m (Dynamic t b)
121[H] mapDynM :: (a -> m' b) -> Dynamic t a -> m (Dynamic t b)
@@ -114,9 +131,49 @@ Other functions must operate in some monadic context, because they produce a res
114-- Efficient one-to-many fanout
131-- Efficient one-to-many fanout
115[ ] demux :: Ord k => Dynamic t k -> Demux t k
132[ ] demux :: Ord k => Dynamic t k -> Demux t k
116[H] getDemuxed :: Eq k => Demux t k -> k -> m (Dynamic t Bool)
133[H] getDemuxed :: Eq k => Demux t k -> k -> m (Dynamic t Bool)
117−-- Dynamic to Dynamic, removing Event occurrences w/o value change
134+-- Dynamic to Dynamic, removing updates w/o value change
118[ ] nubDyn :: Eq a => Dynamic t a -> Dynamic t a
135[ ] nubDyn :: Eq a => Dynamic t a -> Dynamic t a
119-- Dynamic to identical Dynamic with debug trace.
136-- Dynamic to identical Dynamic with debug trace.
120[ ] traceDyn :: Show a => String -> Dynamic t a -> Dynamic t a
137[ ] traceDyn :: Show a => String -> Dynamic t a -> Dynamic t a
121[ ] traceDynWith :: (a -> String) -> Dynamic t a -> Dynamic t a
138[ ] traceDynWith :: (a -> String) -> Dynamic t a -> Dynamic t a
146+-- Reflex-Dom entry point. Takes a monadic widget-building action of lengthy type and turns it into an IO action.
147+[I] mainWidget :: Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
148+[I] mainWidgetWithHead :: Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
149+[I] mainWidgetWithCss :: ByteString -> Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
150+-- One-shot Event that is triggered once all initial widgets are built
151+[W] getPostBuild :: m (Event t ())
154+### Performing side-effects
157+-- Run side-effecting actions in Event when it occurs; returned Event contains results. Side effects run in (WidgetHost m) monad, which includes [S] and [H] and can also do I/O via liftIO
158+[W] performEvent :: Event t (WidgetHost m a) -> m (Event t a)
159+-- Just run side-effects; no return Event
160+[W] performEvent_ :: Event t (WidgetHost m ()) -> m ()
161+-- Actions are run asynchronously; each action is given a callback to call when it completes
162+[W] performEventAsync :: Event t ((a -> IO ()) -> WidgetHost m ()) -> m (Event t a)
166+-- Create a static text element
167+[W] text :: String -> m ()
168+-- Additionally return the DOM element that was created.
169+[W] text' :: String -> m Text
170+-- Create a dynamic text element
171+[W] dynText :: Dynamic t String -> m ()
172+[W] display :: Show a => Dynamic t a -> m ()
173+-- Create a dynamically-redefined Widget, returning DOM elements as they're created
174+[W] dyn :: Dynamic t (m a) -> m (Event t a)
175+-- Like holdDyn, but each Event occurrence redefines the widget
176+[W] widgetHold :: m a -> Event t (m a) -> m (Dynamic t a)