@@ -1,10 +1,28 @@
1−# Reflex Quick Reference
1+# Reflex / Reflex-Dom Quick(ish) Reference
22
3−Note that function signatures have been simplified by removing most typeclass constraints.
3+## Typeclasses
4+
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:
6+
7+```haskell
8+mainWidget :: Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
9+```
10+
11+The function signatures here have been simplified by removing many typeclass constraints and adding simple annotations to each function.
412
513Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time".
614
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:
16+
17+```haskell
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
21+```
22+
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].
24+
25+## Reflex
826
927### Functions producing Event
1028
@@ -75,11 +93,10 @@ Other functions must operate in some monadic context, because they produce a res
7593[ ] <*> :: Behavior t (a -> b) -> Behavior t a -> Behavior t b
7694[ ] >>= :: Behavior t a -> (a -> Behavior t b) -> Behavior t b
7795[ ] <> :: 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
7998[ ] pull :: m a -> Behavior t a
8099 -- Note supplied value is in [S] context
81−-- Behavior to monadic value
82−[S] sample :: Behavior t a -> m a
83100-- Event to monadic Behavior
84101[H] hold :: a -> Event t a -> m (Behavior t a)
85102-- Unwrap Event-of-Behavior to monadic Behavior
@@ -91,14 +108,14 @@ Other functions must operate in some monadic context, because they produce a res
91108```haskell
92109-- Trivial Dynamic
93110[ ] constDyn :: a -> Dynamic t a
94−-- Construct monadic Dynamic from Event
111+-- Construct Dynamic from Event
95112[H] holdDyn :: a -> Event t a -> m (Dynamic t a)
96113[H] foldDyn :: (a -> b -> b) -> b -> Event t a -> m (Dynamic t b)
97114[H] foldDynM :: (a -> b -> m' b) -> b -> Event t a -> m (Dynamic t b)
98115 -- Note supplied function operates in [H] context
99116[H] count :: Num b => Event t a -> m (Dynamic t b)
100117[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
102119[H] mapDyn :: (a -> b) -> Dynamic t a -> m (Dynamic t b)
103120[H] forDyn :: Dynamic t a -> (a -> b) -> m (Dynamic t b)
104121[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
114131-- Efficient one-to-many fanout
115132[ ] demux :: Ord k => Dynamic t k -> Demux t k
116133[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
118135[ ] nubDyn :: Eq a => Dynamic t a -> Dynamic t a
119136-- Dynamic to identical Dynamic with debug trace.
120137[ ] traceDyn :: Show a => String -> Dynamic t a -> Dynamic t a
121138[ ] traceDynWith :: (a -> String) -> Dynamic t a -> Dynamic t a
122139```
140+
141+## Reflex-Dom
142+
143+### Startup
144+
145+```haskell
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 ())
152+```
153+
154+### Performing side-effects
155+
156+```haskell
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)
163+```
164+
165+```haskell
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)
177+
178+. . .
179+```