@@ -1,12 +1,24 @@
11
2+-- The library for general signal manipulation. Some useful functions for
3+-- working with time (e.g. setting FPS) and combining signals and time (e.g.
4+-- delaying updates, getting timestamps) can be found in the
5+-- [`Time`](/docs/Signal/Time.elm) library.
6+--
7+-- Note: There are lift functions up to `lift8`.
28module Signal where
39
410import Native.Signal as Native
511
12+-- Create a constant signal that never changes.
613constant : a -> Signal a
714
15+-- Transform a signal with a given function.
816lift : (a -> b) -> Signal a -> Signal b
17+
18+-- Combine two signals with a given function.
919lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c
20+
21+-- Combine three signals with a given function.
1022lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d
1123lift4 : (a -> b -> c -> d -> e) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e
1224lift5 : (a -> b -> c -> d -> e -> f) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f
@@ -14,21 +26,98 @@ lift6 : (a -> b -> c -> d -> e -> f -> g) -> Signal a -> Signal b -> Signal c ->
1426lift7 : (a -> b -> c -> d -> e -> f -> g -> h) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h
1527lift8 : (a -> b -> c -> d -> e -> f -> g -> h -> i) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h -> Signal i
1628
29+-- Create a past-dependent signal. Each value given on the input signal will
30+-- be accumulated, producing a new output value.
31+--
32+-- For instance, `(foldp (\\t acc -> acc + 1) 0 (Time.every second))` increments every second.
1733foldp : (a -> b -> b) -> b -> Signal a -> Signal b
1834
35+-- Merge two signals into one, biased towards the first signal if both signals
36+-- update at the same time.
1937merge : Signal a -> Signal a -> Signal a
38+
39+-- Merge many signals into one, biased towards the left-most signal if multiple
40+-- signals update simultaneously.
2041merges : [Signal a] -> Signal a
42+
43+-- Merge two signals into one, but distinguishing the values by marking the first
44+-- signal as `Left` and the second signal as `Right`. This allows you to easily
45+-- fold over non-homogeneous inputs.
2146mergeEither : Signal a -> Signal b -> Signal (Either a b)
2247
48+-- Count the number of events that have occured.
2349count : Signal a -> Signal Int
50+
51+-- Count the number of events that have occured that satisfy a given predicate.
2452countIf : (a -> Bool) -> Signal a -> Signal Int
2553
54+-- Keep only events that satisfy the given predicate. Elm does not allow
55+-- undefined signals, so a base case must be provided in case the predicate is
56+-- never satisfied.
2657keepIf : (a -> Bool) -> a -> Signal a -> Signal a
58+
59+-- Drop events that satisfy the given predicate. Elm does not allow undefined
60+-- signals, so a base case must be provided in case the predicate is never
61+-- satisfied.
2762dropIf : (a -> Bool) -> a -> Signal a -> Signal a
63+
64+-- Keep events only when the first signal is true. When the first signal becomes
65+-- true, the most recent value of the second signal will be propagated. Until
66+-- the first signal becomes false again, all events will be propagated. Elm does
67+-- not allow undefined signals, so a base case must be provided in case the first
68+-- signal is never true.
2869keepWhen : Signal Bool -> a -> Signal a -> Signal a
70+
71+-- Drop events when the first signal is true. When the first signal becomes false,
72+-- the most recent value of the second signal will be propagated. Until the first
73+-- signal becomes true again, all events will be propagated. Elm does not allow
74+-- undefined signals, so a base case must be provided in case the first signal is
75+-- always true.
2976dropWhen : Signal Bool -> a -> Signal a -> Signal a
77+
78+-- Drop sequential repeated values. For example, if a signal produces the
79+-- sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that
80+-- are the same as the previous value.
3081dropRepeats : Signal a -> Signal a
3182
83+-- Sample from the second input every time an event occurs on the first input.
84+-- For example, `(sampleOn clicks (every second))` will give the approximate
85+-- time of the latest click.
3286sampleOn : Signal a -> Signal b -> Signal b
3387
34−timestamp : Signal a -> Signal (Time, a)
88+-- Add a timestamp to any signal. Timestamps increase monotonically. Each timestamp is
89+-- related to a specfic event, so `Mouse.x` and `Mouse.y` will always have the same
90+-- timestamp because they both rely on the same underlying event.
91+timestamp : Signal a -> Signal (Time, a)
92+
93+-- Delay a signal by a certain amount of time. So `(delay second Mouse.clicks)`
94+-- will update one second later than any mouse click.
95+delay : Time -> Signal a -> Signal a
96+
97+{-- TODO: only found in docs
98+ , ("average", "Int -> Signal Number -> Signal Float", [markdown|
99+
100+Takes an integer `n` and a signal of numbers. Computes the running
101+average of the signal over the last `n` events.
102+
103+So `(average 20 (fps 40))` would be the average time between the frames for
104+the last 20 frames.|])
105+ , ("foldp1", "(a -> a -> a) -> Signal a -> Signal a", [markdown|
106+Create a past-dependent signal. The first value on the signal is used
107+as the base case.|])
108+ , ("foldp'", "(a -> b -> b) -> (a -> b) -> Signal a -> Signal b", [markdown|
109+Just like foldp, but instead of a base case, you provide a function to be
110+applied to the first value, creating the base case.|])
111+ [ ("(<~)", "(a -> b) -> Signal a -> Signal b", [markdown|
112+An alias for `lift`. A prettier way to apply a
113+function to the current value of a signal.|])
114+ , ("(~)", "Signal (a -> b) -> Signal a -> Signal b", [markdown|
115+Signal application. This takes two signals, holding a function and
116+a value. It applies the current function to the current value.
117+
118+So the following expressions are equivalent:
119+
120+ scene <~ Mouse.x ~ Mouse.y
121+ lift2 scene Mouse.x Mouse.y|])
122+--}
123+