@@ -1,32 +1,52 @@
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`.
2+{-| The library for general signal manipulation. Includes lift functions up to
3+`lift8` and infix lift operators `<~` and `~`, combinations, filters, and
4+past-dependence.
5+
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
9+past-dependence.
10+
11+Some useful functions for working with time (e.g. setting FPS) and combining
12+signals and time (e.g. delaying updates, getting timestamps) can be found in
13+the [`Time`](/docs/Signal/Time.elm) library.
14+
15+# Combine
16+@docs constant, lift, lift2, merge, merges, combine
17+
18+# Pretty Lift
19+@docs (<~), (~)
20+
21+# Past-Dependence
22+@docs foldp, count, countIf
23+
24+#Filters
25+@docs keepIf, dropIf, keepWhen, dropWhen, dropRepeats, sampleOn
26+
27+# Do you even lift?
28+@docs lift3, lift4, lift5, lift6, lift7, lift8
29+
30+-}
831module Signal where
932
1033import Native.Signal
1134import List (foldr)
1235
1336data Signal a = Signal
14−-- = Constant a
15−-- | Lift (a -> a) (Signal a)
1637
17−-- Create a constant signal that never changes.
38+{-| Create a constant signal that never changes. -}
1839constant : a -> Signal a
1940constant = Native.Signal.constant
2041
21−-- Transform a signal with a given function.
42+{-| Transform a signal with a given function. -}
2243lift : (a -> b) -> Signal a -> Signal b
2344lift = Native.Signal.lift
2445
25−-- Combine two signals with a given function.
46+{-| Combine two signals with a given function. -}
2647lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c
2748lift2 = Native.Signal.lift2
2849
29−-- Combine three signals with a given function.
3050lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d
3151lift3 = Native.Signal.lift3
3252
@@ -49,25 +69,25 @@ lift8 : (a -> b -> c -> d -> e -> f -> g -> h -> i)
4969lift8 = Native.Signal.lift8
5070
5171
52−-- Create a past-dependent signal. Each value given on the input signal will
53−-- be accumulated, producing a new output value.
54−--
55−-- For instance, `(foldp (\\arrows number -> number + arrows.y) 0 Keyboard.arrows)`
56−-- increments or decrements the accumulated value (which starts at zero) when the up or down arrow keys are pressed.
72+{-| Create a past-dependent signal. Each value given on the input signal will
73+be accumulated, producing a new output value.
74+
75+For instance, `foldp (+) 0 (fps 40)` is the time the program has been running,
76+updated 40 times a second. -}
5777foldp : (a -> b -> b) -> b -> Signal a -> Signal b
5878foldp = Native.Signal.foldp
5979
60−-- Merge two signals into one, biased towards the first signal if both signals
61−-- update at the same time.
80+{-| Merge two signals into one, biased towards the first signal if both signals
81+update at the same time. -}
6282merge : Signal a -> Signal a -> Signal a
6383merge = Native.Signal.merge
6484
65−-- Merge many signals into one, biased towards the left-most signal if multiple
66−-- signals update simultaneously.
85+{-| Merge many signals into one, biased towards the left-most signal if multiple
86+signals update simultaneously. -}
6787merges : [Signal a] -> Signal a
6888merges = Native.Signal.merges
6989
70−-- Combine a list of signals into a signal of lists.
90+{-| Combine a list of signals into a signal of lists. -}
7191combine : [Signal a] -> Signal [a]
7292combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
7393
@@ -76,70 +96,74 @@ combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant [])
7696 -- fold over non-homogeneous inputs.
7797 -- mergeEither : Signal a -> Signal b -> Signal (Either a b)
7898
79−-- Count the number of events that have occured.
99+{-| Count the number of events that have occured. -}
80100count : Signal a -> Signal Int
81101count = Native.Signal.count
82102
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.
104+-}
84105countIf : (a -> Bool) -> Signal a -> Signal Int
85106countIf = Native.Signal.countIf
86107
87−-- 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
89−-- never satisfied.
108+{-| Keep only events that satisfy the given predicate. Elm does not allow
109+undefined signals, so a base case must be provided in case the predicate is
110+never satisfied. -}
90111keepIf : (a -> Bool) -> a -> Signal a -> Signal a
91112keepIf = Native.Signal.keepIf
92113
93−-- 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
95−-- satisfied.
114+{-| Drop events that satisfy the given predicate. Elm does not allow undefined
115+signals, so a base case must be provided in case the predicate is never
116+satisfied. -}
96117dropIf : (a -> Bool) -> a -> Signal a -> Signal a
97118dropIf = Native.Signal.dropIf
98119
99−-- Keep events only when the first signal is true. When the first signal becomes
100−-- true, the most recent value of the second signal will be propagated. Until
101−-- the first signal becomes false again, all events will be propagated. Elm does
102−-- not allow undefined signals, so a base case must be provided in case the first
103−-- signal is never true.
120+{-| Keep events only when the first signal is true. When the first signal
121+becomes true, the most recent value of the second signal will be propagated.
122+Until the first signal becomes false again, all events will be propagated. Elm
123+does not allow undefined signals, so a base case must be provided in case the
124+first signal is never true. -}
104125keepWhen : Signal Bool -> a -> Signal a -> Signal a
105126keepWhen = Native.Signal.keepWhen
106127
107−-- Drop events when the first signal is true. When the first signal becomes false,
108−-- the most recent value of the second signal will be propagated. Until the first
109−-- signal becomes true again, all events will be propagated. Elm does not allow
110−-- undefined signals, so a base case must be provided in case the first signal is
111−-- always true.
128+{-| Drop events when the first signal is true. When the first signal becomes
129+false, the most recent value of the second signal will be propagated. Until the
130+first signal becomes true again, all events will be propagated. Elm does not
131+allow undefined signals, so a base case must be provided in case the first
132+signal is always true. -}
112133dropWhen : Signal Bool -> a -> Signal a -> Signal a
113134dropWhen = Native.Signal.dropWhen
114135
115−-- 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
117−-- are the same as the previous value.
136+{-| Drop sequential repeated values. For example, if a signal produces the
137+sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that are the
138+same as the previous value. -}
118139dropRepeats : Signal a -> Signal a
119140dropRepeats = Native.Signal.dropRepeats
120141
121−-- 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
123−-- time of the latest click.
142+{-| Sample from the second input every time an event occurs on the first input.
143+For example, `(sampleOn clicks (every second))` will give the approximate time
144+of the latest click. -}
124145sampleOn : Signal a -> Signal b -> Signal b
125146sampleOn = Native.Signal.sampleOn
126147
127−-- An alias for `lift`. A prettier way to apply a
128−-- function to the current value of a signal.
129−--
130−-- lift f signal == f <~ signal
148+{-| An alias for `lift`. A prettier way to apply a function to the current value
149+of a signal. -}
131150(<~) : (a -> b) -> Signal a -> Signal b
132151f <~ s = Native.Signal.lift f s
133152
134−-- Signal application. This takes two signals, holding a function and
135−-- a value. It applies the current function to the current value.
136−--
137−-- So the following expressions are equivalent:
138−--
139−-- scene <~ Window.dimensions ~ Mouse.position
140−-- lift2 scene Window.dimensions Mouse.position
153+{-| Informally, an alias for `liftN`. Intersperse it between additional signal
154+arguments of the lifted function.
155+
156+Formally, signal application. This takes two signals, holding a function and
157+a value. It applies the current function to the current value.
158+
159+The following expressions are equivalent:
160+
161+ scene <~ Window.dimensions ~ Mouse.position
162+ lift2 scene Window.dimensions Mouse.position
163+-}
164+
141165(~) : Signal (a -> b) -> Signal a -> Signal b
142166sf ~ s = Native.Signal.lift2 (\f x -> f x) sf s
143167
144168infixl 4 <~
145−infixl 4 ~
169+infixl 4 ~