git.iko.soy/reflex
on develop help sign in
Merge pull request #284 from reflex-frp/aa-docs

Add some haddocks

commit319fe5fcebde16c34ad6bf1150dcaec99216357d authorRyan Trinkle <ryan.trinkle@gmail.com> dateSun 17 Mar 2019, 15:14 (8 years ago) parent032e6b24b98630
13 files changed+268−69
compare with develop
unifiedsplit
src/Reflex/Class.hs+160−25 src/Reflex/Collection.hs+8 src/Reflex/Dynamic.hs+6−2 src/Reflex/FastWeak.hs+10−6 src/Reflex/FunctorMaybe.hs+6−2 src/Reflex/Network.hs+10−4 src/Reflex/Optimizer.hs+8−4 src/Reflex/Patch.hs+6−5 src/Reflex/Profiled.hs+6 src/Reflex/Pure.hs+7−5 src/Reflex/Spider.hs+5−2 src/Reflex/Time.hs+23−13 src/Reflex/Workflow.hs+13−1
src/Reflex/Class.hs+160−25
@@ -21,9 +21,13 @@
2121{-# OPTIONS_GHC -fplugin=Reflex.Optimizer #-}
2222#endif
2323
24−-- | This module contains the Reflex interface, as well as a variety of
25−-- convenience functions for working with 'Event's, 'Behavior's, and other
26−-- signals.
24+-- |
25+-- Module:
26+-- Reflex.Class
27+-- Description:
28+-- This module contains the Reflex interface, as well as a variety of
29+-- convenience functions for working with 'Event's, 'Behavior's, and other
30+-- signals.
2731module Reflex.Class
2832 ( module Reflex.Patch
2933 -- * Primitives
@@ -256,8 +260,7 @@ class ( MonadHold t (PushM t)
256260 -- | Create an 'Event' that will occur whenever the currently-selected input
257261 -- 'Event' occurs
258262 switch :: Behavior t (Event t a) -> Event t a
259− -- | Create an 'Event' that will occur whenever the input event is occurring
260− -- and its occurrence value, another 'Event', is also occurring
263+ -- | Create an 'Event' that will occur whenever the input event is occurring -- and its occurrence value, another 'Event', is also occurring
261264 coincidence :: Event t (Event t a) -> Event t a
262265 -- | Extract the 'Behavior' of a 'Dynamic'.
263266 current :: Dynamic t a -> Behavior t a
@@ -998,14 +1001,16 @@ distributeListOverDynWith f = fmap (f . map (\(Const2 _ :=> Identity v) -> v) .
9981001difference :: Reflex t => Event t a -> Event t b -> Event t a
9991002difference = alignEventWithMaybe $ \case
10001003 This a -> Just a
1001− _ -> Nothing
1004+ _ -> Nothing
10021005
1006+-- | Zips two values by taking the union of their shapes and combining with the provided function.
1007+-- 'Nothing' values are dropped.
10031008alignEventWithMaybe :: Reflex t => (These a b -> Maybe c) -> Event t a -> Event t b -> Event t c
1004−alignEventWithMaybe f ea eb =
1005− fmapMaybe (f <=< dmapToThese)
1006− $ merge
1007− $ DMap.fromList [LeftTag :=> ea, RightTag :=> eb]
1009+alignEventWithMaybe f ea eb = fmapMaybe (f <=< dmapToThese) $
1010+ merge $ DMap.fromList [LeftTag :=> ea, RightTag :=> eb]
10081011
1012+-- | Produces an 'Event' that fires only when the input event fires with a 'DSum' key that
1013+-- matches the provided key.
10091014filterEventKey
10101015 :: forall t m k v a.
10111016 ( Reflex t
@@ -1023,7 +1028,10 @@ filterEventKey k kv' = do
10231028 Nothing -> Nothing
10241029 takeWhileJustE f kv'
10251030
1026−
1031+-- | "Factor" the input 'DSum' 'Event' to produce an 'Event' which
1032+-- fires when the 'DSum' key changes and contains both the value of the
1033+-- 'DSum' at switchover and an 'Event' of values produced by subsequent
1034+-- firings of the input 'Event' that do not change the 'DSum' key.
10271035factorEvent
10281036 :: forall t m k v a.
10291037 ( Reflex t
@@ -1073,26 +1081,94 @@ class Reflex t => Accumulator t f | f -> t where
10731081 mapAccumMaybe f = mapAccumMaybeM $ \v o -> return $ f v o
10741082 mapAccumMaybeM :: (MonadHold t m, MonadFix m) => (a -> b -> PushM t (Maybe a, Maybe c)) -> a -> Event t b -> m (f a, Event t c)
10751083
1076−accumDyn :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> a) -> a -> Event t b -> m (Dynamic t a)
1084+-- | Accumulate a 'Dynamic' by folding occurrences of an 'Event'
1085+-- with the provided function. See 'foldDyn'.
1086+accumDyn
1087+ :: (Reflex t, MonadHold t m, MonadFix m)
1088+ => (a -> b -> a)
1089+ -> a
1090+ -> Event t b
1091+ -> m (Dynamic t a)
10771092accumDyn f = accumMaybeDyn $ \v o -> Just $ f v o
1078−accumMDyn :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> PushM t a) -> a -> Event t b -> m (Dynamic t a)
1093+
1094+-- | Accumulate a 'Dynamic' by folding occurrences of an 'Event'
1095+-- with the provided 'PushM' action.
1096+accumMDyn
1097+ :: (Reflex t, MonadHold t m, MonadFix m)
1098+ => (a -> b -> PushM t a)
1099+ -> a
1100+ -> Event t b
1101+ -> m (Dynamic t a)
10791102accumMDyn f = accumMaybeMDyn $ \v o -> Just <$> f v o
1080−accumMaybeDyn :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> Maybe a) -> a -> Event t b -> m (Dynamic t a)
1103+
1104+-- | Accumulate a 'Dynamic' by folding occurrences of an 'Event'
1105+-- with the provided function, discarding 'Nothing' results.
1106+accumMaybeDyn
1107+ :: (Reflex t, MonadHold t m, MonadFix m)
1108+ => (a -> b -> Maybe a)
1109+ -> a
1110+ -> Event t b
1111+ -> m (Dynamic t a)
10811112accumMaybeDyn f = accumMaybeMDyn $ \v o -> return $ f v o
1082−accumMaybeMDyn :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> PushM t (Maybe a)) -> a -> Event t b -> m (Dynamic t a)
1113+
1114+-- | Accumulate a 'Dynamic' by folding occurrences of an 'Event'
1115+-- with the provided 'PushM' action, discarding 'Nothing' results.
1116+accumMaybeMDyn
1117+ :: (Reflex t, MonadHold t m, MonadFix m)
1118+ => (a -> b -> PushM t (Maybe a))
1119+ -> a
1120+ -> Event t b
1121+ -> m (Dynamic t a)
10831122accumMaybeMDyn f z e = do
10841123 rec let e' = flip push e $ \o -> do
10851124 v <- sample $ current d'
10861125 f v o
10871126 d' <- holdDyn z e'
10881127 return d'
1089−mapAccumDyn :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> (a, c)) -> a -> Event t b -> m (Dynamic t a, Event t c)
1128+
1129+-- | Accumulate a 'Dynamic' by folding occurrences of an 'Event'
1130+-- with a function that both accumulates and produces a value to fire
1131+-- as an 'Event'. Returns both the accumulated value and an 'Event'.
1132+mapAccumDyn
1133+ :: (Reflex t, MonadHold t m, MonadFix m)
1134+ => (a -> b -> (a, c))
1135+ -> a
1136+ -> Event t b
1137+ -> m (Dynamic t a, Event t c)
10901138mapAccumDyn f = mapAccumMaybeDyn $ \v o -> bimap Just Just $ f v o
1091−mapAccumMDyn :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> PushM t (a, c)) -> a -> Event t b -> m (Dynamic t a, Event t c)
1139+
1140+-- | Similar to 'mapAccumDyn' except that the combining function is a
1141+-- 'PushM' action.
1142+mapAccumMDyn
1143+ :: (Reflex t, MonadHold t m, MonadFix m)
1144+ => (a -> b -> PushM t (a, c))
1145+ -> a
1146+ -> Event t b
1147+ -> m (Dynamic t a, Event t c)
10921148mapAccumMDyn f = mapAccumMaybeMDyn $ \v o -> bimap Just Just <$> f v o
1093−mapAccumMaybeDyn :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> (Maybe a, Maybe c)) -> a -> Event t b -> m (Dynamic t a, Event t c)
1149+
1150+-- | Accumulate a 'Dynamic' by folding occurrences of an 'Event' with
1151+-- a function that both optionally accumulates and optionally produces
1152+-- a value to fire as a separate output 'Event'.
1153+-- Note that because 'Nothing's are discarded in both cases, the output
1154+-- 'Event' may fire even though the output 'Dynamic' has not changed, and
1155+-- the output 'Dynamic' may update even when the output 'Event' is not firing.
1156+mapAccumMaybeDyn
1157+ :: (Reflex t, MonadHold t m, MonadFix m)
1158+ => (a -> b -> (Maybe a, Maybe c))
1159+ -> a
1160+ -> Event t b
1161+ -> m (Dynamic t a, Event t c)
10941162mapAccumMaybeDyn f = mapAccumMaybeMDyn $ \v o -> return $ f v o
1095−mapAccumMaybeMDyn :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> PushM t (Maybe a, Maybe c)) -> a -> Event t b -> m (Dynamic t a, Event t c)
1163+
1164+-- | Like 'mapAccumMaybeDyn' except that the combining function is a
1165+-- 'PushM' action.
1166+mapAccumMaybeMDyn
1167+ :: (Reflex t, MonadHold t m, MonadFix m)
1168+ => (a -> b -> PushM t (Maybe a, Maybe c))
1169+ -> a
1170+ -> Event t b
1171+ -> m (Dynamic t a, Event t c)
10961172mapAccumMaybeMDyn f z e = do
10971173 rec let e' = flip push e $ \o -> do
10981174 v <- sample $ current d'
@@ -1103,15 +1179,39 @@ mapAccumMaybeMDyn f z e = do
11031179 d' <- holdDyn z $ fmapMaybe fst e'
11041180 return (d', fmapMaybe snd e')
11051181
1182+-- | Accumulate a 'Behavior' by folding occurrences of an 'Event'
1183+-- with the provided function.
11061184{-# INLINE accumB #-}
1107−accumB :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> a) -> a -> Event t b -> m (Behavior t a)
1185+accumB
1186+ :: (Reflex t, MonadHold t m, MonadFix m)
1187+ => (a -> b -> a)
1188+ -> a
1189+ -> Event t b
1190+ -> m (Behavior t a)
11081191accumB f = accumMaybeB $ \v o -> Just $ f v o
1192+
1193+-- | Like 'accumB' except that the combining function is a 'PushM' action.
11091194{-# INLINE accumMB #-}
1110−accumMB :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> PushM t a) -> a -> Event t b -> m (Behavior t a)
1195+accumMB
1196+ :: (Reflex t, MonadHold t m, MonadFix m)
1197+ => (a -> b -> PushM t a)
1198+ -> a
1199+ -> Event t b
1200+ -> m (Behavior t a)
11111201accumMB f = accumMaybeMB $ \v o -> Just <$> f v o
1202+
1203+-- | Accumulate a 'Behavior' by folding occurrences of an 'Event'
1204+-- with the provided function, discarding 'Nothing' results.
11121205{-# INLINE accumMaybeB #-}
1113−accumMaybeB :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> Maybe a) -> a -> Event t b -> m (Behavior t a)
1206+accumMaybeB
1207+ :: (Reflex t, MonadHold t m, MonadFix m)
1208+ => (a -> b -> Maybe a)
1209+ -> a
1210+ -> Event t b
1211+ -> m (Behavior t a)
11141212accumMaybeB f = accumMaybeMB $ \v o -> return $ f v o
1213+
1214+-- | Like 'accumMaybeB' except that the combining function is a 'PushM' action.
11151215{-# INLINE accumMaybeMB #-}
11161216accumMaybeMB :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> PushM t (Maybe a)) -> a -> Event t b -> m (Behavior t a)
11171217accumMaybeMB f z e = do
@@ -1120,16 +1220,42 @@ accumMaybeMB f z e = do
11201220 f v o
11211221 d' <- hold z e'
11221222 return d'
1223+
1224+-- | Accumulate a 'Behavior' by folding occurrences of an 'Event'
1225+-- with a function that both accumulates and produces a value to fire
1226+-- as an 'Event'. Returns both the accumulated value and an 'Event'.
11231227{-# INLINE mapAccumB #-}
1124−mapAccumB :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> (a, c)) -> a -> Event t b -> m (Behavior t a, Event t c)
1228+mapAccumB
1229+ :: (Reflex t, MonadHold t m, MonadFix m)
1230+ => (a -> b -> (a, c))
1231+ -> a
1232+ -> Event t b
1233+ -> m (Behavior t a, Event t c)
11251234mapAccumB f = mapAccumMaybeB $ \v o -> bimap Just Just $ f v o
1235+
1236+-- | Like 'mapAccumB' except that the combining function is a 'PushM' action.
11261237{-# INLINE mapAccumMB #-}
1127−mapAccumMB :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> PushM t (a, c)) -> a -> Event t b -> m (Behavior t a, Event t c)
1238+mapAccumMB
1239+ :: (Reflex t, MonadHold t m, MonadFix m)
1240+ => (a -> b -> PushM t (a, c))
1241+ -> a
1242+ -> Event t b
1243+ -> m (Behavior t a, Event t c)
11281244mapAccumMB f = mapAccumMaybeMB $ \v o -> bimap Just Just <$> f v o
1245+
1246+-- | Accumulate a 'Behavior' by folding occurrences of an 'Event' with
1247+-- a function that both optionally accumulates and optionally produces
1248+-- a value to fire as a separate output 'Event'. 'Nothing's are discarded.
11291249{-# INLINE mapAccumMaybeB #-}
1130−mapAccumMaybeB :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> (Maybe a, Maybe c)) -> a -> Event t b -> m (Behavior t a, Event t c)
1250+mapAccumMaybeB
1251+ :: (Reflex t, MonadHold t m, MonadFix m)
1252+ => (a -> b -> (Maybe a, Maybe c))
1253+ -> a
1254+ -> Event t b
1255+ -> m (Behavior t a, Event t c)
11311256mapAccumMaybeB f = mapAccumMaybeMB $ \v o -> return $ f v o
11321257
1258+-- | LIke 'mapAccumMaybeB' except that the combining function is a 'PushM' action.
11331259{-# INLINE mapAccumMaybeMB #-}
11341260mapAccumMaybeMB :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> PushM t (Maybe a, Maybe c)) -> a -> Event t b -> m (Behavior t a, Event t c)
11351261mapAccumMaybeMB f z e = do
@@ -1284,38 +1410,47 @@ infixl 4 <@
12841410-- Cheap Functions
12851411------------------
12861412
1413+-- | A "cheap" version of 'pushAlways'. See the performance note on 'pushCheap'.
12871414{-# INLINE pushAlwaysCheap #-}
12881415pushAlwaysCheap :: Reflex t => (a -> PushM t b) -> Event t a -> Event t b
12891416pushAlwaysCheap f = pushCheap (fmap Just . f)
12901417
1418+-- | A "cheap" version of 'fmapMaybe'. See the performance note on 'pushCheap'.
12911419{-# INLINE fmapMaybeCheap #-}
12921420fmapMaybeCheap :: Reflex t => (a -> Maybe b) -> Event t a -> Event t b
12931421fmapMaybeCheap f = pushCheap $ return . f
12941422
1423+-- | A "cheap" version of 'fforMaybe'. See the performance note on 'pushCheap'.
12951424{-# INLINE fforMaybeCheap #-}
12961425fforMaybeCheap :: Reflex t => Event t a -> (a -> Maybe b) -> Event t b
12971426fforMaybeCheap = flip fmapMaybeCheap
12981427
1428+-- | A "cheap" version of 'ffor'. See the performance note on 'pushCheap'.
12991429{-# INLINE fforCheap #-}
13001430fforCheap :: Reflex t => Event t a -> (a -> b) -> Event t b
13011431fforCheap = flip fmapCheap
13021432
1433+-- | A "cheap" version of 'fmap'. See the performance note on 'pushCheap'.
13031434{-# INLINE fmapCheap #-}
13041435fmapCheap :: Reflex t => (a -> b) -> Event t a -> Event t b
13051436fmapCheap f = pushCheap $ return . Just . f
13061437
1438+-- | A "cheap" version of 'tag'. See the performance note on 'pushCheap'.
13071439{-# INLINE tagCheap #-}
13081440tagCheap :: Reflex t => Behavior t b -> Event t a -> Event t b
13091441tagCheap b = pushAlwaysCheap $ \_ -> sample b
13101442
1443+-- | A "cheap" version of 'mergeWithCheap'. See the performance note on 'pushCheap'.
13111444{-# INLINE mergeWithCheap #-}
13121445mergeWithCheap :: Reflex t => (a -> a -> a) -> [Event t a] -> Event t a
13131446mergeWithCheap = mergeWithCheap' id
13141447
1448+-- | A "cheap" version of 'mergeWithCheap''. See the performance note on 'pushCheap'.
13151449{-# INLINE mergeWithCheap' #-}
13161450mergeWithCheap' :: Reflex t => (a -> b) -> (b -> b -> b) -> [Event t a] -> Event t b
13171451mergeWithCheap' f g = mergeWithFoldCheap' $ foldl1 g . fmap f
13181452
1453+-- | A "cheap" version of 'mergeWithFoldCheap''. See the performance note on 'pushCheap'.
13191454{-# INLINE mergeWithFoldCheap' #-}
13201455mergeWithFoldCheap' :: Reflex t => (NonEmpty a -> b) -> [Event t a] -> Event t b
13211456mergeWithFoldCheap' f es =
src/Reflex/Collection.hs+8
@@ -10,6 +10,9 @@
1010#ifdef USE_REFLEX_OPTIMIZER
1111{-# OPTIONS_GHC -fplugin=Reflex.Optimizer #-}
1212#endif
13+-- |
14+-- Module:
15+-- Reflex.Collection
1316module Reflex.Collection
1417 (
1518 -- * Widgets on Collections
@@ -38,6 +41,9 @@ import Reflex.Adjustable.Class
3841import Reflex.Dynamic
3942import Reflex.PostBuild.Class
4043
44+-- | Create a set of widgets based on the provided 'Map'. When the
45+-- input 'Event' fires, remove widgets for keys with the value 'Nothing'
46+-- and add/replace widgets for keys with 'Just' values.
4147listHoldWithKey
4248 :: forall t m k v a
4349 . (Ord k, Adjustable t m, MonadHold t m)
@@ -182,6 +188,8 @@ selectViewListWithKey selection vals mkChild = do
182188 return $ fmap ((,) k) selectSelf
183189 return $ switchPromptlyDyn $ leftmost . Map.elems <$> selectChild
184190
191+-- | Like 'selectViewListWithKey' but discards the value of the list
192+-- item widget's output 'Event'.
185193selectViewListWithKey_
186194 :: forall t m k v a
187195 . (Adjustable t m, Ord k, PostBuild t m, MonadHold t m, MonadFix m)
src/Reflex/Dynamic.hs+6−2
@@ -17,8 +17,12 @@
1717#ifdef USE_REFLEX_OPTIMIZER
1818{-# OPTIONS_GHC -fplugin=Reflex.Optimizer #-}
1919#endif
20−-- | This module contains various functions for working with 'Dynamic' values.
21−-- 'Dynamic' and its primitives have been moved to the 'Reflex' class.
20+-- |
21+-- Module:
22+-- Reflex.Dynamic
23+-- Description:
24+-- This module contains various functions for working with 'Dynamic' values.
25+-- 'Dynamic' and its primitives have been moved to the 'Reflex' class.
2226module Reflex.Dynamic
2327 ( -- * Basics
2428 Dynamic -- Abstract so we can preserve the law that the current value is always equal to the most recent update
src/Reflex/FastWeak.hs+10−6
@@ -6,14 +6,18 @@
66{-# LANGUAGE JavaScriptFFI #-}
77#endif
88
9−-- | 'FastWeak' is a weak pointer to some value, and 'FastWeakTicket' ensures the value
10−-- referred to by a 'FastWeak' stays live while the ticket is held (live).
9+-- |
10+-- Module:
11+-- Reflex.FastWeak
12+-- Description:
13+-- 'FastWeak' is a weak pointer to some value, and 'FastWeakTicket' ensures the value
14+-- referred to by a 'FastWeak' stays live while the ticket is held (live).
1115--
12−-- On GHC or GHCJS when not built with the @fast-weak@ cabal flag, 'FastWeak' is a wrapper
13−-- around the simple version of 'System.Mem.Weak.Weak' where the key and value are the same.
16+-- On GHC or GHCJS when not built with the @fast-weak@ cabal flag, 'FastWeak' is a wrapper
17+-- around the simple version of 'System.Mem.Weak.Weak' where the key and value are the same.
1418--
15−-- On GHCJS when built with the @fast-weak@ cabal flag, 'FastWeak' is implemented directly
16−-- in JS using @h$FastWeak@ and @h$FastWeakTicket@ which are a nonstandard part of the GHCJS RTS.
19+-- On GHCJS when built with the @fast-weak@ cabal flag, 'FastWeak' is implemented directly
20+-- in JS using @h$FastWeak@ and @h$FastWeakTicket@ which are a nonstandard part of the GHCJS RTS.
1721module Reflex.FastWeak
1822 ( FastWeakTicket
1923 , FastWeak
src/Reflex/FunctorMaybe.hs+6−2
@@ -2,8 +2,12 @@
22{-# LANGUAGE GeneralizedNewtypeDeriving #-}
33{-# LANGUAGE StandaloneDeriving #-}
44
5−-- | This module defines the FunctorMaybe class, which extends Functors with the
6−-- ability to delete values.
5+-- |
6+-- Module:
7+-- Reflex.FunctorMaybe
8+-- Description:
9+-- This module defines the FunctorMaybe class, which extends Functors with the
10+-- ability to delete values.
711module Reflex.FunctorMaybe
812 ( FunctorMaybe (..)
913 ) where
src/Reflex/Network.hs+10−4
@@ -3,6 +3,11 @@
33#ifdef USE_REFLEX_OPTIMIZER
44{-# OPTIONS_GHC -fplugin=Reflex.Optimizer #-}
55#endif
6+-- |
7+-- Module:
8+-- Reflex.Network
9+-- Description:
10+-- This module provides combinators for building FRP graphs/networks and modifying them dynamically.
611module Reflex.Network
712 ( networkView
813 , networkHold
@@ -14,16 +19,17 @@ import Reflex.Adjustable.Class
1419import Reflex.NotReady.Class
1520import Reflex.PostBuild.Class
1621
17−-- | Given a Dynamic of network-creating actions, create a network that is recreated whenever the Dynamic updates.
18−-- The returned Event of network results occurs when the Dynamic does.
19−-- Note: Often, the type 'a' is an Event, in which case the return value is an Event-of-Events that would typically be flattened (via 'switchPromptly').
22+-- | A 'Dynamic' "network": Takes a 'Dynamic' of network-creating actions and replaces the network whenever the 'Dynamic' updates.
23+-- The returned Event of network results fires when the 'Dynamic' updates.
24+-- Note: Often, the type 'a' is an Event, in which case the return value is an Event-of-Events, where the outer 'Event' fires
25+-- when switching networks. Such an 'Event' would typically be flattened (via 'switchPromptly').
2026networkView :: (NotReady t m, Adjustable t m, PostBuild t m) => Dynamic t (m a) -> m (Event t a)
2127networkView child = do
2228 postBuild <- getPostBuild
2329 let newChild = leftmost [updated child, tagCheap (current child) postBuild]
2430 snd <$> runWithReplace notReady newChild
2531
26−-- | Given an initial network and an Event of network-creating actions, create a network that is recreated whenever the Event fires.
32+-- | Given an initial "network" and an 'Event' of network-creating actions, create a network that is recreated whenever the Event fires.
2733-- The returned Dynamic of network results occurs when the Event does.
2834-- Note: Often, the type 'a' is an Event, in which case the return value is a Dynamic-of-Events that would typically be flattened.
2935networkHold :: (Adjustable t m, MonadHold t m) => m a -> Event t (m a) -> m (Dynamic t a)
src/Reflex/Optimizer.hs+8−4
@@ -1,10 +1,14 @@
1−-- | This module provides a GHC plugin designed to improve code that uses
2−-- Reflex. Currently, it just adds an INLINABLE pragma to any top-level
3−-- definition that doesn't have an explicit inlining pragma. In the future,
4−-- additional optimizations are likely to be added.
51{-# LANGUAGE CPP #-}
62{-# LANGUAGE LambdaCase #-}
73{-# LANGUAGE OverloadedStrings #-}
4+-- |
5+-- Module:
6+-- Reflex.Optimizer
7+-- Description:
8+-- This module provides a GHC plugin designed to improve code that uses
9+-- Reflex. Currently, it just adds an INLINABLE pragma to any top-level
10+-- definition that doesn't have an explicit inlining pragma. In the future,
11+-- additional optimizations are likely to be added.
812module Reflex.Optimizer
913 ( plugin
1014 ) where
src/Reflex/Patch.hs+6−5
@@ -1,6 +1,10 @@
1−-- | This module defines the 'Patch' class, which is used by Reflex to manage
2−-- changes to 'Reflex.Class.Incremental' values.
31{-# LANGUAGE TypeFamilies #-}
2+-- |
3+-- Module:
4+-- Reflex.Patch
5+-- Description:
6+-- This module defines the 'Patch' class, which is used by Reflex to manage
7+-- changes to 'Reflex.Class.Incremental' values.
48module Reflex.Patch
59 ( module Reflex.Patch
610 , module X
@@ -17,11 +21,8 @@ import Reflex.Patch.Map as X
1721import Reflex.Patch.MapWithMove as X (PatchMapWithMove, patchMapWithMoveNewElements,
1822 patchMapWithMoveNewElementsMap, unPatchMapWithMove,
1923 unsafePatchMapWithMove)
20−
2124import Data.Semigroup (Semigroup (..), (<>))
2225
23−---- Patches based on commutative groups
24−
2526-- | A 'Group' is a 'Monoid' where every element has an inverse.
2627class (Semigroup q, Monoid q) => Group q where
2728 negateG :: q -> q
src/Reflex/Profiled.hs+6
@@ -8,6 +8,12 @@
88{-# LANGUAGE StandaloneDeriving #-}
99{-# LANGUAGE TypeFamilies #-}
1010{-# LANGUAGE UndecidableInstances #-}
11+-- |
12+-- Module:
13+-- Reflex.Profiled
14+-- Description:
15+-- This module contains an instance of the 'Reflex' class that provides
16+-- profiling/cost-center information.
1117module Reflex.Profiled where
1218
1319import Control.Lens hiding (children)
src/Reflex/Pure.hs+7−5
@@ -13,11 +13,13 @@
1313-- * MonadSample (Pure t) ((->) t)
1414-- * MonadHold (Pure t) ((->) t)
1515{-# OPTIONS_GHC -fno-warn-orphans #-}
16−
17−-- | This module provides a pure implementation of Reflex, which is intended to
18−-- serve as a reference for the semantics of the Reflex class. All
19−-- implementations of Reflex should produce the same results as this
20−-- implementation, although performance and laziness/strictness may differ.
16+-- |
17+-- Module: Reflex.Pure
18+-- Description:
19+-- This module provides a pure implementation of Reflex, which is intended to
20+-- serve as a reference for the semantics of the Reflex class. All
21+-- implementations of Reflex should produce the same results as this
22+-- implementation, although performance and laziness/strictness may differ.
2123module Reflex.Pure
2224 ( Pure
2325 , Behavior (..)
src/Reflex/Spider.hs+5−2
@@ -1,6 +1,9 @@
11{-# LANGUAGE CPP #-}
2−-- | This module exports all of the user-facing functionality of the 'Spider'
3−-- 'Reflex' engine
2+-- |
3+-- Module:
4+-- Reflex.Spider
5+-- Description:
6+-- This module exports all of the user-facing functionality of the 'Spider' 'Reflex' engine
47module Reflex.Spider
58 ( Spider
69 , SpiderTimeline
src/Reflex/Time.hs+23−13
@@ -11,6 +11,11 @@
1111#ifdef USE_TEMPLATE_HASKELL
1212{-# LANGUAGE TemplateHaskell #-}
1313#endif
14+-- |
15+-- Module:
16+-- Reflex.Time
17+-- Description:
18+-- Clocks, timers, and other time-related functions.
1419module Reflex.Time where
1520
1621import Reflex.Class
@@ -37,38 +42,39 @@ import Data.Typeable
3742import GHC.Generics (Generic)
3843import System.Random
3944
45+-- | Metadata associated with a timer "tick"
4046data TickInfo
4147 = TickInfo { _tickInfo_lastUTC :: UTCTime
4248 -- ^ UTC time immediately after the last tick.
4349 , _tickInfo_n :: Integer
44− -- ^ Number of time periods since t0
50+ -- ^ Number of time periods or ticks since the start of the timer
4551 , _tickInfo_alreadyElapsed :: NominalDiffTime
46− -- ^ Amount of time already elapsed in the current tick period.
52+ -- ^ Amount of time that has elapsed in the current tick period.
4753 }
4854 deriving (Eq, Ord, Show, Typeable)
4955
50−-- | Special case of 'tickLossyFrom' that uses the post-build event to start the
51−-- tick thread.
56+-- | Fires an 'Event' once every time provided interval elapses, approximately.
57+-- The provided 'UTCTime' is used bootstrap the determination of how much time has elapsed with each tick.
58+-- This is a special case of 'tickLossyFrom' that uses the post-build event to start the tick thread.
5259tickLossy :: (PostBuild t m, PerformEvent t m, TriggerEvent t m, MonadIO (Performable m), MonadFix m) => NominalDiffTime -> UTCTime -> m (Event t TickInfo)
5360tickLossy dt t0 = tickLossyFrom dt t0 =<< getPostBuild
5461
55−-- | Special case of 'tickLossyFrom' that uses the post-build event to start the
56−-- tick thread and the time of the post-build as the tick basis time.
62+-- | Fires an 'Event' once every time provided interval elapses, approximately.
63+-- This is a special case of 'tickLossyFrom' that uses the post-build event to start the tick thread and the time of the post-build as the tick basis time.
5764tickLossyFromPostBuildTime :: (PostBuild t m, PerformEvent t m, TriggerEvent t m, MonadIO (Performable m), MonadFix m) => NominalDiffTime -> m (Event t TickInfo)
5865tickLossyFromPostBuildTime dt = do
5966 postBuild <- getPostBuild
6067 postBuildTime <- performEvent $ liftIO getCurrentTime <$ postBuild
6168 tickLossyFrom' $ (dt,) <$> postBuildTime
6269
63−-- | Send events over time with the given basis time and interval
64−-- If the system starts running behind, occurrences will be dropped rather than buffered
65−-- Each occurrence of the resulting event will contain the index of the current interval, with 0 representing the basis time
70+-- | Fires an 'Event' approximately each time the provided interval elapses. If the system starts running behind, occurrences will be dropped rather than buffered.
71+-- Each occurrence of the resulting event will contain the index of the current interval, with 0 representing the provided initial time.
6672tickLossyFrom
6773 :: (PerformEvent t m, TriggerEvent t m, MonadIO (Performable m), MonadFix m)
6874 => NominalDiffTime
6975 -- ^ The length of a tick interval
7076 -> UTCTime
71− -- ^ The basis time from which intervals count
77+ -- ^ The basis time from which intervals count and with which the initial calculation of elapsed time will be made.
7278 -> Event t a
7379 -- ^ Event that starts a tick generation thread. Usually you want this to
7480 -- be something like the result of getPostBuild that only fires once. But
@@ -76,12 +82,12 @@ tickLossyFrom
7682 -> m (Event t TickInfo)
7783tickLossyFrom dt t0 e = tickLossyFrom' $ (dt, t0) <$ e
7884
79−-- | Generalization of tickLossyFrom that takes dt and t0 in the event.
85+-- | Generalization of tickLossyFrom that takes the delay and initial time as an 'Event'.
8086tickLossyFrom'
8187 :: (PerformEvent t m, TriggerEvent t m, MonadIO (Performable m), MonadFix m)
8288 => Event t (NominalDiffTime, UTCTime)
8389 -- ^ Event that starts a tick generation thread. Usually you want this to
84− -- be something like the result of getPostBuild that only fires once. But
90+ -- be something like the result of 'getPostBuild' that only fires once. But
8591 -- there could be uses for starting multiple timer threads.
8692 -> m (Event t TickInfo)
8793tickLossyFrom' e = do
@@ -92,12 +98,16 @@ tickLossyFrom' e = do
9298 Concurrent.delay $ ceiling $ (fst pair - _tickInfo_alreadyElapsed tick) * 1000000
9399 cb (tick, pair)
94100
101+-- | Like 'tickLossy', but immediately calculates the first tick and provides a 'Dynamic' that is updated as ticks fire.
95102clockLossy :: (MonadIO m, PerformEvent t m, TriggerEvent t m, MonadIO (Performable m), PostBuild t m, MonadHold t m, MonadFix m) => NominalDiffTime -> UTCTime -> m (Dynamic t TickInfo)
96103clockLossy dt t0 = do
97104 initial <- liftIO $ getCurrentTick dt t0
98105 e <- tickLossy dt t0
99106 holdDyn initial e
100107
108+-- | Generates a 'TickInfo', given the specified interval and timestamp. The 'TickInfo' will include the
109+-- current time, the number of ticks that have elapsed since the timestamp, and the amount of time that
110+-- has elapsed since the start time of this tick.
101111getCurrentTick :: NominalDiffTime -> UTCTime -> IO TickInfo
102112getCurrentTick dt t0 = do
103113 t <- getCurrentTime
@@ -278,7 +288,7 @@ data ThrottleState b
278288
279289data ThrottleBuffer b
280290 = ThrottleBuffer_Empty -- Empty conflicts with lens, and hiding it would require turning
281− -- on PatternSynonyms
291+ -- on PatternSynonyms
282292 | ThrottleBuffer_Full b
283293 deriving (Eq, Ord, Show, Functor, Foldable, Traversable, Generic, Data, Typeable)
284294
src/Reflex/Workflow.hs+13−1
@@ -1,7 +1,13 @@
11{-# LANGUAGE RecursiveDo #-}
22{-# LANGUAGE ScopedTypeVariables #-}
3+-- |
4+-- Module:
5+-- Reflex.Workflow
6+-- Description:
7+-- Provides a convenient way to describe a series of interrelated widgets that
8+-- can send data to, invoke, and replace one another. Useful for modeling user interface
9+-- "workflows."
310module Reflex.Workflow (
4− -- * Workflows
511 Workflow (..)
612 , workflow
713 , workflowView
@@ -18,21 +24,27 @@ import Reflex.Network
1824import Reflex.NotReady.Class
1925import Reflex.PostBuild.Class
2026
27+-- | A widget in a workflow
28+-- When the 'Event' returned by a 'Workflow' fires, the current 'Workflow' is replaced by the one inside the firing 'Event'. A series of 'Workflow's must share the same return type.
2129newtype Workflow t m a = Workflow { unWorkflow :: m (a, Event t (Workflow t m a)) }
2230
31+-- | Runs a 'Workflow' and returns the 'Dynamic' result of the 'Workflow' (i.e., a 'Dynamic' of the value produced by the current 'Workflow' node, and whose update 'Event' fires whenever one 'Workflow' is replaced by another).
2332workflow :: forall t m a. (Reflex t, Adjustable t m, MonadFix m, MonadHold t m) => Workflow t m a -> m (Dynamic t a)
2433workflow w0 = do
2534 rec eResult <- networkHold (unWorkflow w0) $ fmap unWorkflow $ switch $ snd <$> current eResult
2635 return $ fmap fst eResult
2736
37+-- | Similar to 'workflow', but outputs an 'Event' that fires whenever the current 'Workflow' is replaced by the next 'Workflow'.
2838workflowView :: forall t m a. (Reflex t, NotReady t m, Adjustable t m, MonadFix m, MonadHold t m, PostBuild t m) => Workflow t m a -> m (Event t a)
2939workflowView w0 = do
3040 rec eResult <- networkView . fmap unWorkflow =<< holdDyn w0 eReplace
3141 eReplace <- fmap switch $ hold never $ fmap snd eResult
3242 return $ fmap fst eResult
3343
44+-- | Map a function over a 'Workflow', possibly changing the resturn type.
3445mapWorkflow :: (Reflex t, Functor m) => (a -> b) -> Workflow t m a -> Workflow t m b
3546mapWorkflow f (Workflow x) = Workflow (fmap (f *** fmap (mapWorkflow f)) x)
3647
48+-- | Map a "cheap" function over a 'Workflow'. Refer to the documentation for 'pushCheap' for more information and performance considerations.
3749mapWorkflowCheap :: (Reflex t, Functor m) => (a -> b) -> Workflow t m a -> Workflow t m b
3850mapWorkflowCheap f (Workflow x) = Workflow (fmap (f *** fmapCheap (mapWorkflowCheap f)) x)