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: Parameter name.
params: Build 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: if a list contains a single matching item the list itself will be ignore, the single item will replace the list. The list's negated property will be applied to enclosed item.

RegExp properties ignoreCase and basicPosix can be overridden when building one:

// The following will build a case insensitive regular expression
var rex = /^abc/i;
// Case insensitive property will be overridden in RegExp create by validate
Engine.MatchingItem.validate({value:rex, ignoreCase:false});

This may be used when matching criteria and properties are read from different configuration parameters.

Validate parameters: nooptimize Do not optimize the matching criteria.
' Do not optimize the matching criteria.
' Do not optimize the matching criteria.

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