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

Return type: string

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


  • 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 for the exact meaning of the uppercase options, and note that some can be turned on inside the regular expression, e.g. (?s).

  • g: global, replace all matches
  • 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.


bundle agent main
      # 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", "");

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


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()