Prototype: regex_replace(string, regex, replacement, options)

Return type: string

Description: In a given string, replaces a regular expression with something else.

Arguments:

  • string: string - Source string - in the range: .*
  • regex: regular expression - Regular expression pattern - in the range: .*
  • replacement: string - Replacement string - in the range: .*
  • options: string - sed/Perl-style options: gmsixUT - in the range: .*

The supported options are single letters you place in the options string in any order. Consult http://pcre.org/pcre.txt for the exact meaning of the uppercase options, and note that some can be turned on inside the regular expression, e.g. (?s).

  • i: case-insensitive
  • m: multiline (PCRE_MULTILINE)
  • s: dot matches newlines too (PCRE_DOTALL)
  • x: extended regular expressions (PCRE_EXTENDED, very nice for readability)
  • U: ungreedy (PCRE_UNGREEDY)
  • T: disables special characters and backreferences in the replacement string

In the replacement, $1 and \1 refer to the first capture group. $2 and \2 refer to the second, and so on, except there is no \10 or higher, you have to use $10 etc.

In addition, $+ is replaced with the capture count. $' (dollar sign + single quote) is the part of the string after the regex match. $` (dollar sign + backtick) is the part of the string before the regex match. $& holds the entire regex match.

Example:

code
bundle agent main
{
  vars:
      # global regex replace A with B
      "AB" string => regex_replace("This has AAA rating", "A", "B", "g");
      # global regex replace [Aa] with B (case insensitive)
      "AaB" string => regex_replace("This has AAA rating", "A", "B", "gi");
      # global replace every three characters with [cap=thecharacters] using $1
      "cap123" string => regex_replace("abcdefghijklmn", "(...)", "[cap=$1]", "g");
      # multiple captures using \1 \2 (just like $1 $2 but can only go up to \9)
      "path_breakdown" string => regex_replace("/a/b/c/example.txt", "(.+)/(.+)", "dirname = \1 file basename = \2", "");

  reports:
      # in order, the above...
      "AB replacement = '$(AB)'";
      "AaB replacement = '$(AaB)'";
      "cap123 replacement = '$(cap123)'";
      "path_breakdown replacement = '$(path_breakdown)'";
}

Output:

code
R: AB replacement = 'This has BBB rating'
R: AaB replacement = 'This hBs BBB rBting'
R: cap123 replacement = '[cap=abc][cap=def][cap=ghi][cap=jkl]mn'
R: path_breakdown replacement = 'dirname = /a/b/c file basename = example.txt'

History: Was introduced in version 3.8.0 (2015)

See also: data_regextract() regextract()