@@ -1,32 +1,52 @@
2−-- The library for general signal manipulation. Some useful functions for
2+{-| The library for general signal manipulation. Includes lift functions up to
3+`lift8` and infix lift operators `<~` and `~`, combinations, filters, and
6+Signals are time-varying values. Lifted functions are reevaluated whenver any of
7+their input signals has an event. Signal events may be of the same value as the
8+previous value of the signal. Such signals are useful for timing and
3−-- working with time (e.g. setting FPS) and combining signals and time (e.g.
11+Some useful functions for working with time (e.g. setting FPS) and combining
4−-- delaying updates, getting timestamps) can be found in the
12+signals and time (e.g. delaying updates, getting timestamps) can be found in
5−-- [`Time`](/docs/Signal/Time.elm) library.
13+the [`Time`](/docs/Signal/Time.elm) library.
7−-- Note: There are lift functions up to `lift8`.
15+# Combine
16+@docs constant, lift, lift2, merge, merges, combine
22+@docs foldp, count, countIf
25+@docs keepIf, dropIf, keepWhen, dropWhen, dropRepeats, sampleOn
28+@docs lift3, lift4, lift5, lift6, lift7, lift8
8module Signal where
31module Signal where
10import Native.Signal
33import Native.Signal
11import List (foldr)
34import List (foldr)
13data Signal a = Signal
36data Signal a = Signal
15−-- | Lift (a -> a) (Signal a)
17−-- Create a constant signal that never changes.
38+{-| Create a constant signal that never changes. -}
18constant : a -> Signal a
39constant : a -> Signal a
19constant = Native.Signal.constant
40constant = Native.Signal.constant
21−-- Transform a signal with a given function.
42+{-| Transform a signal with a given function. -}
22lift : (a -> b) -> Signal a -> Signal b
43lift : (a -> b) -> Signal a -> Signal b
23lift = Native.Signal.lift
44lift = Native.Signal.lift
25−-- Combine two signals with a given function.
46+{-| Combine two signals with a given function. -}
26lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c
47lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c
27lift2 = Native.Signal.lift2
48lift2 = Native.Signal.lift2
29−-- Combine three signals with a given function.
30lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d
50lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d
31lift3 = Native.Signal.lift3
51lift3 = Native.Signal.lift3
@@ -49,25 +69,25 @@ lift8 : (a -> b -> c -> d -> e -> f -> g -> h -> i)
49lift8 = Native.Signal.lift8
69lift8 = Native.Signal.lift8
52−-- Create a past-dependent signal. Each value given on the input signal will
72+{-| Create a past-dependent signal. Each value given on the input signal will
53−-- be accumulated, producing a new output value.
73+be accumulated, producing a new output value.
55−-- For instance, `(foldp (\\arrows number -> number + arrows.y) 0 Keyboard.arrows)`
75+For instance, `foldp (+) 0 (fps 40)` is the time the program has been running,
56−-- increments or decrements the accumulated value (which starts at zero) when the up or down arrow keys are pressed.
76+updated 40 times a second. -}
57foldp : (a -> b -> b) -> b -> Signal a -> Signal b
77foldp : (a -> b -> b) -> b -> Signal a -> Signal b
58foldp = Native.Signal.foldp
78foldp = Native.Signal.foldp
60−-- Merge two signals into one, biased towards the first signal if both signals
80+{-| Merge two signals into one, biased towards the first signal if both signals
61−-- update at the same time.
81+update at the same time. -}
62merge : Signal a -> Signal a -> Signal a
82merge : Signal a -> Signal a -> Signal a
63merge = Native.Signal.merge
83merge = Native.Signal.merge
65−-- Merge many signals into one, biased towards the left-most signal if multiple
85+{-| Merge many signals into one, biased towards the left-most signal if multiple
66−-- signals update simultaneously.
86+signals update simultaneously. -}
67merges : [Signal a] -> Signal a
87merges : [Signal a] -> Signal a
68merges = Native.Signal.merges
88merges = Native.Signal.merges
70−-- Combine a list of signals into a signal of lists.
90+{-| Combine a list of signals into a signal of lists. -}
71combine : [Signal a] -> Signal [a]
91combine : [Signal a] -> Signal [a]
72combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
92combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
@@ -76,70 +96,74 @@ combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
76 -- fold over non-homogeneous inputs.
96 -- fold over non-homogeneous inputs.
77 -- mergeEither : Signal a -> Signal b -> Signal (Either a b)
97 -- mergeEither : Signal a -> Signal b -> Signal (Either a b)
79−-- Count the number of events that have occured.
99+{-| Count the number of events that have occured. -}
80count : Signal a -> Signal Int
100count : Signal a -> Signal Int
81count = Native.Signal.count
101count = Native.Signal.count
83−-- Count the number of events that have occured that satisfy a given predicate.
103+{-| Count the number of events that have occured that satisfy a given predicate.
84countIf : (a -> Bool) -> Signal a -> Signal Int
105countIf : (a -> Bool) -> Signal a -> Signal Int
85countIf = Native.Signal.countIf
106countIf = Native.Signal.countIf
87−-- Keep only events that satisfy the given predicate. Elm does not allow
108+{-| Keep only events that satisfy the given predicate. Elm does not allow
88−-- undefined signals, so a base case must be provided in case the predicate is
109+undefined signals, so a base case must be provided in case the predicate is
89−-- never satisfied.
110+never satisfied. -}
90keepIf : (a -> Bool) -> a -> Signal a -> Signal a
111keepIf : (a -> Bool) -> a -> Signal a -> Signal a
91keepIf = Native.Signal.keepIf
112keepIf = Native.Signal.keepIf
93−-- Drop events that satisfy the given predicate. Elm does not allow undefined
114+{-| Drop events that satisfy the given predicate. Elm does not allow undefined
94−-- signals, so a base case must be provided in case the predicate is never
115+signals, so a base case must be provided in case the predicate is never
95−-- satisfied.
116+satisfied. -}
96dropIf : (a -> Bool) -> a -> Signal a -> Signal a
117dropIf : (a -> Bool) -> a -> Signal a -> Signal a
97dropIf = Native.Signal.dropIf
118dropIf = Native.Signal.dropIf
99−-- Keep events only when the first signal is true. When the first signal becomes
120+{-| Keep events only when the first signal is true. When the first signal
100−-- true, the most recent value of the second signal will be propagated. Until
121+becomes true, the most recent value of the second signal will be propagated.
101−-- the first signal becomes false again, all events will be propagated. Elm does
122+Until the first signal becomes false again, all events will be propagated. Elm
102−-- not allow undefined signals, so a base case must be provided in case the first
123+does not allow undefined signals, so a base case must be provided in case the
103−-- signal is never true.
124+first signal is never true. -}
104keepWhen : Signal Bool -> a -> Signal a -> Signal a
125keepWhen : Signal Bool -> a -> Signal a -> Signal a
105keepWhen = Native.Signal.keepWhen
126keepWhen = Native.Signal.keepWhen
107−-- Drop events when the first signal is true. When the first signal becomes false,
128+{-| Drop events when the first signal is true. When the first signal becomes
108−-- the most recent value of the second signal will be propagated. Until the first
129+false, the most recent value of the second signal will be propagated. Until the
109−-- signal becomes true again, all events will be propagated. Elm does not allow
130+first signal becomes true again, all events will be propagated. Elm does not
110−-- undefined signals, so a base case must be provided in case the first signal is
131+allow undefined signals, so a base case must be provided in case the first
111−-- always true.
132+signal is always true. -}
112dropWhen : Signal Bool -> a -> Signal a -> Signal a
133dropWhen : Signal Bool -> a -> Signal a -> Signal a
113dropWhen = Native.Signal.dropWhen
134dropWhen = Native.Signal.dropWhen
115−-- Drop sequential repeated values. For example, if a signal produces the
136+{-| Drop sequential repeated values. For example, if a signal produces the
116−-- sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that
137+sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that are the
117−-- are the same as the previous value.
138+same as the previous value. -}
118dropRepeats : Signal a -> Signal a
139dropRepeats : Signal a -> Signal a
119dropRepeats = Native.Signal.dropRepeats
140dropRepeats = Native.Signal.dropRepeats
121−-- Sample from the second input every time an event occurs on the first input.
142+{-| Sample from the second input every time an event occurs on the first input.
122−-- For example, `(sampleOn clicks (every second))` will give the approximate
143+For example, `(sampleOn clicks (every second))` will give the approximate time
123−-- time of the latest click.
144+of the latest click. -}
124sampleOn : Signal a -> Signal b -> Signal b
145sampleOn : Signal a -> Signal b -> Signal b
125sampleOn = Native.Signal.sampleOn
146sampleOn = Native.Signal.sampleOn
127−-- An alias for `lift`. A prettier way to apply a
148+{-| An alias for `lift`. A prettier way to apply a function to the current value
128−-- function to the current value of a signal.
149+of a signal. -}
130−-- lift f signal == f <~ signal
131(<~) : (a -> b) -> Signal a -> Signal b
150(<~) : (a -> b) -> Signal a -> Signal b
132f <~ s = Native.Signal.lift f s
151f <~ s = Native.Signal.lift f s
153+{-| Informally, an alias for `liftN`. Intersperse it between additional signal
154+arguments of the lifted function.
134−-- Signal application. This takes two signals, holding a function and
156+Formally, signal application. This takes two signals, holding a function and
135−-- a value. It applies the current function to the current value.
157+a value. It applies the current function to the current value.
137−-- So the following expressions are equivalent:
159+The following expressions are equivalent:
139−-- scene <~ Window.dimensions ~ Mouse.position
161+ scene <~ Window.dimensions ~ Mouse.position
140−-- lift2 scene Window.dimensions Mouse.position
162+ lift2 scene Window.dimensions Mouse.position
141(~) : Signal (a -> b) -> Signal a -> Signal b
165(~) : Signal (a -> b) -> Signal a -> Signal b
142sf ~ s = Native.Signal.lift2 (\f x -> f x) sf s
166sf ~ s = Native.Signal.lift2 (\f x -> f x) sf s
144infixl 4 <~
168infixl 4 <~
145−infixl 4 ~
169+infixl 4 ~