@@ -83,7 +83,7 @@ instance Reflex t => Functor (Behavior t) where
8383 fmap f = pull . liftM f . sample
8484
8585--TODO: See if there's a better class in the standard libraries already
86−-- | A class for values that combined filtering and mapping using 'Maybe'.
86+-- | A class for values that combines filtering and mapping using 'Maybe'.
8787class FunctorMaybe f where
8888 -- | Combined mapping and filtering function.
8989 fmapMaybe :: (a -> Maybe b) -> f a -> f b
@@ -104,7 +104,8 @@ instance Reflex t => Functor (Event t) where
104104 fmap f = fmapMaybe $ Just . f
105105
106106-- | Create a new 'Event' by combining each occurence with the next value
107−-- of the list using the supplied function. Blocks 'Event' when the list is empty.
107+-- of the list using the supplied function. If the list runs out of items,
108+-- all subsequent 'Event' occurrences will be ignored.
108109zipListWithEvent :: (Reflex t, MonadHold t m, MonadFix m) => (a -> b -> c) -> [a] -> Event t b -> m (Event t c)
109110zipListWithEvent f l e = do
110111 rec lb <- hold l eTail
@@ -117,26 +118,26 @@ zipListWithEvent f l e = do
117118 lb `seq` eBoth `seq` eTail `seq` return ()
118119 return $ fmap fst eBoth
119120
120−-- | Replace the occurrence value of the 'Event' with the value of the
121−-- 'Behavior' at the time of the occurrence.
121+-- | Replace each occurrence value of the 'Event' with the value of the
122+-- 'Behavior' at the time of that occurrence.
122123tag :: Reflex t => Behavior t b -> Event t a -> Event t b
123124tag b = pushAlways $ \_ -> sample b
124125
125−-- | Create a new 'Event' by combining each occurence with the current
126−-- value of the 'Behavior'. Doesn't occur if the combining function
127−-- returns Nothing
128−attachWithMaybe :: Reflex t => (a -> b -> Maybe c) -> Behavior t a -> Event t b -> Event t c
129−attachWithMaybe f b e = flip push e $ \o -> liftM (flip f o) $ sample b
126+-- | Create a new 'Event' that combines occurences of supplied 'Event'
127+-- with the current value of the 'Behavior'.
128+attach :: Reflex t => Behavior t a -> Event t b -> Event t (a, b)
129+attach = attachWith (,)
130130
131131-- | Create a new 'Event' that occurs when the supplied 'Event' occurs
132132-- by combining it with the current value of the 'Behavior'.
133133attachWith :: Reflex t => (a -> b -> c) -> Behavior t a -> Event t b -> Event t c
134134attachWith f = attachWithMaybe $ \a b -> Just $ f a b
135135
136−-- | Create a new 'Event' that combines occurences of supplied 'Event'
137−-- with the current value of the 'Behavior'.
138−attach :: Reflex t => Behavior t a -> Event t b -> Event t (a, b)
139−attach = attachWith (,)
136+-- | Create a new 'Event' by combining each occurence with the current
137+-- value of the 'Behavior'. The occurrence is discarded if the combining function
138+-- returns Nothing
139+attachWithMaybe :: Reflex t => (a -> b -> Maybe c) -> Behavior t a -> Event t b -> Event t c
140+attachWithMaybe f b e = flip push e $ \o -> liftM (flip f o) $ sample b
140141
141142-- | Alias for 'headE'
142143onceE :: (Reflex t, MonadHold t m, MonadFix m) => Event t a -> m (Event t a)
@@ -172,11 +173,17 @@ splitE e = (fmap fst e, fmap snd e)
172173
173174-- | Print the supplied 'String' and the value of the 'Event' on each
174175-- occurence. This should /only/ be used for debugging.
176+--
177+-- Note: As with Debug.Trace.trace, the message will only be printed if
178+-- the 'Event' is actually used.
175179traceEvent :: (Reflex t, Show a) => String -> Event t a -> Event t a
176180traceEvent s = traceEventWith $ \x -> s <> ": " <> show x
177181
178182-- | Print the output of the supplied function on each occurence of
179183-- the 'Event'. This should /only/ be used for debugging.
184+--
185+-- Note: As with Debug.Trace.trace, the message will only be printed if
186+-- the 'Event' is actually used.
180187traceEventWith :: Reflex t => (a -> String) -> Event t a -> Event t a
181188traceEventWith f = push $ \x -> trace (f x) $ return $ Just x
182189
@@ -234,7 +241,7 @@ dmapToThese m = case (DMap.lookup LeftTag m, DMap.lookup RightTag m) of
234241appendEvents :: (Reflex t, Monoid a) => Event t a -> Event t a -> Event t a
235242appendEvents e1 e2 = fmap (mergeThese mappend) $ align e1 e2
236243
237−{-# DEPRECATED sequenceThese "Use bisequenceA from the bifunctors package instead" #-}
244+{-# DEPRECATED sequenceThese "Use bisequenceA or bisequence from the bifunctors package instead" #-}
238245sequenceThese :: Monad m => These (m a) (m b) -> m (These a b)
239246sequenceThese t = case t of
240247 This ma -> liftM This ma
@@ -248,7 +255,7 @@ instance (Semigroup a, Reflex t) => Monoid (Event t a) where
248255
249256-- | Create a new 'Event' that occurs if at least one of the 'Event's
250257-- in the list occurs. If multiple occur at the same time they are
251−-- folded from the left.
258+-- folded from the left with the given function.
252259mergeWith :: Reflex t => (a -> a -> a) -> [Event t a] -> Event t a
253260mergeWith f es = fmap (Prelude.foldl1 f . map (\(Const2 _ :=> v) -> v) . DMap.toList) $ merge $ DMap.fromList $ map (\(k, v) -> WrapArg (Const2 k) :=> v) $ zip [0 :: Int ..] es
254261