{replace:search:replace:text}

Description

Replaces text using a regular expression. The first parameter is a PCRE pattern, the second is the replacement (it may use backreferences such as $1 or $2 to insert captured groups), and the third is the text to search. Internally it calls PHP preg_replace with backtick delimiters that AA supplies for you - you write only the bare pattern, never delimiters or modifiers, so the dangerous /e modifier can never be used. All three parameters are passed verbatim (not trimmed), and the result is never cached. Because parameters are split on the colon, a literal colon anywhere in the pattern or the text must be escaped as #: (for example a non-capturing group (?#:...) or a time like 10#:30). For plain, non-regex substitution where the search text may itself contain regex metacharacters, use str_replace instead.

Parameters

search required

The PCRE regular expression to match. Write the bare pattern only - AA wraps it in delimiters for you, so do not add slashes or trailing modifiers. A literal colon inside the pattern must be escaped as #:.

replace required

The replacement string substituted for each match. May contain backreferences to captured groups: $1, $2 (or ${1}) insert the text matched by the first, second parenthesised group. An empty replacement removes the matched text.

text required

The subject text the pattern is searched in. A literal colon here must also be escaped as #:. Returned unchanged when the pattern matches nothing.

Examples

test{replace:world:Earth:Hello world}
ExpectedHello Earth
ActualHello Earth
The search parameter is a regular expression, so a plain word like "world" matches itself. Every match is replaced.
test{replace:<[^>]+>::<b>Bold</b> and <i>italic</i>}
ExpectedBold and italic
ActualBold and italic
Matches any HTML tag and replaces it with nothing (the replace parameter is empty), leaving only the text.
test{replace:\s+: :Hello spaced out}
ExpectedHello spaced out
ActualHello spaced out
The pattern \s+ matches each run of whitespace; replacing it with a single space normalises spacing.
test{replace:(\w+)@(\w+\.\w+):***@$2:user@example.com}
Expected***@example.com
Actual***@example.com
Two capture groups; the replacement keeps the second group via the backreference $2 and masks the first, hiding the local part of an email address.
test{replace:(?i)hello:Hi:HELLO world, hello again}
ExpectedHi world, Hi again
ActualHi world, Hi again
Modifiers like /i are not allowed after the pattern, but PCRE inline flags work: (?i) at the start makes the whole pattern case-insensitive.
test{replace:\d+#:\d+:[time]:Meeting at 10#:30 today}
ExpectedMeeting at [time] today
ActualMeeting at [time] today
Parameters split on the colon, so a colon in the pattern or text must be written as #:. Here \d+#:\d+ matches 10#:30 (a time) and replaces it.
test{replace:\s+:-:Annual Report 2026}
ExpectedAnnual-Report-2026
ActualAnnual-Report-2026
Collapse runs of whitespace into single hyphens to build a URL-style slug from a title.
← All expressions