git.iko.soy/elk
on 63243ca help sign in
elk/libraries/Signal.elm
167 lines 6.2 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`](/docs/Signal/Time.elm) 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)
35data Signal a = Signal
37{-| Create a constant signal that never changes. -}
38constant : a -> Signal a
39constant = Native.Signal.constant
41{-| Transform a signal with a given function. -}
42lift : (a -> b) -> Signal a -> Signal b
43lift = Native.Signal.lift
45{-| Combine two signals with a given function. -}
46lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c
47lift2 = Native.Signal.lift2
49lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d
50lift3 = Native.Signal.lift3
52lift4 : (a -> b -> c -> d -> e) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e
53lift4 = Native.Signal.lift4
55lift5 : (a -> b -> c -> d -> e -> f) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f
56lift5 = Native.Signal.lift5
58lift6 : (a -> b -> c -> d -> e -> f -> g)
59 -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g
60lift6 = Native.Signal.lift6
62lift7 : (a -> b -> c -> d -> e -> f -> g -> h)
63 -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h
64lift7 = Native.Signal.lift7
66lift8 : (a -> b -> c -> d -> e -> f -> g -> h -> i)
67 -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h -> Signal i
68lift8 = Native.Signal.lift8
71{-| Create a past-dependent signal. Each value given on the input signal will
72be accumulated, producing a new output value.
74For instance, `foldp (+) 0 (fps 40)` is the time the program has been running,
75updated 40 times a second. -}
76foldp : (a -> b -> b) -> b -> Signal a -> Signal b
77foldp = Native.Signal.foldp
79{-| Merge two signals into one, biased towards the first signal if both signals
80update at the same time. -}
81merge : Signal a -> Signal a -> Signal a
82merge = Native.Signal.merge
84{-| Merge many signals into one, biased towards the left-most signal if multiple
85signals update simultaneously. -}
86merges : [Signal a] -> Signal a
87merges = Native.Signal.merges
89{-| Combine a list of signals into a signal of lists. -}
90combine : [Signal a] -> Signal [a]
91combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
93 -- Merge two signals into one, but distinguishing the values by marking the first
94 -- signal as `Left` and the second signal as `Right`. This allows you to easily
95 -- fold over non-homogeneous inputs.
96 -- mergeEither : Signal a -> Signal b -> Signal (Either a b)
98{-| Count the number of events that have occurred. -}
99count : Signal a -> Signal Int
100count = Native.Signal.count
102{-| Count the number of events that have occurred that satisfy a given predicate.
103-}
104countIf : (a -> Bool) -> Signal a -> Signal Int
105countIf = Native.Signal.countIf
107{-| Keep only events that satisfy the given predicate. Elm does not allow
108undefined signals, so a base case must be provided in case the predicate is
109never satisfied. -}
110keepIf : (a -> Bool) -> a -> Signal a -> Signal a
111keepIf = Native.Signal.keepIf
113{-| Drop events that satisfy the given predicate. Elm does not allow undefined
114signals, so a base case must be provided in case the predicate is never
115satisfied. -}
116dropIf : (a -> Bool) -> a -> Signal a -> Signal a
117dropIf = Native.Signal.dropIf
119{-| Keep events only when the first signal is true. When the first signal
120becomes true, the most recent value of the second signal will be propagated.
121Until the first signal becomes false again, all events will be propagated. Elm
122does not allow undefined signals, so a base case must be provided in case the
123first signal is never true. -}
124keepWhen : Signal Bool -> a -> Signal a -> Signal a
125keepWhen = Native.Signal.keepWhen
127{-| Drop events when the first signal is true. When the first signal becomes
128false, the most recent value of the second signal will be propagated. Until the
129first signal becomes true again, all events will be propagated. Elm does not
130allow undefined signals, so a base case must be provided in case the first
131signal is always true. -}
132dropWhen : Signal Bool -> a -> Signal a -> Signal a
133dropWhen = Native.Signal.dropWhen
135{-| Drop sequential repeated values. For example, if a signal produces the
136sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that are the
137same as the previous value. -}
138dropRepeats : Signal a -> Signal a
139dropRepeats = Native.Signal.dropRepeats
141{-| Sample from the second input every time an event occurs on the first input.
142For example, `(sampleOn clicks (every second))` will give the approximate time
143of the latest click. -}
144sampleOn : Signal a -> Signal b -> Signal b
145sampleOn = Native.Signal.sampleOn
147{-| An alias for `lift`. A prettier way to apply a function to the current value
148of a signal. -}
149(<~) : (a -> b) -> Signal a -> Signal b
150f <~ s = Native.Signal.lift f s
152{-| Informally, an alias for `liftN`. Intersperse it between additional signal
153arguments of the lifted function.
155Formally, signal application. This takes two signals, holding a function and
156a value. It applies the current function to the current value.
158The following expressions are equivalent:
160 scene <~ Window.dimensions ~ Mouse.position
161 lift2 scene Window.dimensions Mouse.position
162-}
163(~) : Signal (a -> b) -> Signal a -> Signal b
164sf ~ s = Native.Signal.lift2 (\f x -> f x) sf s
166infixl 4 <~
167infixl 4 ~