on master help sign in
Clean up some documentation and make some minor API tweaks.
commita9400dbc637691c98531d05569b6e5dc9634e30b authorevancz <info@elm-lang.org> dateThu 16 May 2013, 22:10 (13 years ago) parent6e1a3f5
13 files changed+78−100
libraries/Automaton.elm+16−32 libraries/Color.elm+12−4 libraries/Graphics/Collage.elm+2−2 libraries/Keyboard.elm+1−1 libraries/Matrix2D.elm+1−1 libraries/Native/Matrix2D.js+4−2 libraries/Native/Signal/Keyboard.js+1−1 libraries/Native/Signal/Signal.js−23 libraries/Native/Signal/Time.js+1−12 libraries/Prelude.elm+19 libraries/Random.elm+1−1 libraries/Signal.elm+11−17 libraries/Time.elm+9−4
libraries/Automaton.elm+16−32
@@ -40,20 +40,26 @@ pure : (a -> b) -> Automaton a b
4040pure f = Step (\x -> (pure f, f x))
4141
4242-- Create an automaton with state. Requires an initial state and a step
43−-- function to step the state forward.
44−init : b -> (a -> b -> b) -> Automaton a b
45−init s f = Step (\x -> let s' = f x s
46− in (init s' f, s'))
43+-- function to step the state forward. For example, an automaton that counted
44+-- how many steps it has taken would look like this:
45+--
46+-- count = state 0 (\\_ c -> c+1)
47+--
48+-- It is a stateful automaton. The initial state is zero, and the step function
49+-- increments the state on every step.
50+state : b -> (a -> b -> b) -> Automaton a b
51+state s f = Step (\x -> let s' = f x s
52+ in (state s' f, s'))
4753
4854-- Create an automaton with hidden state. Requires an initial state and a
4955-- step function to step the state forward and produce an output.
50−init' : s -> (a -> s -> (s,b)) -> Automaton a b
51−init' s f = Step (\x -> let (s',out) = f x s
52− in (init' s' f, out))
56+hiddenState : s -> (a -> s -> (s,b)) -> Automaton a b
57+hiddenState s f = Step (\x -> let (s',out) = f x s
58+ in (hiddenState s' f, out))
5359
5460-- Count the number of steps taken.
5561count : Automaton a Int
56−count = init 0 (\_ c -> c + 1)
62+count = state 0 (\_ c -> c + 1)
5763
5864type Queue t = ([t],[t])
5965empty = ([],[])
@@ -64,7 +70,7 @@ dequeue q = case q of
6470 (en,hd::tl) -> Just (hd, (en,tl))
6571
6672-- Computes the running average of the last `n` inputs.
67−average : Int -> Automaton (Number a) (Number a)
73+average : Int -> Automaton Float Float
6874average k =
6975 let step n (ns,len,sum) =
7076 if len == k then stepFull n (ns,len,sum)
@@ -74,30 +80,8 @@ average k =
7480 Nothing -> ((ns,len,sum), 0)
7581 Just (m,ns') -> let sum' = sum + n - m
7682 in ((enqueue n ns', len, sum'), sum' / len)
77− in init' (empty,0,0) step
83+ in hiddenState (empty,0,0) step
7884
79−{-- TODO(evancz): move this code to the Form library so people can find it.
80−
81−data DragState = Listen | Ignore | DragFrom (Int,Int)
82−
83−vecSub (x1,y1) (x2,y2) = (x1-x2,y1-y2)
84−
85−stepDrag (press,pos) (ds,form) =
86− let wrap ds' = (form, (ds',form)) in
87− case ds of
88− Listen -> wrap (if | not press -> Listen
89− | pos `isWithin` form -> DragFrom pos
90− | otherwise -> Ignore)
91− Ignore -> wrap (if press then Ignore else Listen)
92− DragFrom p0 ->
93− if press then (uncurry move (vecSub pos p0) form, (DragFrom p0, form))
94− else (let form' = uncurry move (vecSub pos p0) form in
95− (form', (Listen,form')))
96−
97−-- Create a draggable form that can be dynamically created and added to a scene.
98−draggable : Form -> Automaton (Bool,(Int,Int)) Form
99−draggable form = init' (Listen,form) stepDrag
100−--}
10185
10286{-- TODO(evancz): See the following papers for ideas on how to make this
10387library faster and better:
libraries/Color.elm+12−4
@@ -81,9 +81,17 @@ data Gradient
8181 = Linear (Float,Float) (Float,Float) [(Float,Color)]
8282 | Radial (Float,Float) Float (Float,Float) Float [(Float,Color)]
8383
84−linear : (Number a, Number a) ->
85− (Number a, Number a) -> [(Float,Color)] -> Gradient
84+-- Create a linear gradient. Takes a start and end point and then a series
85+-- of &ldquo;color stops&rdquo; that indicate how to interpolate between
86+-- the start and end points. See [this example](/edit/examples/Elements/LinearGradient.elm) for
87+-- a more visual explanation.
88+linear : (Number a, Number a) -> (Number a, Number a) -> [(Float,Color)] -> Gradient
8689linear = Linear
87−radial : (Number a,Number a) -> Number a ->
88− (Number a,Number a) -> Number a -> [(Float,Color)] -> Gradient
90+
91+-- Create a radial gradient. First takes a start point and inner radius.
92+-- Then takes an end point and outer radius. It then takes a series
93+-- of &ldquo;color stops&rdquo; that indicate how to interpolate between
94+-- the inner and outer circles. See [this example](/edit/examples/Elements/RadialGradient.elm) for
95+-- a more visual explanation.
96+radial : (Number a,Number a) -> Number a -> (Number a,Number a) -> Number a -> [(Float,Color)] -> Gradient
8997radial = Radial
libraries/Graphics/Collage.elm+2−2
@@ -103,8 +103,8 @@ rotate t f = { f | theta <- f.theta + t }
103103scale : Float -> Form -> Form
104104scale s f = { f | scale <- f.scale * s }
105105
106−move : Float -> Float -> Form -> Form
107−move x y f = { f | x <- f.x + x, y <- f.y + y }
106+move : (Float,Float) -> Form -> Form
107+move (x,y) f = { f | x <- f.x + x, y <- f.y + y }
108108
109109moveX : Float -> Form -> Form
110110moveX x f = { f | x <- f.x + x }
libraries/Keyboard.elm+1−1
@@ -49,4 +49,4 @@ enter = N.isDown 13
4949keysDown : Signal [KeyCode]
5050
5151-- The latest key that has been pressed.
52−lastKey : Signal KeyCode
52+lastPressed : Signal KeyCode
libraries/Matrix2D.elm+1−1
@@ -7,7 +7,7 @@ identity : Matrix
77
88transform : Float -> Float -> Float -> Float -> Float -> Float -> Matrix -> Matrix
99rotate : Float -> Matrix -> Matrix
10−move : Float -> Float -> Matrix -> Matrix
10+move : (Float,Float) -> Matrix -> Matrix
1111scale : Float -> Matrix -> Matrix
1212scaleX : Float -> Matrix -> Matrix
1313scaleY : Float -> Matrix -> Matrix
libraries/Native/Matrix2D.js+4−2
@@ -28,7 +28,9 @@ Elm.Native.Matrix2D = function(elm) {
2828 return new A([m11*c + m12*s, -m11*s + m12*c, m[2],
2929 m21*c + m22*s, -m21*s + m22*c, m[5]]);
3030 }
31− function move(x,y,m) {
31+ function move(xy,m) {
32+ var x = xy._0;
33+ var y = xy._1;
3234 var m11 = m[0], m12 = m[1], m21 = m[3], m22 = m[4];
3335 return new A([m11, m12, m11*x + m12*y + m[2],
3436 m21, m22, m21*x + m22*y + m[5]]);
@@ -60,7 +62,7 @@ Elm.Native.Matrix2D = function(elm) {
6062
6163 transform:F7(transform),
6264 rotate:F2(rotate),
63− move:F3(move),
65+ move:F2(move),
6466 scale:F2(scale),
6567 scaleX:F2(scaleX),
6668 scaleY:F2(scaleY),
libraries/Native/Signal/Keyboard.js+1−1
@@ -66,7 +66,7 @@ Elm.Native.Keyboard = function(elm) {
6666 isDown:is,
6767 directions:F4(dir),
6868 keysDown:keysDown,
69− lastKey:lastKey
69+ lastPressed:lastKey
7070 };
7171
7272};
libraries/Native/Signal/Signal.js−23
@@ -6,10 +6,8 @@ Elm.Native.Signal = function(elm) {
66 if (elm.Native.Signal) return elm.Native.Signal;
77
88 var Utils = Elm.Native.Utils(elm);
9− var Either = Elm.Either(elm);
109 var foldl1 = Elm.List(elm).foldl1;
1110
12−
1311 function send(node, timestep, changed) {
1412 var kids = node.kids;
1513 for (var i = kids.length; i--; ) {
@@ -195,25 +193,6 @@ Elm.Native.Signal = function(elm) {
195193
196194 function merge(s1,s2) { return new Merge(s1,s2); }
197195 function merges(ss) { return A2(foldl1, F2(merge), ss); }
198− function mergeEither(s1,s2) { return new Merge(lift(Either.Left, s1),
199− lift(Either.Right,s2)); }
200−
201− function average(sampleSize, s) {
202− var sample = new Array(sampleSize);
203− var i = sampleSize;
204− while (i--) { sample[i] = 0; }
205− i = 0;
206− var full = false;
207− var total = 0;
208− function f(n) {
209− total += n - sample[i];
210− sample[i] = n;
211− var avg = total / Math.max(1, full ? sampleSize : i);
212− if (++i == sampleSize) { full = true; i = 0; }
213− return avg;
214− }
215− return lift(f,s);
216− }
217196
218197 return elm.Native.Signal = {
219198 constant : function(v) { return new Input(v); },
@@ -229,8 +208,6 @@ Elm.Native.Signal = function(elm) {
229208 delay : F2(delay),
230209 merge : F2(merge),
231210 merges : merges,
232− mergeEither : F2(mergeEither),
233− average : F2(average),
234211 count : function(s) { return foldp(F2(function(_,c) { return c+1; }), 0, s); },
235212 countIf : F2(function(pred,s) {
236213 return foldp(F2(function(x,c){
libraries/Native/Signal/Time.js+1−12
@@ -42,18 +42,6 @@ Elm.Native.Time = function(elm) {
4242 var dcount = Signal.count(A2(Signal.delay, t, s));
4343 return A3( Signal.lift2, F2(cmp), Signal.count(s), dcount );
4444 }
45− function after(t) {
46− t *= 1000;
47− var thread = Signal.constant(false);
48− setTimeout(function() { elm.notify(thread.id, true); }, t);
49− return thread;
50− }
51− function before(t) {
52− t *= 1000;
53− var thread = Signal.constant(true);
54− setTimeout(function() { elm.notify(thread.id, false); }, t);
55− return thread;
56− }
5745 function read(s) {
5846 var t = Date.parse(s);
5947 return isNaN(t) ? Maybe.Nothing : Maybe.Just(t);
@@ -63,6 +51,7 @@ Elm.Native.Time = function(elm) {
6351 fps : function(t) { return fpsWhen(t, Signal.constant(true)); },
6452 every : function(t) { return everyWhen(t, Signal.constant(true)) },
6553 delay : Signal.delay,
54+ timestamp : Signal.timestamp,
6655 since : F2(since),
6756 after : after,
6857 before : before,
libraries/Prelude.elm+19
@@ -3,18 +3,34 @@ module Prelude where
33
44import Native.Prelude as N
55
6+-- Convert radians to standard Elm angles (radians).
67radians : Float -> Float
78radians t = t
89
10+-- Convert degrees to standard Elm angles (radians).
911degrees : Float -> Float
1012degrees d = d * Math.PI / 180
1113
14+-- Convert turns to standard Elm angles (radians).
15+-- One turn is equal to 360&deg;.
1216turns : Float -> Float
1317turns r = 2 * Math.PI * r
1418
19+-- Start with polar coordinates (r,&theta;)
20+-- and get out cartesian coordinates (x,y).
21+fromPolar : (Float,Float) -> (Float,Float)
22+fromPolar (r,t) = (r * N.cos t, r * N.sin t)
23+
24+-- Start with cartesian coordinates (x,y)
25+-- and get out polar coordinates (r,&theta;).
26+toPolar : (Float,Float) -> (Float,Float)
27+toPolar (x,y) = (N.sqrt (x^2 + y^2), N.atan2 y x)
28+
1529(+) : Number a -> Number a -> Number a
1630(-) : Number a -> Number a -> Number a
1731(*) : Number a -> Number a -> Number a
32+
33+-- Floating point division.
1834(/) : Float -> Float -> Float
1935
2036-- Integer division, remainder is discarded.
@@ -26,6 +42,9 @@ rem : Int -> Int -> Int
2642-- Perform modular arithmetic: 7 `mod` 2 == 1
2743mod : Int -> Int -> Int
2844
45+-- Exponentiation: `3^2 == 9`
46+(^) : Number a -> Number a -> Number a
47+
2948-- Basic functions of trigonometry.
3049cos : Float -> Float
3150sin : Float -> Float
libraries/Random.elm+1−1
@@ -9,5 +9,5 @@ import Native.Random as R
99range : Int -> Int -> Signal a -> Signal Int
1010
1111-- Produces a new signal that changes whenever the input signal changes.
12−-- The new values are random number in [0..1).
12+-- The new values are random numbers in [0..1).
1313float : Signal a -> Signal Float
libraries/Signal.elm+11−17
@@ -23,9 +23,12 @@ lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c
2323lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d
2424lift4 : (a -> b -> c -> d -> e) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e
2525lift5 : (a -> b -> c -> d -> e -> f) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f
26−lift6 : (a -> b -> c -> d -> e -> f -> g) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g
27−lift7 : (a -> b -> c -> d -> e -> f -> g -> h) -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h
28−lift8 : (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
26+lift6 : (a -> b -> c -> d -> e -> f -> g)
27+ -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g
28+lift7 : (a -> b -> c -> d -> e -> f -> g -> h)
29+ -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h
30+lift8 : (a -> b -> c -> d -> e -> f -> g -> h -> i)
31+ -> Signal a -> Signal b -> Signal c -> Signal d -> Signal e -> Signal f -> Signal g -> Signal h -> Signal i
2932
3033-- Create a past-dependent signal. Each value given on the input signal will
3134-- be accumulated, producing a new output value.
@@ -41,14 +44,14 @@ merge : Signal a -> Signal a -> Signal a
4144-- signals update simultaneously.
4245merges : [Signal a] -> Signal a
4346
44−-- Combine many signals into one, with an array of results.
47+-- Combine a list of signals into a signal of lists.
4548combine : [Signal a] -> Signal [a]
4649combine = L.foldr (S.lift2 (::)) (S.constant [])
4750
48−-- Merge two signals into one, but distinguishing the values by marking the first
49−-- signal as `Left` and the second signal as `Right`. This allows you to easily
50−-- fold over non-homogeneous inputs.
51−mergeEither : Signal a -> Signal b -> Signal (Either a b)
51+ -- Merge two signals into one, but distinguishing the values by marking the first
52+ -- signal as `Left` and the second signal as `Right`. This allows you to easily
53+ -- fold over non-homogeneous inputs.
54+ -- mergeEither : Signal a -> Signal b -> Signal (Either a b)
5255
5356-- Count the number of events that have occured.
5457count : Signal a -> Signal Int
@@ -90,15 +93,6 @@ dropRepeats : Signal a -> Signal a
9093-- time of the latest click.
9194sampleOn : Signal a -> Signal b -> Signal b
9295
93−-- Add a timestamp to any signal. Timestamps increase monotonically. Each timestamp is
94−-- related to a specfic event, so `Mouse.x` and `Mouse.y` will always have the same
95−-- timestamp because they both rely on the same underlying event.
96−timestamp : Signal a -> Signal (Time, a)
97−
98−-- Delay a signal by a certain amount of time. So `(delay second Mouse.clicks)`
99−-- will update one second later than any mouse click.
100−delay : Time -> Signal a -> Signal a
101−
10296-- An alias for `lift`. A prettier way to apply a
10397-- function to the current value of a signal.
10498(<~) : (a -> b) -> Signal a -> Signal b
libraries/Time.elm+9−4
@@ -56,7 +56,12 @@ every : Time -> Signal Time
5656-- otherwise.
5757since : Time -> Signal a -> Signal Bool
5858
59−{-- TODO: Only found in docs
60− , ("timeOf", "Signal a -> Signal Time", [markdown|
61− Same as `timestamp` but it throws out the incoming value. So `(timeOf == lift fst . timestamp)`.|])
62−--}
59+-- Add a timestamp to any signal. Timestamps increase monotonically. Each
60+-- timestamp is related to a specfic event, so `Mouse.x` and `Mouse.y` will
61+-- always have the same timestamp because they both rely on the same
62+-- underlying event.
63+timestamp : Signal a -> Signal (Time, a)
64+
65+-- Delay a signal by a certain amount of time. So `(delay second Mouse.clicks)`
66+-- will update one second later than any mouse click.
67+delay : Time -> Signal a -> Signal a