@@ -82,6 +82,8 @@ module Reflex.Class
8282 , zipListWithEvent
8383 , numberOccurrences
8484 , numberOccurrencesFrom
85+ , (<@>)
86+ , (<@)
8587 , headE
8688 , tailE
8789 , headTailE
@@ -926,6 +928,74 @@ numberOccurrences = numberOccurrencesFrom 0
926928numberOccurrencesFrom :: (Reflex t, MonadHold t m, MonadFix m, Num b) => b -> Event t a -> m (Event t (b, a))
927929numberOccurrencesFrom = mapAccum_ (\n a -> (n + 1, (n, a)))
928930
931+-- | This is used to sample the value of a 'Behavior' using an 'Event'.
932+--
933+-- The '<@>' operator is intended to be used in conjunction with
934+-- the 'Applicative' instance for 'Behavior'.
935+--
936+-- This is useful when we want to combine the values of one 'Event' and
937+-- the value of several 'Behavior's at the time the 'Event' is firing.
938+--
939+-- If we have:
940+--
941+-- > f :: a -> b -> c -> d
942+-- > b1 :: Behavior t a
943+-- > b2 :: Behavior t b
944+-- > e :: Event t c
945+--
946+-- then we can do:
947+--
948+-- > f <$> b1 <*> b2 <@> e :: Event t d
949+--
950+-- in order to apply the function 'f' to the relevant values.
951+--
952+-- The alternative would be something like:
953+--
954+-- > attachWith (\(x1, x2) y -> f x1 x2 y) ((,) <$> b1 <*> b2) e :: Event t d
955+--
956+-- or a variation involing a custom data type to hold the combination of
957+-- 'Behavior's even when that combination might only ever be used by 'f'.
958+--
959+-- A more suggestive example might be:
960+--
961+-- > handleMouse <$> bPlayerState <*> bMousePosition <@> eMouseClick :: Event t (GameState -> GameState)
962+--
963+(<@>) :: Reflex t => Behavior t (a -> b) -> Event t a -> Event t b
964+(<@>) b = push $ \x -> do
965+ f <- sample b
966+ return . Just . f $ x
967+infixl 4 <@>
968+
969+-- | An version of '<@>' that does not use the value of the 'Event'.
970+--
971+-- Alternatively, it is 'tag' in operator form.
972+--
973+-- This is useful when we want to combine the values of several
974+-- 'Behavior's at particular points in time using an 'Applicative'
975+-- style syntax.
976+--
977+-- If we have:
978+--
979+-- > g :: a -> b -> d
980+-- > b1 :: Behavior t a
981+-- > b2 :: Behavior t b
982+-- > e :: Event t c
983+--
984+-- where 'e' is firing at the points in time of interest.
985+--
986+-- Then we can use '<@':
987+--
988+-- > g <$> b1 <*> b2 <@ e :: Event t d
989+--
990+-- to combine the values of 'b1' and 'b2' at each of those points of time,
991+-- with the function 'g' being used to combine the values.
992+--
993+-- This is the same as '<@>' except that the 'Event' is being used only
994+-- to act as a trigger.
995+(<@) :: (Reflex t) => Behavior t b -> Event t a -> Event t b
996+(<@) = tag
997+infixl 4 <@
998+
929999-- | A 'Monad' that supports adjustment over time. After an action has been
9301000-- run, if the given events fire, it will adjust itself so that its net effect
9311001-- is as though it had originally been run with the new value. Note that there