Javascript MatchingItem

Revision as of 11:49, 4 September 2024

General

Object implementing complex 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.

Description

This section describes the matching item types and associted 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
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
value Regular expression to match
negated Boolean. Negated match. Default: false

Random

Random match. Matches if value > RANDOM() % maxvalue Properties:
name Item name
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
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

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

Methods

• matches(value)

• getDesc([params])

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