Bump to v3.2.0.

utility/attempt.js

@@ -1,8 +1,9 @@
-var isError = require('../lang/isError');
+var baseSlice = require('../internal/baseSlice'),
+    isError = require('../lang/isError');
 
 /**
- * Attempts to invoke `func`, returning either the result or the caught
- * error object.
+ * Attempts to invoke `func`, returning either the result or the caught error
+ * object. Any additional arguments are provided to `func` when it is invoked.
  *
  * @static
  * @memberOf _
@@ -12,9 +13,9 @@ var isError = require('../lang/isError');
  * @example
  *
  * // avoid throwing errors for invalid selectors
- * var elements = _.attempt(function() {
+ * var elements = _.attempt(function(selector) {
  *   return document.querySelectorAll(selector);
- * });
+ * }, '>_>');
  *
  * if (_.isError(elements)) {
  *   elements = [];
@@ -22,9 +23,9 @@ var isError = require('../lang/isError');
  */
 function attempt(func) {
   try {
-    return func();
+    return func.apply(undefined, baseSlice(arguments, 1));
   } catch(e) {
-    return isError(e) ? e : Error(e);
+    return isError(e) ? e : new Error(e);
   }
 }
 

utility/callback.js

@@ -4,10 +4,11 @@ var baseCallback = require('../internal/baseCallback'),
     matches = require('./matches');
 
 /**
- * Creates a function bound to an optional `thisArg`. If `func` is a property
- * name the created callback returns the property value for a given element.
- * If `func` is an object the created callback returns `true` for elements
- * that contain the equivalent object properties, otherwise it returns `false`.
+ * Creates a function that invokes `func` with the `this` binding of `thisArg`
+ * and arguments of the created function. If `func` is a property name the
+ * created callback returns the property value for a given element. If `func`
+ * is an object the created callback returns `true` for elements that contain
+ * the equivalent object properties, otherwise it returns `false`.
  *
  * @static
  * @memberOf _

utility/matches.js

@@ -6,6 +6,11 @@ var baseClone = require('../internal/baseClone'),
  * and `source`, returning `true` if the given object has equivalent property
  * values, else `false`.
  *
+ * **Note:** This method supports comparing arrays, booleans, `Date` objects,
+ * numbers, `Object` objects, regexes, and strings. Objects are compared by
+ * their own, not inherited, enumerable properties. For comparing a single
+ * own or inherited property value see `_.matchesProperty`.
+ *
  * @static
  * @memberOf _
  * @category Utility
@@ -14,17 +19,12 @@ var baseClone = require('../internal/baseClone'),
  * @example
  *
  * var users = [
- *   { 'user': 'fred',   'age': 40 },
- *   { 'user': 'barney', 'age': 36 }
+ *   { 'user': 'barney', 'age': 36, 'active': true },
+ *   { 'user': 'fred',   'age': 40, 'active': false }
  * ];
  *
- * var matchesAge = _.matches({ 'age': 36 });
- *
- * _.filter(users, matchesAge);
- * // => [{ 'user': 'barney', 'age': 36 }]
- *
- * _.find(users, matchesAge);
- * // => { 'user': 'barney', 'age': 36 }
+ * _.filter(users, _.matches({ 'age': 40, 'active': false }));
+ * // => [{ 'user': 'fred', 'age': 40, 'active': false }]
  */
 function matches(source) {
   return baseMatches(baseClone(source, true));

utility/matchesProperty.js

@@ -0,0 +1,33 @@
+var baseClone = require('../internal/baseClone'),
+    baseMatchesProperty = require('../internal/baseMatchesProperty');
+
+/**
+ * Creates a function which compares the property value of `key` on a given
+ * object to `value`.
+ *
+ * **Note:** This method supports comparing arrays, booleans, `Date` objects,
+ * numbers, `Object` objects, regexes, and strings. Objects are compared by
+ * their own, not inherited, enumerable properties.
+ *
+ * @static
+ * @memberOf _
+ * @category Utility
+ * @param {string} key The key of the property to get.
+ * @param {*} value The value to compare.
+ * @returns {Function} Returns the new function.
+ * @example
+ *
+ * var users = [
+ *   { 'user': 'barney' },
+ *   { 'user': 'fred' },
+ *   { 'user': 'pebbles' }
+ * ];
+ *
+ * _.find(users, _.matchesProperty('user', 'fred'));
+ * // => { 'user': 'fred', 'age': 40 }
+ */
+function matchesProperty(key, value) {
+  return baseMatchesProperty(key + '', baseClone(value, true));
+}
+
+module.exports = matchesProperty;

utility/mixin.js

@@ -32,6 +32,9 @@ var push = arrayProto.push;
  *   });
  * }
  *
+ * // use `_.runInContext` to avoid potential conflicts (esp. in Node.js)
+ * var _ = require('lodash').runInContext();
+ *
  * _.mixin({ 'vowels': vowels });
  * _.vowels('fred');
  * // => ['e']