2012 NEWS 2012-06-27 - New Uize.resolveMatcher Method
The new Uize.resolveMatcher static method, implemented in the Uize base module, resolves the specified matcher (of any type) to a matcher function.
The resolved matcher function can be passed two arguments, value and key, and returns a value derived from one or both of those inputs.
SYNTAX
matcherFUNC = Uize.resolveMatcher (matcherANYTYPE);
The Uize.resolveMatcher method is intended to be used in the implementation of other methods that want to allow a matcher to be specified in several different forms (such as an expression string, for example), but always want to use the matcher as a function. Examples of such methods include the various methods of the Uize.Data.Matches module, such as the Uize.Data.Matches.remove method whose second argument is a matcher. The Uize.resolveMatcher method allows such methods to be versatile in how they let matchers be specified.
EXAMPLE
function findMatches (array,matcher) {
matcher = Uize.resolveMatcher (matcher);
var matches = [];
for (var elementNo = -1; ++elementNo < array.length;) {
var elementValue = array [elementNo];
if (matcher (elementValue)) {
matches.push (elementValue);
}
}
return matches;
}
In the above example, we are implementing a simple function to find the elements in an array that match a specified matcher and return those matches in a new array. The second argument of the function is a matcher. To allow users of the function to specify a matcher using an expression string short form, we resolve the value of the matcher argument using the Uize.resolveMatcher method and re-assign the resolved value to the matcher argument. Once resolved, we can now count on the matcher being a function and we can call it in the loop that iterates over the source array. Now a caller can call this function with statements like...
findMatches (possibleNumbers,'typeof value == "number"'); findMatches (possibleIdentifiers,/^[_\$a-zA-Z][_\$a-zA-Z0-9]*$/);
1. How Different Matcher Types are Resolved
The Uize.resolveMatcher method supports numerous different ways of specifying a matcher.
1.1. When a Function Type Matcher is Specified
When a function is specified for the matcherANYTYPE parameter, that function is simply returned.
The Uize.resolveMatcher method is used to resolve a value that could be one of several different types to something that's guaranteed to be a function. In the case where the matcher is already a function, it is considered to already be resolved and is returned as is.
1.2. When a String Type Matcher is Specified
When a string value is specified for the matcherANYTYPE parameter, a function is produced using the specified string matcher expression as the function's body, and accepting the two arguments value and key.
For example, the matcher expression string 'typeof value == "number"' would be resolved to the function function (value,key) {return typeof value == 'number'}. In another example, the matcher expression string '/name/i.test (key) && /^c/i.test (value)' would be resolved to the function function (value,key) {return /name/i.test (key) && /^c/i.test (value)}.
The Uize.resolveMatcher method imposes the argument names value and key for the two arguments of the function that it produces from a matcher exprression string, so such an expression must use these reserved variable names to access the value and optional key that will be passed in by the caller of the resolved matcher.
1.3. When a Regular Expression Matcher is Specified
When a regular expression is specified for the matcherANYTYPE parameter, a function is produced using the regular expression to test the value of its first argument for a match, returning a boolean value.
EXAMPLE
var isValidIdentifier = Uize.resolveMatcher (/^[_\$a-zA-Z][_\$a-zA-Z0-9]*$/);
alert (isValidIdentifier ('')); // alerts "false"
alert (isValidIdentifier ('fooVar')); // alerts "true"
alert (isValidIdentifier ('$foo')); // alerts "true"
alert (isValidIdentifier ('3rdVar')); // alerts "false"
alert (isValidIdentifier ('_4thVar')); // alerts "true"
1.4. When a Nully Matcher is Specified
When a nully value (i.e. the value null or undefined) is specified for the matcherANYTYPE parameter, a function is produced that always returns the value true.
This behavior is useful for methods that want to offer an optional matcher and wish no filtering (i.e. always matching) to be performed when the optional argument is not specified, or if the values null or undefined are explicitly specified.
1.5. When a Boolean Type Matcher is Specified
When a boolean value is specified for the matcherANYTYPE parameter, a function is produced that simply returns that boolean value, regardless of the argument values.
This behavior can be useful in situations where you wish to force the matching result to be always true or false. In such cases, specifying simply a boolean value for the matcher is a convenient shorthand.