Match

Match

A class for matching anything. Really, anything.

Most Triggers, Filters and expects use Match internally to match values, and passing a new Match to them will use the Match that you specify.

Matching has two major flavors: matching by "value", where two things are strictly compared to see if they are they exact same; and matching by "type", where something is compared to a class of things to see if it belongs to that class.

Examples of comparison by value are 3 === 3, or {a: 1} === {a: 1}. You'll note that the latter doesn't really work with strict equals, so comparisons need to be a bit more sophisticated. To that end, objects and arrays are recursively compared for a strict match using Match.value. To help out with this are a number of registered types that can spot the differences between things. Looking at the Match.addType and Match.getType static methods, these help to register handlers for specific data types. Most data types are already registered, but feel free to add your own (or create a library of types and share with friends!). These registered types create Diffs that represent the one-or-more differences between two items.

Examples of comparison by type are 3 === "string" or {a: 1} === "object". You can use Match.type to compare something to it's type, again using the built-in types or the types of your own choosing.

A Match object contains an original value or type and is ready to compare to anything passed to it using the compare() method. This makes matches easy to pass around, such as passing them as arguments to functions that do comparison.

Constructor

new Match()

Source:
Example
var matchVal = Match.value("bob");
matchVal.compare("bob"); // true
matchVal.compare("sally"); // false
matchVal.compare(undefined); // false

matchVal = Match.value(undefined);
matchVal.compare(undefined); // true

var matchType = Match.type("number");
matchType.compare(3); // true
matchType.compare(42); // true
matchType.compare("test"); // false
matchType.compare("3"); // false

console.log (Match.getType("foo").name); // "string"
console.log (Match.getType(12).name); // "number"
console.log (Match.getType(true).name); // "boolean"
console.log (Match.getType(null).name); // "null"
console.log (Match.getType(new Error()).name); // "error"
console.log (Match.getType(new Date()).name); // "date"
console.log (Match.getType([1, 2, 3]).name); // "array"
console.log (Match.getType({a: 1}).name); // "object"

Methods

(static) addType(name, parentName, testFn, diffFn)

Source:

Adds a new type to the type registry

Example
function testRegex(rex) {
    if (rex instanceof RegExp) return true;
    return false;
}

function diffRegex(rex1, rex2) {
    if (rex1.toString() !== rex2.toString()) return newDiff(rex1.toString(), rex2.toString());
    return [];
}

Match.addType("regexp", "object", testRegex, diffRegex);
Parameters:
Name Type Description
name String

The name of the type
parentName String | null

The parent of this type. For example, the parent of Array or Error is Object, since both Array and Error are objects. Care must be used in selecting the right parent, or else getType may fail and so will everything else. Use null if no parent type exists; however, all conceivable parent types have already been registered by default.
testFn function

A function that when passed a value, will return true if it is of this type and false otherwise.
diffFn function

A function that when passed two values of this type can tell the difference between them and return a proper diff Array.

(static) diff(value1, value2) → {Array}

Source:

Creates a deep diff between two values. If the arguments are Objects or Arrays, they are recurisvely iterated and compared.

Example
(
    {a: 1, b: 2, c: 3},
    {a: 1, c: 4}
    );
// returns:
// [{key: ".b", src: 2, dst: undefined},
//  {key: ".c", src: 3, dst: 4}]
Parameters:
Name Type Description
value1 any

The first value to diff.
value2 any

The second value to diff.
Returns:

An Array of differences between value1 and value2

Type
Array

(static) getType(value, matcherListopt) → {Object}

Source:

Returns the most specific 'matcher' that can identify the type

Example
var matcher = Match.getType("foo");
console.log (matcher.name); // "string"

matcher = Match.getType(true);
console.log (matcher.name); // "boolean"

matcher = Match.getType(null);
console.log (matcher.name); // "null"

matcher = Match.getType(undefined);
console.log (matcher.name); // "undefined"
Parameters:
Name Type Attributes Default Description
value any

The value to get the type for
matcherList Map <optional>
 matcherRegistrySingleton

The matcher list to retrieve the type from. Mosty used for recursion.
Returns:

The previously registered 'matcher' Object

Type
Object

(static) type(arg) → {Match}

Source:

A convenience class that creates a new Match and sets the type to be matched to arg.

Example
var m = Match.type("boolean"); // create new `Match` with value set to "foo"
m.compare(false); // true
m.compare("test"); // false
Parameters:
Name Type Description
arg arg

The type to be matched. Built-in types include: "object", "array", "string", "number", "boolean", "number", "null", "undefined", "date", "regexp", and "error".
Returns:

The new Match instance

Type
Match

(static) value(arg) → {Match}

Source:

A convenience class that creates a new Match and sets the value to be matched to arg.

Example
var m = Match.value("foo"); // create new `Match` with value set to "foo"
m.compare("foo"); // true
Parameters:
Name Type Description
arg arg

The argument to be matched
Returns:

The new Match instance

Type
Match

compare(value) → {Boolean}

Source:

Compares a new value to the previously defined value.

Parameters:
Name Type Description
value any

The value to be compared against the original value when the Match was created.
Returns:

Returns true if value matches the original value; false otherwise

Type
Boolean