Javascript MatchingItem

General

Object implementing value(s) matching.
May be set as filter in Message handler and post hook install (match one or more message parameter(s)).
May be used for matching individual values or javascript objects.

Usage:

var list = [{name:"param1",value:"str"},{name:"param2",value:/^abc/}];
miParams = new Engine.MatchingItem({value:list, any:true});

// Handler for a "message.name" message matching some parameters
Message.install(some_function,"call.preroute",100,miParams);

// Posthook for all call.* messages but not call.cdr using the above parameters list matching
var list = [{value:/^call\./},{value:"call.cdr",negated:true}];
var miMsgName = new Engine.MatchingItem(list);
Message.installPostHook(some_function,"some_id",miMsgName,miParams);

// Match object
var obj = {param1:"str",a:2};
var ok = miParams.matches(obj);

// Match string
var ok = miParams.matches("str");

Description

This section describes the matching item types and associated properties.
When matching object properties (e.g. Message parameters) item name indicates a specific property name (message parameter name).

NOTE: Item properties listed here does not belong to a MatchingItem object. They are held in internal item structure and used during matching.
They are present in value returned by getDesc() function.
They are handled in MatchingItem build (constructor) or validate().

In the following example the negated property of mi object is ignored by matching:

var mi = new Engine.MatchingItem("some_value","some_name");
mi.negated = true;
var ok = mi.matches("some_value");
// ok will be true

NOTE: negated property indicates matches() will return true if item matching conditions are NOT fulfilled.
This is a pseudo-code describing it:

IF matching_conditions_fulfilled THEN
   matches = TRUE
ELSE
   matches = FALSE
IF negated THEN
   matches = NOT matches

String

String comparison.
Properties:
name Item name. May be empty
value Value to compare with (string)
ignoreCase Boolean. Case insensitive comparison. Default: false
negated Boolean. Negated match. Default: false

RegExp

Regular expression match.
Properties:
name Item name. May be empty
value RegExp. Regular expression to match
negated Boolean. Negated match. Default: false

Random

Random match. Matches if value > RANDOM() % maxvalue Properties:
name Item name. May be empty
value Numeric, handled as 32bit positive value. Default: 0.
maxvalue Numeric, handled as 32bit positive value. Default: 0.
negated Boolean. Negated match. Default: false

Default data when built:
value==0: Ignore maxvalue, set it 100: NEVER MATCH
value>0 AND maxvalue<2: Ignore value and maxvalue. Set both to 100: ALWAYS MATCH

List

List matching. May contain any matching item including other list(s).
Properties:
name Item name. May be empty
value Array of matching items
any Boolean. True: match if any item matches (logical OR). Default: false, match if all items match (logical AND).
negated Boolean. Negated match. Default: false

Examples

Build simple items

String:

// Same matching rule:
var miStr = new Engine.MatchingItem("some_string","some_name"); 
var miStr = new Engine.MatchingItem({value:"some_string",name:"some_name"});
// The second variant allows adding properties:
var miStrFull = new Engine.MatchingItem({value:"some_string",name:"some_name",negated:true,ignoreCase:true});

Regexp:

// Same matching rule:
var miRex = new Engine.MatchingItem(/^some_string/,"some_name"); 
var miRex = new Engine.MatchingItem({value:/^some_string/,name:"some_name"});
// The second variant allows adding properties:
var miRex2 = new Engine.MatchingItem({value:/^some_string/,name:"some_name",negated:true});

Random:

// Random percent match: 50%
var miRand50 = new Engine.MatchingItem({type:"random",value:50,maxvalue:100});

Build list of items

List:

var value = [];
value.push({value:"some_string",name:"string"});
value.push({value:/^some_string/,name:"regexp",negated:true});
value.push({value:"some_string",name:"string_nocase_negated",ignoreCase:true,negated:true});
// Include a list in this list. Set the included list 'any' property
var valueItemList = [];
valueItemList.push({value:/^some_string/,name:"regexp_nocase",ignoreCase:true});
valueItemList.push({type:"random",value:50,maxvalue:100});
value.push({value:valueItemList, any:true});
var list = new Engine.MatchingItem(value);

Output of list.dump(undefined,"\r\n"," "):

string: 'some_string'
regexp: [!] /^some_string/
string_nocase_negated: [!i] 'some_string'
List: [any]
  regexp_nocase: [i] /^some_string/
  RANDOM 50%

Output of Engine.print_var_r(Engine.MatchingItem.validate(value)):

'match' = [object Object]
  'name' = 
  'value' = [object Array]
    '0' = [object Object]
      'name' = 'string'
      'value' = 'some_string'
    '1' = [object Object]
      'name' = 'regexp'
      'value' = /^some_string/
        'ignoreCase' = 'false'
        'basicPosix' = 'false'
      'negated' = true
    '2' = [object Object]
      'name' = 'string_nocase_negated'
      'value' = 'some_string'
      'ignoreCase' = true
      'negated' = true
    '3' = [object Object]
      'name' = 
      'value' = [object Array]
        '0' = [object Object]
          'name' = 'regexp_nocase'
          'value' = /^some_string/
            'ignoreCase' = 'true'
            'basicPosix' = 'false'
        '1' = [object Object]
          'name' = 
          'value' = [object Object]
            'type' = 'random'
            'value' = 50
            'maxvalue' = 100
      'any' = true

Constructor

• new Engine.MatchingItem(value[,name[,params])

Build a new MatchingItem object.
Parameters:
value: Value to match. May be another MatchingItem object (all other parameters will be ignored).
name: Parameter name.
params: Build parameters.

If value is a MatchingItem builds a copy of it.

Otherwise build a MatchingItem from received parameters.
See validate() method for processing.
Constructor will fail if validate() would not return an object.
If you are not sure of parameters (may be read from configuration): call validate() and pass the result to constructor:

var obj = Engine.MatchingItem.validate(some_value,some_name,params);
if (obj && "string" != typeof obj)
    obj = new Engine.MatchingItem(obj);
else if (undefined === obj) {
    // Empty ...
}
else {
    // Invalid. obj is an error string
}

Static methods

• validate(value[,name[,params]])

Parameters:
value: Value to match.
name: Optional parameter name.
params: Validate parameters.
Return:
Success: Object with matching properties. See the description section.
Success with empty optimized matching: undefined
Error: string describing the error

Lists will be optimized by default: if a list contains a single matching item the list itself will be ignored, the single item will replace the list. The list's negated property will be applied to enclosed item.
If a list is given and its negated property is set the single item's negated' property will be negated.
List optimization is recursive:

var list = [ [ {name:"n", value:"s"} ] ];
var s = JSON.stringify(Engine.MatchingItem.validate(list));
// s variable contents: {"name": "n","value": "s"} 

Validate parameters:
nooptimize Do not optimize the matching criteria. Default: false (optimize)
name_required_simple Fail if name is empty for simple (non list) matching items. Default: false
name_required_list Fail if name is empty for matching item list. Default: false

Validate based on value type:

1. Not an object: Build a string matching using it as matching value. Use name as parameter name. Check params for negated and ignoreCase properties
2. Array: Build a matching list. Use name as parameter name. Check params for any and negated properties
3. RegExp: Build a regular expression matching. Use name as parameter name. Check params for negated, ignoreCase and basicPosix properties. Override RegExp properties if present in params
4. Object have a type property set to random: Build a random match. Use name as parameter name. Check params for a negated property. Check value object value and maxvalue properties
5. null: build an empty string match (empty name/value)
6. MatchingItem: fail validate
7. Otherwise: build a matching item from object description. Ignore all other parameters except for validate parameters

Build a matching item from object description:
Retrieve name, value and negated properties from object.
Validate/build based on object value type:

1. Not an object: Build a string matching using it. Check for object ignoreCase property
2. Array: Build a matching list. Check for object any property
3. RegExp: Build a regular expression matching. Check object ignoreCase and basicPosix properties. Override RegExp properties if present
4. Object have a type property set to random: Build a random match. Check object for value and maxvalue properties
5. null: build an empty string match (empty name/value)
6. Otherwise: fail validate

Last (if not already failed: matching list validate/build may fail if any item build fails):

1. Check name as instructed in validate parameters. Fail if empty and validate is requiring not to be
2. Optimize if optimization is available (list) and not prevented by validate parameters

Methods

• matches(value)

Check if a value matches this item.
Parameters:
value Value to match.
Return: True if item rules matches, false otherwise.

Matching null, undefined or non object:
Match string value. Item(s) name will be ignored.
Empty string is used for null or undefined

Matching object:
Check properties and values.
Item(s) name is used to retrieve object property.
Missing property or empty values are handled as empty string.

• getDesc([params])

Retrieve the description of this item.
Parameters:
params Object with description generation parameters.
Return: Object. See description section for object properties.

Generation parameters:
force_bool_props Boolean. Fill properties with having default values (e.g. fill negated property even if set to false). Default: false.

• dump([params[,indent,origIndent]])

Dump a string containing a printable description of this item.
Parameters:
params Dump parameters.
indent String. Indent for each item (line). Increased by 'origIndent' when depth advances.
origIndent String. Original (all items) indent.
Return: String

Dump parameters:
rex_enclose String, first character only. Character to use to enclose regular expression values. Default: /.
str_enclose String, first character only. Character to use to enclose string values. Default: '.
name_value_sep String. name/value separator to use when needed. Default: ": ".
prop_negated String, first character only. Character to use to dump indication of negated item. Default: !.
prop_caseinsensitive String, first character only. Character to use to dump indication of ignoreCase item property. Default: i.
prop_rex_basic String, first character only. Character to use to dump indication of basicPosix=true regexp property. Default: empty.
prop_rex_extended String, first character only. Character to use to dump indication of basicPosix=false regexp property. Default: empty.
flags: Comma separated list of dump flags:

• no_initial_list_desc Boolean. True: don not dump initial list (this object) description. Default: false