Regular expression function

The Regular Expression function executes a regular expression extraction against a source string. By default, this group is the first group that is returned, however an optional fourth parameter can be used to extract other groups.

Note: Functions can be written in Legacy Script Language or in ECMAScript. For details, see Scripts within tests and stubs. All the examples given in this topic are in Legacy, unless specified otherwise.

Usage


regex(string, expr, [instance], [extractionGroup])
  • string is the source string against which the regular expression is to be run.
  • expr is the regular expression.
  • instance is the optional instance to be extracted without this parameter, true, or false is returned based on whether the match succeeds.
  • extractionGroup is the optional extraction group that controls how content is returned. A zero (default) returns all text, one returns only the first match, two returns only the second match, and so on.

Examples of string functions

The following examples illustrate the use of the regex function. The simplest case is to see if a pattern exists within the string:

regex ( "hello world", "h")
Returns 'true'.
regex ( "hello world", "xxx")
Returns 'false'.
regex ( "hello world", "l.",1)
Returns 'll'.

Example for time field

If a time field (hh:mm:ss) is extracted from a message and is held in a tag named "timeField", the following function returns the value for the hours as instance 1:


regex ( "%%timeField%%", "(\d\d)",1)

Increasing the instance argument to "2" or "3" provides access to the minute and second values.

Example for multiple sections

It is possible to specify multiple sections of text within ( ) brackets. In this case, the function must extract some words from the following tag in an XML document that is specified by %%XML%%:

<tag_name>Here is some writing to be transformed.</tag_name>
regex("%%XML%%", "<tag_name>.* (t\w*).*(t\w*).*</tag_name>",1,1)
Finds the first ( ) match the word that begins with 't' and returns 'to'.
Legacy:
regex("%%XML%%", "<tag_name>.* (t\w*).*(t\w*).*</tag_name>",1,2)
Finds the second ( ) match and returns 'transformed'.
ECMAScript:
regex ( xml, "<tag_name>.* (tw*).* (tw*).*</tag_name>", 1, 2)
To see a working example, include the sample value into an XML variable: 

<item><title>a book</title><quantity>1</quantity><tag_name>Here is some writing to be transformed.</tag_name><price>10.00</price></item>
Note: If extractionGroup is set to zero, the whole string match is returned.

Modifiers

Modifiers can be used in regular expression (for example, those expressions that are used to process strings that span multiple lines). Modifiers are placed in front of the regular expression in round brackets, as follows:

(?s)\<\?xml.* extracts an XML string over multiple lines.

Modifiers can be combined in the same brackets by using a single '?', as follows:

(?si)\<\?xml.* extracts an XML string over multiple lines while it ignores the case.

The following is a list of commonly used modifiers:

  • ?i case insensitive
  • ?x comment mode
  • ?d line mode
  • ?m multiple line mode
  • ?s single-line mode

Modifiers can be used anywhere that regular expressions are used in HCL OneTest™ API, for example in tagging operations. For more information, see the Perl regular expression documentation.