_.islike(obj, pattern) tests objects are like patterns

.gitignore

@@ -8,3 +8,4 @@ examples/*.css
 examples/*.html
 examples/public
 bower_components/*
+*.swp

docs/index.md

@@ -74,6 +74,7 @@ The _.contrib library currently contains a number of related capabilities, aggre
   - [underscore.util.operators](#util.operators) - functions that wrap common (or missing) JavaScript operators
   - [underscore.util.strings](#util.strings) - functions to work with strings
   - [underscore.util.trampolines](#util.trampolines) - functions to facilitate calling functions recursively without blowing the stack
+  - [underscore.comparison.islike](#comparison.islike) - a function to test objects fit simple patterns
 
 The links above are to the annotated source code.  Full-blown _.contrib documentation is in the works.  Contributors welcomed.
 

docs/underscore.comparison.islike.js.md

@@ -0,0 +1,62 @@
+### comparison.islike
+
+This is a function to check things, and particularly complex objects, fit a certain pattern. It is useful when you want to check that an argument you have received has the properties you expect.
+
+**Signature:** `_.islike(object:Any, pattern:Any)`
+
+Returns `true` if the object is like the pattern. `false` otherwise.
+
+```javascript
+_.islike(
+  {name: "James", age: 10, hobbies: ["football", "computer games", "baking"]},
+  {name: "", age: 0, hobbies: [""]}
+)
+
+```
+
+#### Basic types
+
+To specify that a value should be a string you can put an empty string in the pattern `""`. For a number use `0` and for an array use an empty array `[]`.
+
+ * `""` - stands for a string
+ * `0` - stands for a number
+ * `false` - stands for a boolean
+ * `[]` - stands for an array
+ * `Function` - stands for a function
+
+If you specify a type in the pattern then the value will be tested using `instanceof`. If you want to verify a function value (for instance a callback) you need to pass the `Function` type, since a normal `function() {}` is indistinguishable from type in Javascript. A more complex example using these follows:
+
+```javascript
+_.islike(myArgument, {
+    title: "", count: "", owner: OwnerModel, success: Function, error: Function
+});
+```
+
+#### Array types
+
+An array value can also be type checked by passing an array of types in the pattern. For example
+
+ * `_.islike([ 1, 2, 3, "hello" ], [ 0 ])` - returns false
+ * `_.islike([ 1, 2, 3, "hello", function() {} ], [ 0, "" ])` - returns false
+ * `_.islike([ 1, 2, 3, "hello" ], [ 0, "" ]}` - returns true
+ * `_.islike([ 1, 2, 3, "hello", function() {} ], [ 0, "", Function ]}` - returns true
+
+`[""]` allows an array of only strings and `["",0]` allows strings and numbers. This check is done using `typeof` so objects and arrays will fall into the same category.
+
+#### Complex nested objects
+
+Nested objects are recursively checked, so you just need to nest your pattern.
+
+This is a very complex example, probably more complex than `_.islike` is suited for, but is shows the nesting. In the example the object has a `process` property with two callback functuons and an array of numbers. It also has an `author` property which has another nested `location` property.
+
+```javascript
+_.islike(myComplexArgument,
+    title: "", age: 0, popularity: 0, available: false,
+    process: {
+        success: Function, error: Function, values: [0]
+    },
+    author: {
+        name: "", location: { country: "", city: "", postcode: "" }
+    }
+});
+```

test/comparison.islike.js

@@ -0,0 +1,82 @@
+$(document).ready(function() {
+
+  module("underscore.comparison.islike");
+
+  test("string islike string", function() {
+      ok(_.islike("hello, world", ""));
+  });
+
+  test("number islike number", function() {
+      ok(_.islike(32.4, 0));
+  });
+
+  test("boolean islike boolean", function() {
+      ok(_.islike(true, true));
+  });
+
+  test("string is not like number", function() {
+      equal(_.islike("hello", 0), false);
+  });
+
+  test("boolean is not like number", function() {
+      equal(_.islike(false, 0), false);
+  });
+
+  test("array is like array", function() {
+      ok(_.islike([1,2,3], []));
+  });
+
+  test("number array is typed like array", function() {
+      ok(_.islike([1,2,3], [0]));
+  });
+
+  test("string array is typed like array", function() {
+      ok(_.islike(["hello", "world"], [""]));
+  });
+
+  test("string array is not typed like number array", function() {
+      equal(_.islike(["hello", "world"], [0]), false);
+  });
+
+  test("object is like object", function() {
+      ok(_.islike(
+          {name: "James", age: 10, hobbies: ["football", "computer games", "baking"]},
+          {name: "", age: 0, hobbies: [""]}
+      ));
+  });
+
+  test("object is not like object", function() {
+      equal(_.islike(
+          {name: "James", age: 10, hobbies: ["football", "computer games", "baking"]},
+          {name: "", age: 0, hometown: "", hobbies: [""]}
+      ), false);
+  });
+
+  test("object is like type", function() {
+      var Type = function(){};
+
+      ok(_.islike(new Type, Type));
+  });
+
+  test("function is like Function", function() {
+      ok(_.islike(function(){}, Function));
+  });
+
+  test("function is not like function", function() {
+      equal(_.islike(function(){}, function(){}), false);
+  });
+
+  test("object with functions is like object", function() {
+      ok(_.islike(
+          {name: "James", age: 10, hobbies: ["football", "computer games", "baking"], done: function() { console.log("done");} },
+          {name: "", age: 0, hobbies: [""], done: Function}
+      ));
+  });
+
+  test("object with functions is not like object", function() {
+      equal(_.islike(
+          {name: "James", age: 10, hobbies: ["football", "computer games", "baking"], done: true},
+          {name: "", age: 0, hobbies: [""], done: Function}
+      ), false);
+  });
+});

test/index.html

@@ -24,6 +24,7 @@
   <script src="../underscore.util.trampolines.js"></script>
   <script src="../underscore.util.operators.js"></script>
   <script src="../underscore.util.strings.js"></script>
+  <script src="../underscore.comparison.islike.js"></script>
 
   <!-- contrib tests -->
   <script src="array.builders.js"></script>
@@ -40,6 +41,7 @@
   <script src="util.trampolines.js"></script>
   <script src="util.operators.js"></script>
   <script src="util.strings.js"></script>
+  <script src="comparison.islike.js"></script>
 </head>
 <body>
   <div id="qunit"></div>

underscore.comparison.islike.js

@@ -0,0 +1,67 @@
+/*
+* Tests if an object is like another. This means objects should follow the same
+* structure and arrays should contain the same types.
+*
+* E.g.
+*
+* _.islike(
+*   {name: "James", age: 10, hobbies: ["football", "computer games", "baking"]},
+*   {name: "", age: 0, hobbies: [""]}
+* )
+*/
+(function() {
+  // Establish the root object, `window` in the browser, or `require` it on the server.
+  if (typeof exports === 'object') {
+    _ = module.exports = require('underscore');
+  }
+
+    var islike = function(obj, pattern) {
+        if (typeof pattern === "function") {
+            return obj instanceof pattern;
+        }
+
+        if (typeof obj !== typeof pattern) return false;
+            if (_.isArray(pattern) && !_.isArray(obj)) return false;
+
+                var type = typeof pattern;
+
+                if (type == "object") {
+                    if (pattern instanceof Array) {
+                        if (pattern.length > 0) {
+                            var oTypes = _.uniq(_.map(obj, fTypeof));
+                            var pTypes = _.uniq(_.map(pattern, fTypeof));
+                            if (_.difference(oTypes, pTypes).length) {
+                                return false;
+                            }
+                        }
+                    } else { // object
+                        if (pattern.constructor === pattern.constructor.prototype.constructor) {
+                            // for 'simple' objects we enumerate
+                            var anyUnlike = _.any(pattern, function(p, k) {
+                                var o = obj[k];
+                                return !islike(o, p);
+                            });
+                            if (anyUnlike) {
+                                return false;
+                            }
+                        } else {
+                            // for 'types' we just check the inheritance chain
+                            if (!(obj instanceof pattern.constructor)) {
+                                return false;
+                            }
+                        }
+                    }
+                }
+
+                return true;
+    };
+
+    var fTypeof = function(o) {
+        return typeof o;
+    };
+
+    _.mixin({islike: islike});
+}).call(this);
+
+
+