git.iko.soy/elk
on 4bec310 help sign in
elk/libraries/Signal.elm
170 lines 6.1 kB history raw
1module Signal where
2{-| The library for general signal manipulation. Includes lift functions up to
3`lift8` and infix lift operators `<~` and `~`, combinations, filters, and
4past-dependence.
6Signals are time-varying values. Lifted functions are reevaluated whenever any of
7their input signals has an event. Signal events may be of the same value as the
8previous value of the signal. Such signals are useful for timing and
9past-dependence.
11Some useful functions for working with time (e.g. setting FPS) and combining
12signals and time (e.g. delaying updates, getting timestamps) can be found in
13the `Time` library.
15# Combine
16@docs constant, lift, lift2, merge, merges, combine
18# Past-Dependence
19@docs foldp, count, countIf
21#Filters
22@docs keepIf, dropIf, keepWhen, dropWhen, dropRepeats, sampleOn
24# Pretty Lift
25@docs (<~), (~)
27# Do you even lift?
28@docs lift3, lift4, lift5, lift6, lift7, lift8
30-}
32import Native.Signal
33import List (foldr)
34import Basics (fst, snd, not)
36data Signal a = Signal
38{-| Create a constant signal that never changes. -}
39constant : a -> Signal a
40constant = Native.Signal.constant
42{-| Transform a signal with a given function. -}
43lift : (a -> b) -> Signal a -> Signal b
44lift = Native.Signal.lift
46{-| Combine two signals with a given function. -}
47lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c
48lift2 = Native.Signal.lift2
50lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d
51lift3 = Native.Signal.lift3
53lift4 : (a -> b -> c -> d -> e) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e
54lift4 = Native.Signal.lift4
56lift5 : (a -> b -> c -> d -> e -> f) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f
57lift5 = Native.Signal.lift5
59lift6 : (a -> b -> c -> d -> e -> f -> g)
60 -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g
61lift6 = Native.Signal.lift6
63lift7 : (a -> b -> c -> d -> e -> f -> g -> h)
64 -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h
65lift7 = Native.Signal.lift7
67lift8 : (a -> b -> c -> d -> e -> f -> g -> h -> i)
68 -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h -> Signal i
69lift8 = Native.Signal.lift8
72{-| Create a past-dependent signal. Each value given on the input signal will
73be accumulated, producing a new output value.
75For instance, `foldp (+) 0 (fps 40)` is the time the program has been running,
76updated 40 times a second. -}
77foldp : (a -> b -> b) -> b -> Signal a -> Signal b
78foldp = Native.Signal.foldp
80{-| Merge two signals into one, biased towards the first signal if both signals
81update at the same time. -}
82merge : Signal a -> Signal a -> Signal a
83merge = Native.Signal.merge
85{-| Merge many signals into one, biased towards the left-most signal if multiple
86signals update simultaneously. -}
87merges : [Signal a] -> Signal a
88merges = Native.Signal.merges
90{-| Combine a list of signals into a signal of lists. -}
91combine : [Signal a] -> Signal [a]
92combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
94 -- Merge two signals into one, but distinguishing the values by marking the first
95 -- signal as `Left` and the second signal as `Right`. This allows you to easily
96 -- fold over non-homogeneous inputs.
97 -- mergeEither : Signal a -> Signal b -> Signal (Either a b)
99{-| Count the number of events that have occurred. -}
100count : Signal a -> Signal Int
101count = Native.Signal.count
103{-| Count the number of events that have occurred that satisfy a given predicate.
104-}
105countIf : (a -> Bool) -> Signal a -> Signal Int
106countIf = Native.Signal.countIf
108{-| Keep only events that satisfy the given predicate. Elm does not allow
109undefined signals, so a base case must be provided in case the predicate is
110not satisfied initially. -}
111keepIf : (a -> Bool) -> a -> Signal a -> Signal a
112keepIf = Native.Signal.keepIf
114{-| Drop events that satisfy the given predicate. Elm does not allow undefined
115signals, so a base case must be provided in case the predicate is satisfied
116initially. -}
117dropIf : (a -> Bool) -> a -> Signal a -> Signal a
118dropIf = Native.Signal.dropIf
120{-| Keep events only when the first signal is true. Elm does not allow undefined
121signals, so a base case must be provided in case the first signal is not true
122initially.
123-}
124keepWhen : Signal Bool -> a -> Signal a -> Signal a
125keepWhen bs def sig =
126 snd <~ (keepIf fst (False, def) ((,) <~ (sampleOn sig bs) ~ sig))
128{-| Drop events when the first signal is true. Elm does not allow undefined
129signals, so a base case must be provided in case the first signal is true
130initially.
131-}
132dropWhen : Signal Bool -> a -> Signal a -> Signal a
133dropWhen bs = keepWhen (not <~ bs)
135{-| Drop updates that repeat the current value of the signal.
137Imagine a signal `numbers` has initial value
1380 and then updates with values 0, 0, 1, 1, and 2. `dropRepeats numbers`
139is a signal that has initial value 0 and updates as follows: ignore 0,
140ignore 0, update to 1, ignore 1, update to 2. -}
141dropRepeats : Signal a -> Signal a
142dropRepeats = Native.Signal.dropRepeats
144{-| Sample from the second input every time an event occurs on the first input.
145For example, `(sampleOn clicks (every second))` will give the approximate time
146of the latest click. -}
147sampleOn : Signal a -> Signal b -> Signal b
148sampleOn = Native.Signal.sampleOn
150{-| An alias for `lift`. A prettier way to apply a function to the current value
151of a signal. -}
152(<~) : (a -> b) -> Signal a -> Signal b
153f <~ s = Native.Signal.lift f s
155{-| Informally, an alias for `liftN`. Intersperse it between additional signal
156arguments of the lifted function.
158Formally, signal application. This takes two signals, holding a function and
159a value. It applies the current function to the current value.
161The following expressions are equivalent:
163 scene <~ Window.dimensions ~ Mouse.position
164 lift2 scene Window.dimensions Mouse.position
165-}
166(~) : Signal (a -> b) -> Signal a -> Signal b
167sf ~ s = Native.Signal.lift2 (\f x -> f x) sf s
169infixl 4 <~
170infixl 4 ~