Skip to content

Predefined functions

The rule engine comes with a variety of built-in functions that can be used in scripting scenarios. Some functions are generic and can be used in any context, while others are designed specifically for altering categorization or extraction results.

Categorization functions

For categorization scripting, a comprehensive list of functions and their explanations can be found in the documentation here.

Extraction functions

For extraction scripting, a comprehensive list of functions and their explanations can be found in the documentation here.

Generic functions

loadFile

The loadFile function allows you to read the contents of a text file and store it as a string variable. To use it, simply provide the file path as an argument, like this:

var myList = loadFile("mylist.txt")

The syntax is:

loadFile(filePath)

Here, filePath is the path to the text file, relative to the rules sub-folder of your project.

Warning

For security reasons, the loadFile function is restricted from accessing folders that are located outside the rules directory. Attempting to do so will result in an exception being triggered.

Tip

When dealing with larger files, such as long lists, it is recommended that you call loadFile inside the initialize function, which is executed only once when the engine starts up. This can help improve performance and avoid potential memory issues.

LENGTH

The LENGTH function returns the length of an object or an array. It is particularly useful when working with dictionaries, which would otherwise require a more verbose syntax to obtain their length. Using LENGTH can simplify code and make it more readable when needing to obtain the length of a dictionary.

To use the function, pass the variable name as an argument.

LENGTH(variableName)

This function is also used in domain manipulations.

CLONE

The CLONE function performs a deep copy of an array or object; making it useful for scenarios where you don't want to reference the original data but instead make a separate copy of it.

This function is also used in domain manipulations.

To use the function, pass the variable name as an argument.

CLONE(variableName)

For example:

var object = { 
    name: "foo", 
    data: {
        subArray: [0, 1, 2]
    }
}

var myCopy = CLONE(object);
myCopy.name = "fighters";

CONSOLE.log(JSON.stringify(object));
CONSOLE.log(JSON.stringify(myCopy));

In this example, the printed output shows that modifying the myCopy object has no impact on the original object.

find

The find function checks whether a specified key exists in an object and returns a boolean value. To use the function, provide the keyName and objectName as arguments in the following format:

find(objectName, keyName)

where:

  • objectName: the name of the object to search for the key in
  • keyName: the name of the key to search for in the object

If the key is present in the object, the function returns true. Otherwise, it returns false.

For example:

var object = { 
    name: "foo", 
}

CONSOLE.log(find(object, "name"));
CONSOLE.log(find(object, "nonexisting_name"));

Here, the first call to the find function will return a true, while the second a false.

convertToNumber

The convertToNumber function is utilized to transform a string into a number, using a user-defined value as a fallback if the string cannot be converted. It requires two parameters:

convertToNumber(value, NaN_value)

where:

  • value: A string that will be converted into a number (if possible).
  • NaN_value: A default value to be returned if the string cannot be converted to a number.

The function returns a number. If value is not a number, it returns the specified NaN_value.

For example:

var string_1 = "42";
var string_2 = "foo";

CONSOLE.log(convertToNumber(string_1, -1) * 2); // result is: 84
CONSOLE.log(convertToNumber(string_2, 0) + 1); // result is: 1
CONSOLE.log(convertToNumber(string_2, "test")); // result is: test

checkFloatRange

The checkFloatRange function is used to check whether a given value is within a specified range, and if not, return a default value. It requires four parameters:

checkFloatRange(value, min, max, defaultValue)

where:

  • value: A number that represents the value to be checked for range.
  • min: A number that represents the minimum value allowed.
  • max: A number that represents the maximum value allowed.
  • defaultValue: A number that represents the default value to return if the value is outside the range.

The function returns a number. If value is not a number, it returns the defaultValue. If value is a number and is within the specified range, it returns the value, otherwise it returns the defaultValue.

For example:

var result_1 = checkFloatRange(5, 0, 10, 0); 
var result_2 = checkFloatRange(15, 0, 10, 0);
var result_3 = checkFloatRange("abc", 0, 10, -1);

CONSOLE.log(result_1); // result_1: is 5
CONSOLE.log(result_2); // result_2: is 0
CONSOLE.log(result_3); // result_3: is -1

printOBJ

The printOBJ function is a utility function that converts an object into a string and directly prints it to the console. It requires a single parameter:

printOBJ(object)

where:

  • object: An object (or an array) to be printed in the console

For example:

var obj = { string: "fighters", number: 42};
var array = ["lucky", 7];

printOBJ(obj); // result is: {"string":"fighters","number":42}
printOBJ(array); // result is: ["lucky",7]

Please note that printOBJ will not return the string but will directly display it in the console, allowing you to quickly inspect the content of an object or an array during debugging or development.