Search and replace function

Use the regreplace function to perform search and replace operations on strings by using regular expressions.

The syntax is as follows:

regreplace(input, "regularexpression", "substitution" [,count])

Where:

The input is a string expression. The regreplace function reads the input string from left to right.
In Fix Pack 4 or later, the regularexpression can be a string or a string expression. Previous levels only allowed the use of string literals for regular expressions. You can use parentheses () in the string to specify substrings that require specific matching. You can use multiple sets of parentheses in a string.
The substitution is a string expression that specifies how strings that match input are to be written in the result. You can use metacharacters to reference matching substrings (in parentheses), as well as an entire matching string or strings. For example, \1 matches the first group in the regular expression, \2 the second, and so on, while & or \0 match the entire string. Characters and strings that do not match the regular expression are copied to the result string.
The count is an optional positive integer expression, and denotes the number of substitutions to be made on matching strings. If you do not provide a value for count, the substitutions continue until no more matching strings are found. If count is a non-integer expression, it is interpreted as 0, and the input is not changed. If count is a negative integer, a warning message is entered in the probe log, and the input is not changed.

Note: If you provide an invalid string expression for the regular expression, it will fail to compile at run time, and the result of a regreplace call becomes the original input string. In addition, an error message is logged in the probe log file for invalid string expressions.

Example: Using search and replace to remove unwanted characters from a string

The following example shows how to use the regreplace function to replace underscores (_), percent signs (%), and single quotes (') with a blank string:

$result = regreplace("%Node___='foobar27'%" , "([_%']*)", "" )

The result of this expression is as follows:

$result="Node=foobar27"

The following example shows how to use the regreplace function to replace carriage return (CR) or line feed (LF) control characters with a blank string:

@Summary = regreplace($Summary, '[\n\r]', "")

Example: Reordering groups of characters in a string

The following example shows how to match multiple substrings within a string and, in the output, reorder the substrings. The order of substrings in the input string is changed in the output string.

regreplace("aba argle aca", "(a.a) (.*) (a.a)", "\3 \2 \1")

The regular expression matches the substrings in the following order:

\1="aba"
\2="argle"
\3="aca"

The substitution string specifies that the matched strings be written in the reverse order to which the input is read. Consequently, the result of this expression is as follows:

$result = "aca argle aba"

Example: Using metacharacters to match an entire string

The following example shows how to use the metacharacter &, which can also be expressed as \0, to match the entire string represented by the regular expression:

regreplace("aaabbbaaa", "a(b+)a" "_&_")

The & or \0 metacharacters match everything that maps to the regular expression, not only the substring in parentheses. In this example, the regular expression matches the following substring in the input: abbba. The nonmatching substrings are copied to the output.

The result of this expression is as follows:

$result="aa_abbba_aa"

Example: Using variables to replace all strings contained in a field with same string

You can use variables to replace all instances of a string contained in a field with the same string. The following example shows how to use the regreplace function with regular expressions stored in variables ($element or @Field in rules files).

In this example, the probe receives a $Summary token that contains a textual description of the problem, which includes the node name of the host several times. You can use regreplace as follows to replace the node name obtained from the @Node field with the string "host", making the resulting message more generic and easier to write generic rules file code for:

$Summary = regreplace( $Summary, @Node, "host" )

For example, this converts the $Summary value of

"The machine nodea.example.com is experiencing connectivity problems. nodea.example.com cannot reach the gateway."

to the following value:

"The machine host is experiencing connectivity problems. host cannot reach the gateway."