Rebuild docs and dist.

Former-commit-id: ae113f2c04eef7a34b1b49bca3e6dcb7402f723c

dist/lodash.compat.js

@@ -581,7 +581,6 @@
      *
      * @name _
      * @constructor
-     * @alias chain
      * @category Chaining
      * @param {Mixed} value The value to wrap in a `lodash` instance.
      * @returns {Object} Returns a `lodash` instance.
@@ -618,9 +617,11 @@
      *
      * @private
      * @param {Mixed} value The value to wrap in a `lodash` instance.
+     * @param {Boolean} chainAll A flag to enable chaining for all methods
      * @returns {Object} Returns a `lodash` instance.
      */
-    function lodashWrapper(value) {
+    function lodashWrapper(value, chainAll) {
+      this.__chain__ = !!chainAll;
       this.__wrapped__ = value;
     }
     // ensure `new lodashWrapper` is an instance of `lodash`
@@ -1605,6 +1606,7 @@
      *
      * @static
      * @memberOf _
+     * @type Function
      * @category Objects
      * @param {Mixed} value The value to check.
      * @returns {Boolean} Returns `true`, if the `value` is an array, else `false`.
@@ -1893,7 +1895,7 @@
     var defaults = createIterator(defaultsIteratorOptions);
 
     /**
-     * This method is similar to `_.find`, except that it returns the key of the
+     * This method is like `_.findIndex`, except that it returns the key of the
      * element that passes the callback check, instead of the element itself.
      *
      * @static
@@ -1910,7 +1912,7 @@
      * _.findKey({ 'a': 1, 'b': 2, 'c': 3, 'd': 4 }, function(num) {
      *   return num % 2 == 0;
      * });
-     * // => 'b'
+     * // => 'b' (order is not guaranteed)
      */
     function findKey(object, callback, thisArg) {
       var result;
@@ -1924,6 +1926,38 @@
       return result;
     }
 
+    /**
+     * This method is like `_.findKey`, except that it iterates over elements
+     * of a `collection` in the opposite order.
+     *
+     * @static
+     * @memberOf _
+     * @category Objects
+     * @param {Object} object The object to search.
+     * @param {Function|Object|String} [callback=identity] The function called per
+     *  iteration. If a property name or object is passed, it will be used to create
+     *  a "_.pluck" or "_.where" style callback, respectively.
+     * @param {Mixed} [thisArg] The `this` binding of `callback`.
+     * @returns {Mixed} Returns the key of the found element, else `undefined`.
+     * @example
+     *
+     * _.findLastKey({ 'a': 1, 'b': 2, 'c': 3, 'd': 4 }, function(num) {
+     *   return num % 2 == 1;
+     * });
+     * // => returns `c`, assuming `_.findKey` returns `a`
+     */
+    function findLastKey(object, callback, thisArg) {
+      var result;
+      callback = lodash.createCallback(callback, thisArg);
+      forOwnRight(object, function(value, key, object) {
+        if (callback(value, key, object)) {
+          result = key;
+          return false;
+        }
+      });
+      return result;
+    }
+
     /**
      * Iterates over own and inherited enumerable properties of a given `object`,
      * executing the `callback` for each property. The `callback` is bound to
@@ -1945,18 +1979,62 @@
      * }
      *
      * Dog.prototype.bark = function() {
-     *   alert('Woof, woof!');
+     *   console.log('Woof, woof!');
      * };
      *
      * _.forIn(new Dog('Dagny'), function(value, key) {
-     *   alert(key);
+     *   console.log(key);
      * });
-     * // => alerts 'name' and 'bark' (order is not guaranteed)
+     * // => logs 'bark' and 'name' (order is not guaranteed)
      */
     var forIn = createIterator(eachIteratorOptions, forOwnIteratorOptions, {
       'useHas': false
     });
 
+    /**
+     * This method is like `_.forIn`, except that it iterates over elements
+     * of a `collection` in the opposite order.
+     *
+     * @static
+     * @memberOf _
+     * @category Objects
+     * @param {Object} object The object to iterate over.
+     * @param {Function} [callback=identity] The function called per iteration.
+     * @param {Mixed} [thisArg] The `this` binding of `callback`.
+     * @returns {Object} Returns `object`.
+     * @example
+     *
+     * function Dog(name) {
+     *   this.name = name;
+     * }
+     *
+     * Dog.prototype.bark = function() {
+     *   console.log('Woof, woof!');
+     * };
+     *
+     * _.forInRight(new Dog('Dagny'), function(value, key) {
+     *   console.log(key);
+     * });
+     * // => logs 'name' and 'bark' assuming `_.forIn ` logs 'bark' and 'name'
+     */
+    function forInRight(object, callback, thisArg) {
+      var index = -1,
+          pairs = [];
+
+      forIn(object, function(value, key) {
+        pairs.push(value, key);
+      });
+
+      var length = pairs.length;
+      callback = lodash.createCallback(callback, thisArg, 3);
+      while (++index < length) {
+        if (callback(pairs[index], pairs[++index], object) === false) {
+          break;
+        }
+      }
+      return object;
+    }
+
     /**
      * Iterates over own enumerable properties of a given `object`, executing the
      * `callback` for each property. The `callback` is bound to `thisArg` and
@@ -1974,12 +2052,44 @@
      * @example
      *
      * _.forOwn({ '0': 'zero', '1': 'one', 'length': 2 }, function(num, key) {
-     *   alert(key);
+     *   console.log(key);
      * });
-     * // => alerts '0', '1', and 'length' (order is not guaranteed)
+     * // => logs '0', '1', and 'length' (order is not guaranteed)
      */
     var forOwn = createIterator(eachIteratorOptions, forOwnIteratorOptions);
 
+    /**
+     * This method is like `_.forOwn`, except that it iterates over elements
+     * of a `collection` in the opposite order.
+     *
+     * @static
+     * @memberOf _
+     * @category Objects
+     * @param {Object} object The object to iterate over.
+     * @param {Function} [callback=identity] The function called per iteration.
+     * @param {Mixed} [thisArg] The `this` binding of `callback`.
+     * @returns {Object} Returns `object`.
+     * @example
+     *
+     * _.forOwnRight({ '0': 'zero', '1': 'one', 'length': 2 }, function(num, key) {
+     *   console.log(key);
+     * });
+     * // => logs 'length', '1', and '0' assuming `_.forOwn` logs '0', '1', and 'length'
+     */
+    function forOwnRight(object, callback, thisArg) {
+      var props = keys(object),
+          length = props.length;
+
+      callback = lodash.createCallback(callback, thisArg, 3);
+      while (length--) {
+        var key = props[length];
+        if (callback(object[key], key, object) === false) {
+          break;
+        }
+      }
+      return object;
+    }
+
     /**
      * Creates a sorted array of property names of all enumerable properties,
      * own and inherited, of `object` that have function values.
@@ -3023,6 +3133,38 @@
       }
     }
 
+    /**
+     * This method is like `_.find`, except that it iterates over elements
+     * of a `collection` from right to left.
+     *
+     * @static
+     * @memberOf _
+     * @category Collections
+     * @param {Array|Object|String} collection The collection to iterate over.
+     * @param {Function|Object|String} [callback=identity] The function called per
+     *  iteration. If a property name or object is passed, it will be used to create
+     *  a "_.pluck" or "_.where" style callback, respectively.
+     * @param {Mixed} [thisArg] The `this` binding of `callback`.
+     * @returns {Mixed} Returns the found element, else `undefined`.
+     * @example
+     *
+     * _.findLast([1, 2, 3, 4], function(num) {
+     *   return num % 2 == 1;
+     * });
+     * // => 3
+     */
+    function findLast(collection, callback, thisArg) {
+      var result;
+      callback = lodash.createCallback(callback, thisArg);
+      forEachRight(collection, function(value, index, collection) {
+        if (callback(value, index, collection)) {
+          result = value;
+          return false;
+        }
+      });
+      return result;
+    }
+
     /**
      * Iterates over elements of a `collection`, executing the `callback` for
      * each element. The `callback` is bound to `thisArg` and invoked with three
@@ -3039,11 +3181,11 @@
      * @returns {Array|Object|String} Returns `collection`.
      * @example
      *
-     * _([1, 2, 3]).forEach(alert).join(',');
-     * // => alerts each number and returns '1,2,3'
+     * _([1, 2, 3]).forEach(function(num) { console.log(num); }).join(',');
+     * // => logs each number and returns '1,2,3'
      *
-     * _.forEach({ 'one': 1, 'two': 2, 'three': 3 }, alert);
-     * // => alerts each number value (order is not guaranteed)
+     * _.forEach({ 'one': 1, 'two': 2, 'three': 3 }, function(num) { console.log(num); });
+     * // => logs each number value and returns the object (order is not guaranteed)
      */
     function forEach(collection, callback, thisArg) {
       if (callback && typeof thisArg == 'undefined' && isArray(collection)) {
@@ -3061,6 +3203,41 @@
       return collection;
     }
 
+    /**
+     * This method is like `_.forEach`, except that it iterates over elements
+     * of a `collection` from right to left.
+     *
+     * @static
+     * @memberOf _
+     * @alias each
+     * @category Collections
+     * @param {Array|Object|String} collection The collection to iterate over.
+     * @param {Function} [callback=identity] The function called per iteration.
+     * @param {Mixed} [thisArg] The `this` binding of `callback`.
+     * @returns {Array|Object|String} Returns `collection`.
+     * @example
+     *
+     * _([1, 2, 3]).forEachRight(function(num) { console.log(num); }).join(',');
+     * // => logs each number from right to left and returns '3,2,1'
+     */
+    function forEachRight(collection, callback, thisArg) {
+      var iterable = collection,
+          length = collection ? collection.length : 0;
+
+      if (typeof length != 'number') {
+        var props = keys(collection);
+        length = props.length;
+      } else if (support.unindexedChars && isString(collection)) {
+        iterable = collection.split('');
+      }
+      callback = lodash.createCallback(callback, thisArg, 3);
+      forEach(collection, function(value, index, collection) {
+        index = props ? props[--length] : --length;
+        callback(iterable[index], index, collection);
+      });
+      return collection;
+    }
+
     /**
      * Creates an object composed of keys generated from the results of running
      * each element of the `collection` through the `callback`. The corresponding
@@ -3450,7 +3627,7 @@
     }
 
     /**
-     * This method is similar to `_.reduce`, except that it iterates over elements
+     * This method is like `_.reduce`, except that it iterates over elements
      * of a `collection` from right to left.
      *
      * @static
@@ -3469,22 +3646,12 @@
      * // => [4, 5, 2, 3, 0, 1]
      */
     function reduceRight(collection, callback, accumulator, thisArg) {
-      var iterable = collection,
-          length = collection ? collection.length : 0,
-          noaccum = arguments.length < 3;
-
-      if (typeof length != 'number') {
-        var props = keys(collection);
-        length = props.length;
-      } else if (support.unindexedChars && isString(collection)) {
-        iterable = collection.split('');
-      }
+      var noaccum = arguments.length < 3;
       callback = lodash.createCallback(callback, thisArg, 4);
-      forEach(collection, function(value, index, collection) {
-        index = props ? props[--length] : --length;
+      forEachRight(collection, function(value, index, collection) {
         accumulator = noaccum
-          ? (noaccum = false, iterable[index])
-          : callback(accumulator, iterable[index], index, collection);
+          ? (noaccum = false, value)
+          : callback(accumulator, value, index, collection);
       });
       return accumulator;
     }
@@ -3833,8 +4000,8 @@
     }
 
     /**
-     * This method is similar to `_.find`, except that it returns the index of
-     * the element that passes the callback check, instead of the element itself.
+     * This method is like `_.find`, except that it returns the index of the
+     * element that passes the callback check, instead of the element itself.
      *
      * @static
      * @memberOf _
@@ -3865,6 +4032,39 @@
       return -1;
     }
 
+    /**
+     * This method is like `_.findIndex`, except that it iterates over elements
+     * of a `collection` from right to left.
+     *
+     * @static
+     * @memberOf _
+     * @category Arrays
+     * @param {Array} array The array to search.
+     * @param {Function|Object|String} [callback=identity] The function called per
+     *  iteration. If a property name or object is passed, it will be used to create
+     *  a "_.pluck" or "_.where" style callback, respectively.
+     * @param {Mixed} [thisArg] The `this` binding of `callback`.
+     * @returns {Mixed} Returns the index of the found element, else `-1`.
+     * @example
+     *
+     * _.findLastIndex(['apple', 'banana', 'beet'], function(food) {
+     *   return /^b/.test(food);
+     * });
+     * // => 2
+     */
+    function findLastIndex(array, callback, thisArg) {
+      var index = -1,
+          length = array ? array.length : 0;
+
+      callback = lodash.createCallback(callback, thisArg);
+      while (length--) {
+        if (callback(array[index], index, array)) {
+          return index;
+        }
+      }
+      return -1;
+    }
+
     /**
      * Gets the first element of the `array`. If a number `n` is passed, the first
      * `n` elements of the `array` are returned. If a `callback` function is passed,
@@ -4693,12 +4893,12 @@
      *
      * var view = {
      *  'label': 'docs',
-     *  'onClick': function() { alert('clicked ' + this.label); }
+     *  'onClick': function() { console.log('clicked ' + this.label); }
      * };
      *
      * _.bindAll(view);
      * jQuery('#docs').on('click', view.onClick);
-     * // => alerts 'clicked docs', when the button is clicked
+     * // => logs 'clicked docs', when the button is clicked
      */
     function bindAll(object) {
       var funcs = arguments.length > 1 ? baseFlatten(arguments, true, false, 1) : functions(object),
@@ -4763,11 +4963,22 @@
      * @returns {Function} Returns the new composed function.
      * @example
      *
-     * var greet = function(name) { return 'hi ' + name; };
-     * var exclaim = function(statement) { return statement + '!'; };
-     * var welcome = _.compose(exclaim, greet);
-     * welcome('moe');
-     * // => 'hi moe!'
+     * var realNameMap = {
+     *   'curly': 'jerome'
+     * };
+     *
+     * var format = function(name) {
+     *   name = realNameMap[name.toLowerCase()] || name;
+     *   return name.charAt(0).toUpperCase() + name.slice(1).toLowerCase();
+     * };
+     *
+     * var greet = function(formatted) {
+     *   return 'Hiya ' + formatted + '!';
+     * };
+     *
+     * var welcome = _.compose(greet, format);
+     * welcome('curly');
+     * // => 'Hiya Jerome!'
      */
     function compose() {
       var funcs = arguments;
@@ -5019,8 +5230,8 @@
      * @returns {Number} Returns the timer id.
      * @example
      *
-     * _.defer(function() { alert('deferred'); });
-     * // returns from the function before `alert` is called
+     * _.defer(function() { console.log('deferred'); });
+     * // returns from the function before 'deferred' is logged
      */
     function defer(func) {
       var args = nativeSlice.call(arguments, 1);
@@ -5143,7 +5354,7 @@
     }
 
     /**
-     * This method is similar to `_.partial`, except that `partial` arguments are
+     * This method is like `_.partial`, except that `partial` arguments are
      * appended to those passed to the new function.
      *
      * @static
@@ -5709,6 +5920,34 @@
 
     /*--------------------------------------------------------------------------*/
 
+    /**
+     * Creates a `lodash` object that wraps the given `value`.
+     *
+     * @static
+     * @memberOf _
+     * @category Chaining
+     * @param {Mixed} value The value to wrap.
+     * @returns {Object} Returns the wrapper object.
+     * @example
+     *
+     * var stooges = [
+     *   { 'name': 'moe', 'age': 40 },
+     *   { 'name': 'larry', 'age': 50 },
+     *   { 'name': 'curly', 'age': 60 }
+     * ];
+     *
+     * var youngest = _.chain(stooges)
+     *     .sortBy(function(stooge) { return stooge.age; })
+     *     .map(function(stooge) { return stooge.name + ' is ' + stooge.age; })
+     *     .first();
+     * // => 'moe is 40'
+     */
+    function chain(value) {
+      value = new lodashWrapper(value);
+      value.__chain__ = true;
+      return value;
+    }
+
     /**
      * Invokes `interceptor` with the `value` as the first argument, and then
      * returns `value`. The purpose of this method is to "tap into" a method chain,
@@ -5724,10 +5963,10 @@
      *
      * _([1, 2, 3, 4])
      *  .filter(function(num) { return num % 2 == 0; })
-     *  .tap(alert)
+     *  .tap(function(array) { console.log(array); })
      *  .map(function(num) { return num * num; })
      *  .value();
-     * // => // [2, 4] (alerted)
+     * // => // [2, 4] (logged)
      * // => [4, 16]
      */
     function tap(value, interceptor) {
@@ -5735,6 +5974,26 @@
       return value;
     }
 
+    /**
+     * Enables method chaining on the wrapper object.
+     *
+     * @name chain
+     * @memberOf _
+     * @category Chaining
+     * @returns {Mixed} Returns the wrapper object.
+     * @example
+     *
+     * var sum = _([1, 2, 3])
+     *     .chain()
+     *     .reduce(function(sum, num) { return sum + num; })
+     *     .value()
+     * // => 6`
+     */
+    function wrapperChain() {
+      this.__chain__ = true;
+      return this;
+    }
+
     /**
      * Produces the `toString` result of the wrapped value.
      *
@@ -5777,6 +6036,7 @@
     lodash.bind = bind;
     lodash.bindAll = bindAll;
     lodash.bindKey = bindKey;
+    lodash.chain = chain;
     lodash.compact = compact;
     lodash.compose = compose;
     lodash.countBy = countBy;
@@ -5789,8 +6049,11 @@
     lodash.filter = filter;
     lodash.flatten = flatten;
     lodash.forEach = forEach;
+    lodash.forEachRight = forEachRight;
     lodash.forIn = forIn;
+    lodash.forInRight = forInRight;
     lodash.forOwn = forOwn;
+    lodash.forOwnRight = forOwnRight;
     lodash.functions = functions;
     lodash.groupBy = groupBy;
     lodash.indexBy = indexBy;
@@ -5845,10 +6108,6 @@
     // add functions to `lodash.prototype`
     mixin(lodash);
 
-    // add Underscore compat
-    lodash.chain = lodash;
-    lodash.prototype.chain = function() { return this; };
-
     /*--------------------------------------------------------------------------*/
 
     // add functions that return unwrapped values when chaining
@@ -5859,7 +6118,10 @@
     lodash.every = every;
     lodash.find = find;
     lodash.findIndex = findIndex;
+    lodash.findLast = findLast;
+    lodash.findLastIndex = findLastIndex;
     lodash.findKey = findKey;
+    lodash.findLastKey = findLastKey;
     lodash.has = has;
     lodash.identity = identity;
     lodash.indexOf = indexOf;
@@ -5909,9 +6171,14 @@
     forOwn(lodash, function(func, methodName) {
       if (!lodash.prototype[methodName]) {
         lodash.prototype[methodName] = function() {
-          var args = [this.__wrapped__];
+          var args = [this.__wrapped__],
+              chainAll = this.__chain__;
+
           push.apply(args, arguments);
-          return func.apply(lodash, args);
+          var result = func.apply(lodash, args);
+          return chainAll
+            ? new lodashWrapper(result, chainAll)
+            : result;
         };
       }
     });
@@ -5929,10 +6196,12 @@
     forOwn(lodash, function(func, methodName) {
       if (!lodash.prototype[methodName]) {
         lodash.prototype[methodName]= function(callback, thisArg) {
-          var result = func(this.__wrapped__, callback, thisArg);
-          return callback == null || (thisArg && typeof callback != 'function')
+          var chainAll = this.__chain__,
+              result = func(this.__wrapped__, callback, thisArg);
+
+          return !chainAll && (callback == null || (thisArg && typeof callback != 'function'))
             ? result
-            : new lodashWrapper(result);
+            : new lodashWrapper(result, chainAll);
         };
       }
     });
@@ -5949,6 +6218,7 @@
     lodash.VERSION = '1.3.1';
 
     // add "Chaining" functions to the wrapper
+    lodash.prototype.chain = wrapperChain;
     lodash.prototype.toString = wrapperToString;
     lodash.prototype.value = wrapperValueOf;
     lodash.prototype.valueOf = wrapperValueOf;
@@ -5957,7 +6227,12 @@
     baseEach(['join', 'pop', 'shift'], function(methodName) {
       var func = arrayRef[methodName];
       lodash.prototype[methodName] = function() {
-        return func.apply(this.__wrapped__, arguments);
+        var chainAll = this.__chain__,
+            result = func.apply(this.__wrapped__, arguments);
+
+        return chainAll
+          ? new lodashWrapper(result, chainAll)
+          : result;
       };
     });
 
@@ -5974,7 +6249,7 @@
     baseEach(['concat', 'slice', 'splice'], function(methodName) {
       var func = arrayRef[methodName];
       lodash.prototype[methodName] = function() {
-        return new lodashWrapper(func.apply(this.__wrapped__, arguments));
+        return new lodashWrapper(func.apply(this.__wrapped__, arguments), this.__chain__);
       };
     });
 
@@ -5986,13 +6261,16 @@
             isSplice = methodName == 'splice';
 
         lodash.prototype[methodName] = function() {
-          var value = this.__wrapped__,
+          var chainAll = this.__chain__,
+              value = this.__wrapped__,
               result = func.apply(value, arguments);
 
           if (value.length === 0) {
             delete value[0];
           }
-          return isSplice ? new lodashWrapper(result) : result;
+          return (chainAll || isSplice)
+            ? new lodashWrapper(result, chainAll)
+            : result;
         };
       });
     }