From 5e3f783a231ced7d41188499614678b59015e242 Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Tue, 27 Oct 2009 12:29:24 -0400 Subject: [PATCH] docs done -- going back to code comments --- index.html | 137 ++++++++++++++++++++++++++++-------------------- test/arrays.js | 2 +- test/objects.js | 4 -- underscore.js | 26 +++++---- 4 files changed, 94 insertions(+), 75 deletions(-) diff --git a/index.html b/index.html index 4fa43925c..535df71bb 100644 --- a/index.html +++ b/index.html @@ -116,7 +116,7 @@
keys, values, extend, clone, isEqual, isElement, - isArray, isFunction, isUndefined, toString + isArray, isFunction, isUndefined

@@ -142,7 +142,7 @@ 

 _.each([1, 2, 3], function(num){ alert(num); });
-=> alerts each number in turn...
+=> alerts each number in turn...

map_.map(list, iterator, [context]) @@ -153,7 +153,7 @@ _.each([1, 2, 3], function(num){ alert(num); }); 

 _.map([1, 2, 3], function(num){ return num * 3 });
-=> [3, 6, 9]
+=> [3, 6, 9]

inject_.inject(list, memo, iterator, [context]) @@ -165,7 +165,7 @@ _.map([1, 2, 3], function(num){ return num * 3 }); 

 var sum = _.inject([1, 2, 3], 0, function(memo, num){ return memo + num });
-=> 6
+=> 6

@@ -178,7 +178,7 @@ var sum = _.inject([1, 2, 3], 0, function(memo, num){ return memo + num }); 

 var even = _.detect([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
-=> 2
+=> 2

@@ -190,7 +190,7 @@ var even = _.detect([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; }); 

 var evens = _.select([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
-=> [2, 4, 6]
+=> [2, 4, 6]

@@ -201,7 +201,7 @@ var evens = _.select([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; }); 

 var odds = _.reject([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
-=> [1, 3, 5]
+=> [1, 3, 5]

@@ -214,7 +214,7 @@ var odds = _.reject([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; }); 

 _.all([true, 1, null, 'yes']);
-=> false
+=> false

@@ -227,7 +227,7 @@ _.all([true, 1, null, 'yes']); 

 _.any([null, 0, 'yes', false]);
-=> true
+=> true

@@ -239,7 +239,7 @@ _.any([null, 0, 'yes', false]); 

 _.include([1, 2, 3], 3);
-=> true
+=> true

@@ -251,7 +251,7 @@ _.include([1, 2, 3], 3); 

 _.invoke([[5, 1, 7], [3, 2, 1]], 'sort');
-=> [[1, 5, 7], [1, 2, 3]]
+=> [[1, 5, 7], [1, 2, 3]]

@@ -263,7 +263,7 @@ _.invoke([[5, 1, 7], [3, 2, 1]], 'sort'); 

 var stooges = [{name : 'moe', age : 40}, {name : 'larry', age : 50}, {name : 'curly', age : 60}];
 _.pluck(stooges, 'name');
-=> ["moe", "larry", "curly"]
+=> ["moe", "larry", "curly"]

@@ -276,7 +276,7 @@ _.pluck(stooges, 'name'); 

 var stooges = [{name : 'moe', age : 40}, {name : 'larry', age : 50}, {name : 'curly', age : 60}];
 _.max(stooges, function(stooge){ return stooge.age; });
-=> {name : 'curly', age : 60};
+=> {name : 'curly', age : 60};

@@ -289,7 +289,7 @@ _.max(stooges, function(stooge){ return stooge.age; }); 

 var numbers = [10, 5, 100, 2, 1000];
 _.min(numbers);
-=> 2
+=> 2

@@ -300,7 +300,7 @@ _.min(numbers); 

 _.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); });
-=> [5, 4, 6, 3, 1, 2]
+=> [5, 4, 6, 3, 1, 2]

@@ -313,7 +313,7 @@ _.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); }); 

 _.sortedIndex([10, 20, 30, 40, 50], 35);
-=> 3
+=> 3

@@ -324,7 +324,7 @@ _.sortedIndex([10, 20, 30, 40, 50], 35); 

 (function(){ return _.toArray(arguments).slice(0); })(1, 2, 3);
-=> [1, 2, 3]
+=> [1, 2, 3]

@@ -334,7 +334,7 @@ _.sortedIndex([10, 20, 30, 40, 50], 35); 

 _.size({one : 1, two : 2, three : 3});
-=> 3
+=> 3

Array Functions

@@ -346,7 +346,7 @@ _.size({one : 1, two : 2, three : 3}); 

 _.first([3, 2, 1]);
-=> 3
+=> 3

@@ -356,7 +356,7 @@ _.first([3, 2, 1]); 

 _.last([3, 2, 1]);
-=> 1
+=> 1

@@ -368,7 +368,7 @@ _.last([3, 2, 1]); 

 _.compact([0, 1, false, 2, '', 3]);
-=> [1, 2, 3]
+=> [1, 2, 3]

@@ -378,7 +378,7 @@ _.compact([0, 1, false, 2, '', 3]); 

 _.flatten([1, [2], [3, [[[4]]]]]);
-=> [1, 2, 3, 4];
+=> [1, 2, 3, 4];

@@ -389,7 +389,7 @@ _.flatten([1, [2], [3, [[[4]]]]]); 

 _.without([1, 2, 1, 0, 3, 1, 4], 0, 1);
-=> [2, 3, 4]
+=> [2, 3, 4]

@@ -401,7 +401,7 @@ _.without([1, 2, 1, 0, 3, 1, 4], 0, 1); 

 _.uniq([1, 2, 1, 3, 1, 4]);
-=> [1, 2, 3, 4]
+=> [1, 2, 3, 4]

@@ -412,7 +412,7 @@ _.uniq([1, 2, 1, 3, 1, 4]); 

 _.intersect([1, 2, 3], [101, 2, 1, 10], [2, 1]);
-=> [1, 2]
+=> [1, 2]

@@ -424,7 +424,7 @@ _.intersect([1, 2, 3], [101, 2, 1, 10], [2, 1]); 

 _.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
-=> [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]
+=> [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]

@@ -436,7 +436,7 @@ _.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]); 

 _.indexOf([1, 2, 3], 2);
-=> 1
+=> 1

Function (uh, ahem) Functions

@@ -453,7 +453,7 @@ _.indexOf([1, 2, 3], 2); var func = function(greeting){ return greeting + ': ' + this.name }; func = _.bind(func, {name : 'moe'}, 'hi'); func(); -=> 'hi: moe' +=> 'hi: moe'

@@ -473,7 +473,7 @@ var buttonView = { }; _.bindAll('onClick', 'onHover', buttonView); jQuery('#underscore_button').bind('click', buttonView.onClick); -=> When the button is clicked, this.label will have the correct value... +=> When the button is clicked, this.label will have the correct value...

@@ -486,7 +486,7 @@ jQuery('#underscore_button').bind('click', buttonView.onClick); 

 var log = _.bind(console.log, console);
 _.delay(log, 1000, 'logged later');
-=> 'logged later' // Appears after one second.
+=> 'logged later' // Appears after one second.

@@ -516,7 +516,7 @@ hello = _.wrap(hello, function(func) { return "before, " + func("moe") + ", after"; }); hello(); -=> before, hello: moe, after +=> before, hello: moe, after

Object Functions

@@ -528,7 +528,7 @@ hello(); 

 _.keys({one : 1, two : 2, three : 3});
-=> ["one", "two", "three"]
+=> ["one", "two", "three"]

@@ -538,7 +538,7 @@ _.keys({one : 1, two : 2, three : 3}); 

 _.values({one : 1, two : 2, three : 3});
-=> [1, 2, 3]
+=> [1, 2, 3]

@@ -549,7 +549,7 @@ _.values({one : 1, two : 2, three : 3}); 

 _.extend({name : 'moe'}, {age : 50});
-=> {name : 'moe', age : 50}
+=> {name : 'moe', age : 50}

@@ -560,7 +560,7 @@ _.extend({name : 'moe'}, {age : 50}); 

 _.clone({name : 'moe'});
-=> {name : 'moe'};
+=> {name : 'moe'};

@@ -573,60 +573,85 @@ _.clone({name : 'moe'}); var moe = {name : 'moe', luckyNumbers : [13, 27, 34]}; var clone = {name : 'moe', luckyNumbers : [13, 27, 34]}; moe == clone; -=> false +=> false _.isEqual(moe, clone); -=> true +=> true -

- isElement_.() +

+ isElement_.isElement(object)
+ Returns true if object is a DOM element. 

+_.isElement(jQuery('body')[0]);
+=> true
-

- isArray_.() +

+ isArray_.isArray(object)
+ Returns true if object is an Array. 

+(function(){ return _.isArray(arguments); })();
+=> false
+_.isArray([1,2,3]);
+=> true
-

- isFunction_.() +

+ isFunction_.isFunction(object)
+ Returns true if object is a Function. 

+_.isFunction(alert);
+=> true
-

- isUndefined_.() -
-

- 
-
- -

- toString_.() +

+ isUndefined_.isUndefined(variable)
+ Returns true if variable is undefined. 

+_.isUndefined(window.missingVariable);
+=> true

Utility Functions

-

- uniqueId_.() +

+ uniqueId_.uniqueId([prefix])
+ Generate a globally-unique id for client-side models or DOM elements + that need one. If prefix is passed, the id will be appended to it. 

+_.uniqueId('contact_');
+=> 'contact_104'
-

- template_.() +

+ template_.template(templateString)
+ Compiles Javascript templates into functions that can be evaluated + for rendering. Useful for rendering complicated bits of HTML from JSON + data sources. Template functions can both interpolate variables, using
+ <%= … %>, as well as execute arbitrary Javascript code, with + <% … %>. When you evaluate a template, pass in a + context object that has properties corresponding to the template's free + variables. 

+var compiled = _.template("hello: <%= name %>");
+compiled({name : 'moe'});
+=> "hello: moe"
+
+var list = "<% _.each(people, function(name) { %> <li><%= name %></li> <% }); %>";
+_.template(list, {people : ['moe', 'curly', 'larry']});
+=> "<li>moe</li><li>curly</li><li>larry</li>"
diff --git a/test/arrays.js b/test/arrays.js index 7b4e45692..e59397996 100644 --- a/test/arrays.js +++ b/test/arrays.js @@ -40,7 +40,7 @@ $(document).ready(function() { test('arrays: zip', function() { var names = ['moe', 'larry', 'curly'], ages = [30, 40, 50], leaders = [true]; var stooges = _.zip(names, ages, leaders); - equals(_.toString(stooges), 'moe,30,true,larry,40,,curly,50,', 'zipped together arrays of different lengths'); + equals(String(stooges), 'moe,30,true,larry,40,,curly,50,', 'zipped together arrays of different lengths'); }); test("arrays: indexOf", function() { diff --git a/test/objects.js b/test/objects.js index 624d67bfe..eb73245d8 100644 --- a/test/objects.js +++ b/test/objects.js @@ -58,9 +58,5 @@ $(document).ready(function() { ok(_.isUndefined(), 'nothing is undefined'); ok(_.isUndefined(undefined), 'undefined is undefined'); }); - - test("objects: toString", function() { - equals(_.toString([1, 2, 3]), '1,2,3', 'object can be converted to printable strings'); - }); }); diff --git a/underscore.js b/underscore.js index 7a42cbb12..9f2f403e8 100644 --- a/underscore.js +++ b/underscore.js @@ -1,6 +1,11 @@ -// Javascript can be so much more pleasant when it's functional -- re-implement -// a bunch of utility methods from Prototype and Steele's Functional... +// Underscore.js +// (c) 2009 Jeremy Ashkenas, DocumentCloud Inc. +// Underscore is freely distributable under the terms of the MIT license. +// For all details and documentation: +// http://fdjklsafjsdalk window._ = { + + VERSION : '0.1.0', // The cornerstone, an each implementation. // Handles objects implementing forEach, _each, arrays, and raw objects. @@ -345,17 +350,15 @@ window._ = { if (a == b) return true; // One of them implements an isEqual()? if (a.isEqual) return a.isEqual(b); + // If a is not an object by this point, we can't handle it. + if (atype !== 'object') return false; // Nothing else worked, deep compare the contents. - return atype === 'object' && _._isEqualContents(a, b); - }, - - // Objects have equal contents if they have the same keys, and all the values - // are equal (as defined by _.isEqual). - _isEqualContents : function(a, b) { var aKeys = _.keys(a), bKeys = _.keys(b); + // Different object sizes? if (aKeys.length != bKeys.length) return false; + // Recursive comparison of contents. for (var key in a) if (!_.isEqual(a[key], b[key])) return false; - return true; + return true; }, // Is a given value a DOM element? @@ -378,11 +381,6 @@ window._ = { return typeof obj == 'undefined'; }, - // Convert any value into printable string form. - toString : function(obj) { - return obj == null ? '' : String(obj); - }, - /* -------------- The following methods are utility methods --------------- */ // Generate a unique integer id (unique within the entire client session).