Skip to content

REX

Introduction

Regular expressions are patterns that can match one or more characters in a string.

REX is a pre-defined object available in the scripting language that can be used for regular expression-based find & replace operations.

The REX object supports the same Perl compatible regular expressions used for the PATTERN attribute of the rules language. Its methods are described below.

compile

The first thing to do in order to use a regular expression is to compile it.
This is achieved with the compile method of the REX object which has this syntax:

REX.compile(regularExpression)

where regularExpression is a string—a constant or a variable—representing a Perl compatible regular expression.
This method returns an integer value which is the identifier used in find & replace methods to refer to the regular expression.

anchoredMatch

The anchoredMatch method checks if a regular expression matches the beginning of a string. It returns a Boolean value, which will be True, if the match is found and False otherwise. For example, after the execution of this snippet of code:

// The value of variable text is "Hello world!"

var rexId = REX.compile("[[:upper:]]");

var isMatch = REX.anchoredMatch(rexId, text);

the value of the isMatch variable is True, because an uppercase letter (H) was found at the beginning of the value (Hello world!) of the text variable.

The syntax is:

REX.anchoredMatch(regularExpressionIdentifier, string)

where:

  • regularExpressionIdentifier is the identifier of a regular expression that's previously been compiled with the compile method.
  • string is a string—variable or constant—in which to search for the regular expression.

partialMatch

The partialMatch method checks if a regular expression has a match anywhere inside a string. It returns a Boolean value which is True if the match was found, False otherwise. For example, after the execution of this snippet of code:

// The value of variable text is "Hello world!"

var rexId = REX.compile("[wm]o");

var isMatch = REX.partialMatch(rexId, text);

the value of the isMatch variable is True, because a match (wo) for the regular expression [wm]o was found inside the value of the text variable.

The syntax is:

REX.partialMatch(regularExpressionIdentifier, string)

where:

  • regularExpressionIdentifier is the identifier of a regular expression that's previously been compiled with the compile method.
  • string is a string—variable or constant—in which to search for the regular expression.

match

The match method checks if a regular expression matches a string starting the search at an offset position withing the string itself. It returns an array containing the position and the length of the match. For example, after the execution of this snippet of code:

// The value of variable text is "Hello world!"

var rexId = REX.compile("[wm]o");

var match = REX.match(rexId, text, 3);

the value of the match variable is this array:

match[0] = 6
match[1] = 2

because a match of the regular expression [wm]o was found at position 6 of the value of text (Hello world!) and the length of the matched sub-string (wo) is 2.

The syntax is:

REX.match(regularExpressionIdentifier, string, offset)

where:

  • regularExpressionIdentifier is the identifier of a regular expression that's previously been compiled with the compile method.
  • string is a string—variable or constant—in which to search for the regular expression.
  • offset is an integer value or an integer variable representing the offset in the string from which to start searching for the regular expression.

When no match is found the value of the returned array is:

[0] = -1
[1] = 0

substitute

The substitute method replaces the part of a string that is matched by a regular expression with another string. It returns the resulting string. For example, after the execution of this snippet of code:

// The value of variable text is "Hello world!"

var rexId = REX.compile("(?i)hello");

var replaced = REX.substitute(rexId, text, "Hi");

the value of the replaced variable will be:

Hi world!

because the match of the regular expression (?i)hello (Hello) was replaced with the constant string Hi.

The syntax is:

REX.substitute(regularExpressionIdentifier, string, replacementString)

where:

  • regularExpressionEdentifier is the identifier of a regular expression that's previously been compiled with the compile method.
  • string is a string—variable or constant—in which to search for the regular expression.
  • replacementString is the replacement string—either a constant or a variable.

The method returns a new string representing the string after the replacement.

close

The close method releases the memory occupied by a regular expression. After the execution of the method, the regular expression is no longer available.

The syntax is:

REX.close(regularExpressionEdentifier)

where regularExpressionIdentifier is the identifier of a regular expression that's previously been compiled with the compile method.

Always use the close method to free up memory when you don't need a regular expression anymore.

Scope of the REX object

The REX object always has a global scope and can be used in any function of a script, it is particularly useful in the onPrepare function.
If desired, it is also possible to give a regular expression identifier a global scope. This is accomplished by setting it with the REX.compile method in the initialize function. A globally scoped regular expression identifier can be used anywhere in the code, but remember to close it with the REX.close method in the shutdown function.