From 3f49d1df3029ab0d3df44ccfa70f7de386bcae49 Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Tue, 5 Oct 2010 16:44:56 -0400 Subject: [PATCH] Tweaking Underscore for docco-mentation. --- docs/docco.css | 185 +++++++++++++++++++ docs/underscore.html | 417 +++++++++++++++++++++++++++++++++++++++++++ underscore.js | 60 ++++--- 3 files changed, 636 insertions(+), 26 deletions(-) create mode 100644 docs/docco.css create mode 100644 docs/underscore.html diff --git a/docs/docco.css b/docs/docco.css new file mode 100644 index 000000000..1ddec8912 --- /dev/null +++ b/docs/docco.css @@ -0,0 +1,185 @@ +/*--------------------- Layout and Typography ----------------------------*/ +body { + font-family: 'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif; + font-size: 16px; + line-height: 24px; + color: #252519; + margin: 0; padding: 0; +} +a { + color: #261a3b; +} + a:visited { + color: #261a3b; + } +p { + margin: 0 0 15px 0; +} +h1, h2, h3, h4, h5, h6 { + margin: 40px 0 15px 0; +} + h3, h4, h5, h6 { + margin-top: 20px; + } +#container { + position: relative; +} +#background { + position: fixed; + top: 0; left: 575px; right: 0; bottom: 0; + background: #f5f5ff; + border-left: 1px solid #e5e5ee; + z-index: -1; +} +#jump_to, #jump_page { + background: white; + -webkit-box-shadow: 0 0 25px #777; -moz-box-shadow: 0 0 25px #777; + -webkit-border-bottom-left-radius: 5px; -moz-border-radius-bottomleft: 5px; + font: 10px Arial; + text-transform: uppercase; + cursor: pointer; + text-align: right; +} +#jump_to, #jump_wrapper { + position: fixed; + right: 0; top: 0; + padding: 5px 10px; +} + #jump_wrapper { + padding: 0; + display: none; + } + #jump_to:hover #jump_wrapper { + display: block; + } + #jump_page { + padding: 5px 0 3px; + margin: 0 0 25px 25px; + } + #jump_page .source { + display: block; + padding: 5px 10px; + text-decoration: none; + border-top: 1px solid #eee; + } + #jump_page .source:hover { + background: #f5f5ff; + } + #jump_page .source:first-child { + } +table td { + border: 0; + outline: 0; +} + td.docs, th.docs { + max-width: 500px; + min-width: 500px; + min-height: 5px; + padding: 10px 25px 1px 50px; + vertical-align: top; + text-align: left; + } + .docs pre { + margin: 15px 0 15px; + padding-left: 15px; + } + .docs p tt, .docs p code { + background: #f8f8ff; + border: 1px solid #dedede; + font-size: 12px; + padding: 0 0.2em; + } + .octowrap { + position: relative; + } + .octothorpe { + font: 12px Arial; + text-decoration: none; + color: #454545; + position: absolute; + top: 3px; left: -20px; + padding: 1px 2px; + opacity: 0; + -webkit-transition: opacity 0.2s linear; + } + td.docs:hover .octothorpe { + opacity: 1; + } + td.code, th.code { + padding: 14px 15px 16px 50px; + width: 100%; + vertical-align: top; + background: #f5f5ff; + border-left: 1px solid #e5e5ee; + } + pre, tt, code { + font-size: 12px; line-height: 18px; + font-family: Monaco, Consolas, "Lucida Console", monospace; + margin: 0; padding: 0; + } + + +/*---------------------- Syntax Highlighting -----------------------------*/ +td.linenos { background-color: #f0f0f0; padding-right: 10px; } +span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; } +body .hll { background-color: #ffffcc } +body .c { color: #408080; font-style: italic } /* Comment */ +body .err { border: 1px solid #FF0000 } /* Error */ +body .k { color: #954121 } /* Keyword */ +body .o { color: #666666 } /* Operator */ +body .cm { color: #408080; font-style: italic } /* Comment.Multiline */ +body .cp { color: #BC7A00 } /* Comment.Preproc */ +body .c1 { color: #408080; font-style: italic } /* Comment.Single */ +body .cs { color: #408080; font-style: italic } /* Comment.Special */ +body .gd { color: #A00000 } /* Generic.Deleted */ +body .ge { font-style: italic } /* Generic.Emph */ +body .gr { color: #FF0000 } /* Generic.Error */ +body .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +body .gi { color: #00A000 } /* Generic.Inserted */ +body .go { color: #808080 } /* Generic.Output */ +body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +body .gs { font-weight: bold } /* Generic.Strong */ +body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +body .gt { color: #0040D0 } /* Generic.Traceback */ +body .kc { color: #954121 } /* Keyword.Constant */ +body .kd { color: #954121; font-weight: bold } /* Keyword.Declaration */ +body .kn { color: #954121; font-weight: bold } /* Keyword.Namespace */ +body .kp { color: #954121 } /* Keyword.Pseudo */ +body .kr { color: #954121; font-weight: bold } /* Keyword.Reserved */ +body .kt { color: #B00040 } /* Keyword.Type */ +body .m { color: #666666 } /* Literal.Number */ +body .s { color: #219161 } /* Literal.String */ +body .na { color: #7D9029 } /* Name.Attribute */ +body .nb { color: #954121 } /* Name.Builtin */ +body .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +body .no { color: #880000 } /* Name.Constant */ +body .nd { color: #AA22FF } /* Name.Decorator */ +body .ni { color: #999999; font-weight: bold } /* Name.Entity */ +body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */ +body .nf { color: #0000FF } /* Name.Function */ +body .nl { color: #A0A000 } /* Name.Label */ +body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +body .nt { color: #954121; font-weight: bold } /* Name.Tag */ +body .nv { color: #19469D } /* Name.Variable */ +body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +body .w { color: #bbbbbb } /* Text.Whitespace */ +body .mf { color: #666666 } /* Literal.Number.Float */ +body .mh { color: #666666 } /* Literal.Number.Hex */ +body .mi { color: #666666 } /* Literal.Number.Integer */ +body .mo { color: #666666 } /* Literal.Number.Oct */ +body .sb { color: #219161 } /* Literal.String.Backtick */ +body .sc { color: #219161 } /* Literal.String.Char */ +body .sd { color: #219161; font-style: italic } /* Literal.String.Doc */ +body .s2 { color: #219161 } /* Literal.String.Double */ +body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ +body .sh { color: #219161 } /* Literal.String.Heredoc */ +body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ +body .sx { color: #954121 } /* Literal.String.Other */ +body .sr { color: #BB6688 } /* Literal.String.Regex */ +body .s1 { color: #219161 } /* Literal.String.Single */ +body .ss { color: #19469D } /* Literal.String.Symbol */ +body .bp { color: #954121 } /* Name.Builtin.Pseudo */ +body .vc { color: #19469D } /* Name.Variable.Class */ +body .vg { color: #19469D } /* Name.Variable.Global */ +body .vi { color: #19469D } /* Name.Variable.Instance */ +body .il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/docs/underscore.html b/docs/underscore.html new file mode 100644 index 000000000..3420f7b37 --- /dev/null +++ b/docs/underscore.html @@ -0,0 +1,417 @@ + underscore.js

underscore.js

# 
(c) 2010 Jeremy Ashkenas, DocumentCloud Inc.
+Underscore is freely distributable under the terms of the MIT license.
+Portions of Underscore are inspired by or borrowed from Prototype.js,
+Oliver Steele's Functional, and John Resig's Micro-Templating.
+For all details and documentation:
+http://documentcloud.github.com/underscore
+
 
(function() {
#

Baseline setup

 
             		           
                               
                            
                 #               
               
Establish the root object, window in the browser, or global on the server.
             		                            
  var root = this;
             		           
                               
                            
                 #               
               
Save the previous value of the _ variable.
             		                            
  var previousUnderscore = root._;
             		           
                               
                            
                 #               
               
Establish the object that gets thrown to break out of a loop iteration.
             		                            
  var breaker = typeof StopIteration !== 'undefined' ? StopIteration : '__break__';
             		           
                               
                            
                 #               
               
Quick regexp-escaping function, because JS doesn't have a RegExp.escape().
             		                            
  var escapeRegExp = function(s) { return s.replace(/([.*+?^${}()|[\]\/\\])/g, '\\$1'); };
             		           
                               
                            
                 #               
               
Save bytes in the minified (but not gzipped) version:
             		                            
  var ArrayProto = Array.prototype, ObjProto = Object.prototype;
             		           
                               
                            
                 #               
               
Create quick reference variables for speed access to core prototypes.
             		                            
  var slice                 = ArrayProto.slice,
+      unshift               = ArrayProto.unshift,
+      toString              = ObjProto.toString,
+      hasOwnProperty        = ObjProto.hasOwnProperty,
+      propertyIsEnumerable  = ObjProto.propertyIsEnumerable;
             		           
                               
                            
                 #               
               
All ECMA5 native implementations we hope to use are declared here.
             		                            
  var
+    nativeForEach      = ArrayProto.forEach,
+    nativeMap          = ArrayProto.map,
+    nativeReduce       = ArrayProto.reduce,
+    nativeReduceRight  = ArrayProto.reduceRight,
+    nativeFilter       = ArrayProto.filter,
+    nativeEvery        = ArrayProto.every,
+    nativeSome         = ArrayProto.some,
+    nativeIndexOf      = ArrayProto.indexOf,
+    nativeLastIndexOf  = ArrayProto.lastIndexOf,
+    nativeIsArray      = Array.isArray,
+    nativeKeys         = Object.keys;
             		           
                               
                            
                 #               
               
Create a safe reference to the Underscore object for use below.
             		                            
  var _ = function(obj) { return new wrapper(obj); };
             		           
                               
                            
                 #               
               
Export the Underscore object for CommonJS.
             		                            
  if (typeof exports !== 'undefined') exports._ = _;
             		           
                               
                            
                 #               
               
Export Underscore to global scope.
             		                            
  root._ = _;
             		           
                               
                            
                 #               
               
Current version.
             		                            
  _.VERSION = '1.1.0';
             		           
                               
                            
                 #               
               
Collection Functions
             		                            
             		           
                               
                            
                 #               
               
The cornerstone, an each implementation.
+Handles objects implementing forEach, arrays, and raw objects.
+Delegates to JavaScript 1.6's native forEach if available.
             		                            
  var each = _.forEach = function(obj, iterator, context) {
+    try {
+      if (nativeForEach && obj.forEach === nativeForEach) {
+        obj.forEach(iterator, context);
+      } else if (_.isNumber(obj.length)) {
+        for (var i = 0, l = obj.length; i < l; i++) iterator.call(context, obj[i], i, obj);
+      } else {
+        for (var key in obj) {
+          if (hasOwnProperty.call(obj, key)) iterator.call(context, obj[key], key, obj);
+        }
+      }
+    } catch(e) {
+      if (e != breaker) throw e;
+    }
+    return obj;
+  };
             		           
                               
                            
                 #               
               
Return the results of applying the iterator to each element.
+Delegates to JavaScript 1.6's native map if available.
             		                            
  _.map = function(obj, iterator, context) {
+    if (nativeMap && obj.map === nativeMap) return obj.map(iterator, context);
+    var results = [];
+    each(obj, function(value, index, list) {
+      results[results.length] = iterator.call(context, value, index, list);
+    });
+    return results;
+  };
             		           
                               
                            
                 #               
               
Reduce builds up a single result from a list of values, aka inject,
+or foldl. Delegates to JavaScript 1.8's native reduce if available.
             		                            
  _.reduce = function(obj, iterator, memo, context) {
+    if (nativeReduce && obj.reduce === nativeReduce) {
+      if (context) iterator = _.bind(iterator, context);
+      return obj.reduce(iterator, memo);
+    }
+    each(obj, function(value, index, list) {
+      memo = iterator.call(context, memo, value, index, list);
+    });
+    return memo;
+  };
             		           
                               
                            
                 #               
               
The right-associative version of reduce, also known as foldr. Uses
+Delegates to JavaScript 1.8's native reduceRight if available.
             		                            
  _.reduceRight = function(obj, iterator, memo, context) {
+    if (nativeReduceRight && obj.reduceRight === nativeReduceRight) {
+      if (context) iterator = _.bind(iterator, context);
+      return obj.reduceRight(iterator, memo);
+    }
+    var reversed = _.clone(_.toArray(obj)).reverse();
+    return _.reduce(reversed, iterator, memo, context);
+  };
             		           
                               
                            
                 #               
               
Return the first value which passes a truth test.
             		                            
  _.detect = function(obj, iterator, context) {
+    var result;
+    each(obj, function(value, index, list) {
+      if (iterator.call(context, value, index, list)) {
+        result = value;
+        _.breakLoop();
+      }
+    });
+    return result;
+  };
             		           
                               
                            
                 #               
               
Return all the elements that pass a truth test.
+Delegates to JavaScript 1.6's native filter if available.
             		                            
  _.filter = function(obj, iterator, context) {
+    if (nativeFilter && obj.filter === nativeFilter) return obj.filter(iterator, context);
+    var results = [];
+    each(obj, function(value, index, list) {
+      if (iterator.call(context, value, index, list)) results[results.length] = value;
+    });
+    return results;
+  };
             		           
                               
                            
                 #               
               
Return all the elements for which a truth test fails.
             		                            
  _.reject = function(obj, iterator, context) {
+    var results = [];
+    each(obj, function(value, index, list) {
+      if (!iterator.call(context, value, index, list)) results[results.length] = value;
+    });
+    return results;
+  };
             		           
                               
                            
                 #               
               
Determine whether all of the elements match a truth test.
+Delegates to JavaScript 1.6's native every if available.
             		                            
  _.every = function(obj, iterator, context) {
+    iterator = iterator || _.identity;
+    if (nativeEvery && obj.every === nativeEvery) return obj.every(iterator, context);
+    var result = true;
+    each(obj, function(value, index, list) {
+      if (!(result = result && iterator.call(context, value, index, list))) _.breakLoop();
+    });
+    return result;
+  };
             		           
                               
                            
                 #               
               
Determine if at least one element in the object matches a truth test.
+Delegates to JavaScript 1.6's native some if available.
             		                            
  _.some = function(obj, iterator, context) {
+    iterator = iterator || _.identity;
+    if (nativeSome && obj.some === nativeSome) return obj.some(iterator, context);
+    var result = false;
+    each(obj, function(value, index, list) {
+      if (result = iterator.call(context, value, index, list)) _.breakLoop();
+    });
+    return result;
+  };
             		           
                               
                            
                 #               
               
Determine if a given value is included in the array or object using '==='.
             		                            
  _.include = function(obj, target) {
+    if (nativeIndexOf && obj.indexOf === nativeIndexOf) return obj.indexOf(target) != -1;
+    var found = false;
+    each(obj, function(value) {
+      if (found = value === target) _.breakLoop();
+    });
+    return found;
+  };
             		           
                               
                            
                 #               
               
Invoke a method with arguments on every item in a collection.
             		                            
  _.invoke = function(obj, method) {
+    var args = _.rest(arguments, 2);
+    return _.map(obj, function(value) {
+      return (method ? value[method] : value).apply(value, args);
+    });
+  };
             		           
                               
                            
                 #               
               
Convenience version of a common use case of map: fetching a property.
             		                            
  _.pluck = function(obj, key) {
+    return _.map(obj, function(value){ return value[key]; });
+  };
             		           
                               
                            
                 #               
               
Return the maximum item or (item-based computation).
             		                            
  _.max = function(obj, iterator, context) {
+    if (!iterator && _.isArray(obj)) return Math.max.apply(Math, obj);
+    var result = {computed : -Infinity};
+    each(obj, function(value, index, list) {
+      var computed = iterator ? iterator.call(context, value, index, list) : value;
+      computed >= result.computed && (result = {value : value, computed : computed});
+    });
+    return result.value;
+  };
             		           
                               
                            
                 #               
               
Return the minimum element (or element-based computation).
             		                            
  _.min = function(obj, iterator, context) {
+    if (!iterator && _.isArray(obj)) return Math.min.apply(Math, obj);
+    var result = {computed : Infinity};
+    each(obj, function(value, index, list) {
+      var computed = iterator ? iterator.call(context, value, index, list) : value;
+      computed < result.computed && (result = {value : value, computed : computed});
+    });
+    return result.value;
+  };
             		           
                               
                            
                 #               
               
Sort the object's values by a criterion produced by an iterator.
             		                            
  _.sortBy = function(obj, iterator, context) {
+    return _.pluck(_.map(obj, function(value, index, list) {
+      return {
+        value : value,
+        criteria : iterator.call(context, value, index, list)
+      };
+    }).sort(function(left, right) {
+      var a = left.criteria, b = right.criteria;
+      return a < b ? -1 : a > b ? 1 : 0;
+    }), 'value');
+  };
             		           
                               
                            
                 #               
               
Use a comparator function to figure out at what index an object should
+be inserted so as to maintain order. Uses binary search.
             		                            
  _.sortedIndex = function(array, obj, iterator) {
+    iterator = iterator || _.identity;
+    var low = 0, high = array.length;
+    while (low < high) {
+      var mid = (low + high) >> 1;
+      iterator(array[mid]) < iterator(obj) ? low = mid + 1 : high = mid;
+    }
+    return low;
+  };
             		           
                               
                            
                 #               
               
Convert anything iterable into a real, live array.
             		                            
  _.toArray = function(iterable) {
+    if (!iterable)                return [];
+    if (iterable.toArray)         return iterable.toArray();
+    if (_.isArray(iterable))      return iterable;
+    if (_.isArguments(iterable))  return slice.call(iterable);
+    return _.values(iterable);
+  };
             		           
                               
                            
                 #               
               
Return the number of elements in an object.
             		                            
  _.size = function(obj) {
+    return _.toArray(obj).length;
+  };
             		           
                               
                            
                 #               
               
Array Functions
             		                            
             		           
                               
                            
                 #               
               
Get the first element of an array. Passing "n" will return the first N
+values in the array. Aliased as "head". The "guard" check allows it to work
+with _.map.
             		                            
  _.first = function(array, n, guard) {
+    return n && !guard ? slice.call(array, 0, n) : array[0];
+  };
             		           
                               
                            
                 #               
               
Returns everything but the first entry of the array. Aliased as "tail".
+Especially useful on the arguments object. Passing an "index" will return
+the rest of the values in the array from that index onward. The "guard"
+check allows it to work with _.map.
             		                            
  _.rest = function(array, index, guard) {
+    return slice.call(array, _.isUndefined(index) || guard ? 1 : index);
+  };
             		           
                               
                            
                 #               
               
Get the last element of an array.
             		                            
  _.last = function(array) {
+    return array[array.length - 1];
+  };
             		           
                               
                            
                 #               
               
Trim out all falsy values from an array.
             		                            
  _.compact = function(array) {
+    return _.filter(array, function(value){ return !!value; });
+  };
             		           
                               
                            
                 #               
               
Return a completely flattened version of an array.
             		                            
  _.flatten = function(array) {
+    return _.reduce(array, function(memo, value) {
+      if (_.isArray(value)) return memo.concat(_.flatten(value));
+      memo[memo.length] = value;
+      return memo;
+    }, []);
+  };
             		           
                               
                            
                 #               
               
Return a version of the array that does not contain the specified value(s).
             		                            
  _.without = function(array) {
+    var values = _.rest(arguments);
+    return _.filter(array, function(value){ return !_.include(values, value); });
+  };
             		           
                               
                            
                 #               
               
Produce a duplicate-free version of the array. If the array has already
+been sorted, you have the option of using a faster algorithm.
             		                            
  _.uniq = function(array, isSorted) {
+    return _.reduce(array, function(memo, el, i) {
+      if (0 == i || (isSorted === true ? _.last(memo) != el : !_.include(memo, el))) memo[memo.length] = el;
+      return memo;
+    }, []);
+  };
             		           
                               
                            
                 #               
               
Produce an array that contains every item shared between all the
+passed-in arrays.
             		                            
  _.intersect = function(array) {
+    var rest = _.rest(arguments);
+    return _.filter(_.uniq(array), function(item) {
+      return _.every(rest, function(other) {
+        return _.indexOf(other, item) >= 0;
+      });
+    });
+  };
             		           
                               
                            
                 #               
               
Zip together multiple lists into a single array -- elements that share
+an index go together.
             		                            
  _.zip = function() {
+    var args = _.toArray(arguments);
+    var length = _.max(_.pluck(args, 'length'));
+    var results = new Array(length);
+    for (var i = 0; i < length; i++) results[i] = _.pluck(args, "" + i);
+    return results;
+  };
             		           
                               
                            
                 #               
               
If the browser doesn't supply us with indexOf (I'm looking at you, MSIE),
+we need this function. Return the position of the first occurence of an
+item in an array, or -1 if the item is not included in the array.
+Delegates to JavaScript 1.8's native indexOf if available.
             		                            
  _.indexOf = function(array, item) {
+    if (nativeIndexOf && array.indexOf === nativeIndexOf) return array.indexOf(item);
+    for (var i = 0, l = array.length; i < l; i++) if (array[i] === item) return i;
+    return -1;
+  };
             		           
                               
                            
                 #               
               
Delegates to JavaScript 1.6's native lastIndexOf if available.
             		                            
  _.lastIndexOf = function(array, item) {
+    if (nativeLastIndexOf && array.lastIndexOf === nativeLastIndexOf) return array.lastIndexOf(item);
+    var i = array.length;
+    while (i--) if (array[i] === item) return i;
+    return -1;
+  };
             		           
                               
                            
                 #               
               
Generate an integer Array containing an arithmetic progression. A port of
+the native Python range() function. See:
+http://docs.python.org/library/functions.html#range
             		                            
  _.range = function(start, stop, step) {
+    var a     = _.toArray(arguments);
+    var solo  = a.length <= 1;
+    var start = solo ? 0 : a[0], stop = solo ? a[0] : a[1], step = a[2] || 1;
+    var len   = Math.ceil((stop - start) / step);
+    if (len <= 0) return [];
+    var range = new Array(len);
+    for (var i = start, idx = 0; true; i += step) {
+      if ((step > 0 ? i - stop : stop - i) >= 0) return range;
+      range[idx++] = i;
+    }
+  };
             		           
                               
                            
                 #               
               
Function Functions
             		                            
             		           
                               
                            
                 #               
               
Create a function bound to a given object (assigning 'this', and arguments,
+optionally). Binding with arguments is also known as 'curry'.
             		                            
  _.bind = function(func, obj) {
+    var args = _.rest(arguments, 2);
+    return function() {
+      return func.apply(obj || {}, args.concat(_.toArray(arguments)));
+    };
+  };
             		           
                               
                            
                 #               
               
Bind all of an object's methods to that object. Useful for ensuring that
+all callbacks defined on an object belong to it.
             		                            
  _.bindAll = function(obj) {
+    var funcs = _.rest(arguments);
+    if (funcs.length == 0) funcs = _.functions(obj);
+    each(funcs, function(f) { obj[f] = _.bind(obj[f], obj); });
+    return obj;
+  };
             		           
                               
                            
                 #               
               
Memoize an expensive function by storing its results.
             		                            
  _.memoize = function(func, hasher) {
+    var memo = {};
+    hasher = hasher || _.identity;
+    return function() {
+      var key = hasher.apply(this, arguments);
+      return key in memo ? memo[key] : (memo[key] = func.apply(this, arguments));
+    };
+  };
             		           
                               
                            
                 #               
               
Delays a function for the given number of milliseconds, and then calls
+it with the arguments supplied.
             		                            
  _.delay = function(func, wait) {
+    var args = _.rest(arguments, 2);
+    return setTimeout(function(){ return func.apply(func, args); }, wait);
+  };
             		           
                               
                            
                 #               
               
Defers a function, scheduling it to run after the current call stack has
+cleared.
             		                            
  _.defer = function(func) {
+    return _.delay.apply(_, [func, 1].concat(_.rest(arguments)));
+  };
             		           
                               
                            
                 #               
               
Returns the first function passed as an argument to the second,
+allowing you to adjust arguments, run code before and after, and
+conditionally execute the original function.
             		                            
  _.wrap = function(func, wrapper) {
+    return function() {
+      var args = [func].concat(_.toArray(arguments));
+      return wrapper.apply(wrapper, args);
+    };
+  };
             		           
                               
                            
                 #               
               
Returns a function that is the composition of a list of functions, each
+consuming the return value of the function that follows.
             		                            
  _.compose = function() {
+    var funcs = _.toArray(arguments);
+    return function() {
+      var args = _.toArray(arguments);
+      for (var i=funcs.length-1; i >= 0; i--) {
+        args = [funcs[i].apply(this, args)];
+      }
+      return args[0];
+    };
+  };
             		           
                               
                            
                 #               
               
Object Functions
             		                            
             		           
                               
                            
                 #               
               
Retrieve the names of an object's properties.
+Delegates to ECMA5's native Object.keys
             		                            
  _.keys = nativeKeys || function(obj) {
+    if (_.isArray(obj)) return _.range(0, obj.length);
+    var keys = [];
+    for (var key in obj) if (hasOwnProperty.call(obj, key)) keys[keys.length] = key;
+    return keys;
+  };
             		           
                               
                            
                 #               
               
Retrieve the values of an object's properties.
             		                            
  _.values = function(obj) {
+    return _.map(obj, _.identity);
+  };
             		           
                               
                            
                 #               
               
Return a sorted list of the function names available on the object.
             		                            
  _.functions = function(obj) {
+    return _.filter(_.keys(obj), function(key){ return _.isFunction(obj[key]); }).sort();
+  };
             		           
                               
                            
                 #               
               
Extend a given object with all the properties in passed-in object(s).
             		                            
  _.extend = function(obj) {
+    each(_.rest(arguments), function(source) {
+      for (var prop in source) obj[prop] = source[prop];
+    });
+    return obj;
+  };
             		           
                               
                            
                 #               
               
Create a (shallow-cloned) duplicate of an object.
             		                            
  _.clone = function(obj) {
+    if (_.isArray(obj)) return obj.slice(0);
+    return _.extend({}, obj);
+  };
             		           
                               
                            
                 #               
               
Invokes interceptor with the obj, and then returns obj.
+The primary purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain.
             		                            
  _.tap = function(obj, interceptor) {
+    interceptor(obj);
+    return obj;
+  };
             		           
                               
                            
                 #               
               
Perform a deep comparison to check if two objects are equal.
             		                            
  _.isEqual = function(a, b) {
             		           
                               
                            
                 #               
               
Check object identity.
             		                            
    if (a === b) return true;
             		           
                               
                            
                 #               
               
Different types?
             		                            
    var atype = typeof(a), btype = typeof(b);
+    if (atype != btype) return false;
             		           
                               
                            
                 #               
               
Basic equality test (watch out for coercions).
             		                            
    if (a == b) return true;
             		           
                               
                            
                 #               
               
One is falsy and the other truthy.
             		                            
    if ((!a && b) || (a && !b)) return false;
             		           
                               
                            
                 #               
               
One of them implements an isEqual()?
             		                            
    if (a.isEqual) return a.isEqual(b);
             		           
                               
                            
                 #               
               
Check dates' integer values.
             		                            
    if (_.isDate(a) && _.isDate(b)) return a.getTime() === b.getTime();
             		           
                               
                            
                 #               
               
Both are NaN?
             		                            
    if (_.isNaN(a) && _.isNaN(b)) return false;
             		           
                               
                            
                 #               
               
Compare regular expressions.
             		                            
    if (_.isRegExp(a) && _.isRegExp(b))
+      return a.source     === b.source &&
+             a.global     === b.global &&
+             a.ignoreCase === b.ignoreCase &&
+             a.multiline  === b.multiline;
             		           
                               
                            
                 #               
               
If a is not an object by this point, we can't handle it.
             		                            
    if (atype !== 'object') return false;
             		           
                               
                            
                 #               
               
Check for different array lengths before comparing contents.
             		                            
    if (a.length && (a.length !== b.length)) return false;
             		           
                               
                            
                 #               
               
Nothing else worked, deep compare the contents.
             		                            
    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 (!(key in b) || !_.isEqual(a[key], b[key])) return false;
+    return true;
+  };
             		           
                               
                            
                 #               
               
Is a given array or object empty?
             		                            
  _.isEmpty = function(obj) {
+    if (_.isArray(obj) || _.isString(obj)) return obj.length === 0;
+    for (var key in obj) if (hasOwnProperty.call(obj, key)) return false;
+    return true;
+  };
             		           
                               
                            
                 #               
               
Is a given value a DOM element?
             		                            
  _.isElement = function(obj) {
+    return !!(obj && obj.nodeType == 1);
+  };
             		           
                               
                            
                 #               
               
Is a given value an array?
+Delegates to ECMA5's native Array.isArray
             		                            
  _.isArray = nativeIsArray || function(obj) {
+    return !!(obj && obj.concat && obj.unshift && !obj.callee);
+  };
             		           
                               
                            
                 #               
               
Is a given variable an arguments object?
             		                            
  _.isArguments = function(obj) {
+    return !!(obj && obj.callee);
+  };
             		           
                               
                            
                 #               
               
Is a given value a function?
             		                            
  _.isFunction = function(obj) {
+    return !!(obj && obj.constructor && obj.call && obj.apply);
+  };
             		           
                               
                            
                 #               
               
Is a given value a string?
             		                            
  _.isString = function(obj) {
+    return !!(obj === '' || (obj && obj.charCodeAt && obj.substr));
+  };
             		           
                               
                            
                 #               
               
Is a given value a number?
             		                            
  _.isNumber = function(obj) {
+    return (obj === +obj) || (toString.call(obj) === '[object Number]');
+  };
             		           
                               
                            
                 #               
               
Is a given value a boolean?
             		                            
  _.isBoolean = function(obj) {
+    return obj === true || obj === false;
+  };
             		           
                               
                            
                 #               
               
Is a given value a date?
             		                            
  _.isDate = function(obj) {
+    return !!(obj && obj.getTimezoneOffset && obj.setUTCFullYear);
+  };
             		           
                               
                            
                 #               
               
Is the given value a regular expression?
             		                            
  _.isRegExp = function(obj) {
+    return !!(obj && obj.test && obj.exec && (obj.ignoreCase || obj.ignoreCase === false));
+  };
             		           
                               
                            
                 #               
               
Is the given value NaN -- this one is interesting. NaN != NaN, and
+isNaN(undefined) == true, so we make sure it's a number first.
             		                            
  _.isNaN = function(obj) {
+    return _.isNumber(obj) && isNaN(obj);
+  };
             		           
                               
                            
                 #               
               
Is a given value equal to null?
             		                            
  _.isNull = function(obj) {
+    return obj === null;
+  };
             		           
                               
                            
                 #               
               
Is a given variable undefined?
             		                            
  _.isUndefined = function(obj) {
+    return typeof obj == 'undefined';
+  };
             		           
                               
                            
                 #               
               
Utility Functions
             		                            
             		           
                               
                            
                 #               
               
Run Underscore.js in noConflict mode, returning the '_' variable to its
+previous owner. Returns a reference to the Underscore object.
             		                            
  _.noConflict = function() {
+    root._ = previousUnderscore;
+    return this;
+  };
             		           
                               
                            
                 #               
               
Keep the identity function around for default iterators.
             		                            
  _.identity = function(value) {
+    return value;
+  };
             		           
                               
                            
                 #               
               
Run a function n times.
             		                            
  _.times = function (n, iterator, context) {
+    for (var i = 0; i < n; i++) iterator.call(context, i);
+  };
             		           
                               
                            
                 #               
               
Break out of the middle of an iteration.
             		                            
  _.breakLoop = function() {
+    throw breaker;
+  };
             		           
                               
                            
                 #               
               
Add your own custom functions to the Underscore object, ensuring that
+they're correctly added to the OOP wrapper as well.
             		                            
  _.mixin = function(obj) {
+    each(_.functions(obj), function(name){
+      addToWrapper(name, _[name] = obj[name]);
+    });
+  };
             		           
                               
                            
                 #               
               
Generate a unique integer id (unique within the entire client session).
+Useful for temporary DOM ids.
             		                            
  var idCounter = 0;
+  _.uniqueId = function(prefix) {
+    var id = idCounter++;
+    return prefix ? prefix + id : id;
+  };
             		           
                               
                            
                 #               
               
By default, Underscore uses ERB-style template delimiters, change the
+following template settings to use alternative delimiters.
             		                            
  _.templateSettings = {
+    evaluate    : /<%(.+?)%>/g,
+    interpolate : /<%=(.+?)%>/g
+  };
             		           
                               
                            
                 #               
               
JavaScript templating a-la ERB, pilfered from John Resig's
+"Secrets of the JavaScript Ninja", page 83.
+Single-quote fix from Rick Strahl's version.
+With alterations for arbitrary delimiters, and to preserve whitespace.
             		                            
  _.template = function(str, data) {
+    var c  = _.templateSettings;
+    var tmpl = 'var __p=[],print=function(){__p.push.apply(__p,arguments);};' +
+      'with(obj||{}){__p.push(\'' +
+      str.replace(/'/g, "\\'")
+         .replace(c.interpolate, function(match, code) {
+           return "'," + code.replace(/\\'/g, "'") + ",'";
+         })
+         .replace(c.evaluate || null, function(match, code) {
+           return "');" + code.replace(/\\'/g, "'")
+                              .replace(/[\r\n\t]/g, ' ') + "__p.push('";
+         })
+         .replace(/\r/g, '\\r')
+         .replace(/\n/g, '\\n')
+         .replace(/\t/g, '\\t')
+         + "');}return __p.join('');";
+    var func = new Function('obj', tmpl);
+    return data ? func(data) : func;
+  };
             		           
                               
                            
                 #               
               
Aliases:
             		                            
  _.each     = _.forEach;
+  _.foldl    = _.inject       = _.reduce;
+  _.foldr    = _.reduceRight;
+  _.select   = _.filter;
+  _.all      = _.every;
+  _.any      = _.some;
+  _.contains = _.include;
+  _.head     = _.first;
+  _.tail     = _.rest;
+  _.methods  = _.functions;
             		           
                               
                            
                 #               
               
The OOP Wrapper
             		                            
             		           
                               
                            
                 #               
               
If Underscore is called as a function, it returns a wrapped object that
+can be used OO-style. This wrapper holds altered versions of all the
+underscore functions. Wrapped objects may be chained.
             		                            
  var wrapper = function(obj) { this._wrapped = obj; };
             		           
                               
                            
                 #               
               
Helper function to continue chaining intermediate results.
             		                            
  var result = function(obj, chain) {
+    return chain ? _(obj).chain() : obj;
+  };
             		           
                               
                            
                 #               
               
A method to easily add functions to the OOP wrapper.
             		                            
  var addToWrapper = function(name, func) {
+    wrapper.prototype[name] = function() {
+      var args = _.toArray(arguments);
+      unshift.call(args, this._wrapped);
+      return result(func.apply(_, args), this._chain);
+    };
+  };
             		           
                               
                            
                 #               
               
Add all of the Underscore functions to the wrapper object.
             		                            
  _.mixin(_);
             		           
                               
                            
                 #               
               
Add all mutator Array functions to the wrapper.
             		                            
  each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) {
+    var method = ArrayProto[name];
+    wrapper.prototype[name] = function() {
+      method.apply(this._wrapped, arguments);
+      return result(this._wrapped, this._chain);
+    };
+  });
             		           
                               
                            
                 #               
               
Add all accessor Array functions to the wrapper.
             		                            
  each(['concat', 'join', 'slice'], function(name) {
+    var method = ArrayProto[name];
+    wrapper.prototype[name] = function() {
+      return result(method.apply(this._wrapped, arguments), this._chain);
+    };
+  });
             		           
                               
                            
                 #               
               
Start chaining a wrapped Underscore object.
             		                            
  wrapper.prototype.chain = function() {
+    this._chain = true;
+    return this;
+  };
             		           
                               
                            
                 #               
               
Extracts the result from a wrapped and chained object.
             		                            
  wrapper.prototype.value = function() {
+    return this._wrapped;
+  };
+
+})();
+
+
             		           
                     
   
   
\ No newline at end of file
diff --git a/underscore.js b/underscore.js
index 36100bdde..31b769950 100644
--- a/underscore.js
+++ b/underscore.js
@@ -1,24 +1,25 @@
-// Underscore.js
-// (c) 2010 Jeremy Ashkenas, DocumentCloud Inc.
-// Underscore is freely distributable under the terms of the MIT license.
-// Portions of Underscore are inspired by or borrowed from Prototype.js,
-// Oliver Steele's Functional, and John Resig's Micro-Templating.
-// For all details and documentation:
-// http://documentcloud.github.com/underscore
+//     (c) 2010 Jeremy Ashkenas, DocumentCloud Inc.
+//     Underscore is freely distributable under the terms of the MIT license.
+//     Portions of Underscore are inspired by or borrowed from Prototype.js,
+//     Oliver Steele's Functional, and John Resig's Micro-Templating.
+//     For all details and documentation:
+//     http://documentcloud.github.com/underscore
 
 (function() {
-  // ------------------------- Baseline setup ---------------------------------
 
-  // Establish the root object, "window" in the browser, or "global" on the server.
+  // Baseline setup
+  // --------------
+
+  // Establish the root object, `window` in the browser, or `global` on the server.
   var root = this;
 
-  // Save the previous value of the "_" variable.
+  // Save the previous value of the `_` variable.
   var previousUnderscore = root._;
 
   // Establish the object that gets thrown to break out of a loop iteration.
   var breaker = typeof StopIteration !== 'undefined' ? StopIteration : '__break__';
 
-  // Quick regexp-escaping function, because JS doesn't have RegExp.escape().
+  // Quick regexp-escaping function, because JS doesn't have a `RegExp.escape()`.
   var escapeRegExp = function(s) { return s.replace(/([.*+?^${}()|[\]\/\\])/g, '\\$1'); };
 
   // Save bytes in the minified (but not gzipped) version:
@@ -48,20 +49,21 @@
   // Create a safe reference to the Underscore object for use below.
   var _ = function(obj) { return new wrapper(obj); };
 
-  // Export the Underscore object for CommonJS.
+  // Export the Underscore object for **CommonJS**.
   if (typeof exports !== 'undefined') exports._ = _;
 
-  // Export underscore to global scope.
+  // Export Underscore to global scope.
   root._ = _;
 
   // Current version.
   _.VERSION = '1.1.0';
 
-  // ------------------------ Collection Functions: ---------------------------
+  // Collection Functions
+  // --------------------
 
   // The cornerstone, an each implementation.
-  // Handles objects implementing forEach, arrays, and raw objects.
-  // Delegates to JavaScript 1.6's native forEach if available.
+  // Handles objects implementing `forEach`, arrays, and raw objects.
+  // Delegates to JavaScript 1.6's native `forEach` if available.
   var each = _.forEach = function(obj, iterator, context) {
     try {
       if (nativeForEach && obj.forEach === nativeForEach) {
@@ -80,7 +82,7 @@
   };
 
   // Return the results of applying the iterator to each element.
-  // Delegates to JavaScript 1.6's native map if available.
+  // Delegates to JavaScript 1.6's native `map` if available.
   _.map = function(obj, iterator, context) {
     if (nativeMap && obj.map === nativeMap) return obj.map(iterator, context);
     var results = [];
@@ -90,8 +92,8 @@
     return results;
   };
 
-  // Reduce builds up a single result from a list of values, aka inject, or foldl.
-  // Delegates to JavaScript 1.8's native reduce if available.
+  // **Reduce** builds up a single result from a list of values, aka `inject`,
+  // or `foldl`. Delegates to JavaScript 1.8's native `reduce` if available.
   _.reduce = function(obj, iterator, memo, context) {
     if (nativeReduce && obj.reduce === nativeReduce) {
       if (context) iterator = _.bind(iterator, context);
@@ -103,7 +105,7 @@
     return memo;
   };
 
-  // The right-associative version of reduce, also known as foldr. Uses
+  // The right-associative version of reduce, also known as `foldr`. Uses
   // Delegates to JavaScript 1.8's native reduceRight if available.
   _.reduceRight = function(obj, iterator, memo, context) {
     if (nativeReduceRight && obj.reduceRight === nativeReduceRight) {
@@ -254,7 +256,8 @@
     return _.toArray(obj).length;
   };
 
-  // -------------------------- Array Functions: ------------------------------
+  // Array Functions
+  // ---------------
 
   // Get the first element of an array. Passing "n" will return the first N
   // values in the array. Aliased as "head". The "guard" check allows it to work
@@ -361,7 +364,8 @@
     }
   };
 
-  // ----------------------- Function Functions: ------------------------------
+  // Function Functions
+  // ------------------
 
   // Create a function bound to a given object (assigning 'this', and arguments,
   // optionally). Binding with arguments is also known as 'curry'.
@@ -427,7 +431,8 @@
     };
   };
 
-  // ------------------------- Object Functions: ------------------------------
+  // Object Functions
+  // ----------------
 
   // Retrieve the names of an object's properties.
   // Delegates to ECMA5's native Object.keys
@@ -574,7 +579,8 @@
     return typeof obj == 'undefined';
   };
 
-  // -------------------------- Utility Functions: ----------------------------
+  // Utility Functions
+  // -----------------
 
   // Run Underscore.js in noConflict mode, returning the '_' variable to its
   // previous owner. Returns a reference to the Underscore object.
@@ -645,7 +651,8 @@
     return data ? func(data) : func;
   };
 
-  // ------------------------------- Aliases ----------------------------------
+  // Aliases:
+  // --------
 
   _.each     = _.forEach;
   _.foldl    = _.inject       = _.reduce;
@@ -658,7 +665,8 @@
   _.tail     = _.rest;
   _.methods  = _.functions;
 
-  // ------------------------ Setup the OOP Wrapper: --------------------------
+  // The OOP Wrapper
+  // ---------------
 
   // If Underscore is called as a function, it returns a wrapped object that
   // can be used OO-style. This wrapper holds altered versions of all the