add documentation for RegexReplacer

base/regex.jl

@@ -532,6 +532,8 @@ end
 Stores the given string `substr` as a `SubstitutionString`, for use in regular expression
 substitutions. Most commonly constructed using the [`@s_str`](@ref) macro.
 
+See also [`RegexReplacer`](@ref).
+
 ```jldoctest
 julia> SubstitutionString("Hello \\\\g<name>, it's \\\\1")
 s"Hello \\g<name>, it's \\1"
@@ -568,6 +570,8 @@ Construct a substitution string, used for regular expression substitutions.  Wit
 string, sequences of the form `\\N` refer to the Nth capture group in the regex, and
 `\\g<groupname>` refers to a named capture group with name `groupname`.
 
+See also [`RegexReplacer`](@ref).
+
 ```jldoctest
 julia> msg = "#Hello# from Julia";
 
@@ -666,6 +670,33 @@ function _replace(io, repl_s::SubstitutionString, str, r, re::RegexAndMatchData)
     end
 end
 
+"""
+    RegexReplacer(f::Function)
+
+Create a `RegexReplacer` that can be used to
+[`replace`](@ref replace(::AbstractString, ::Pair))
+[`Regex`](@ref)-matched text using the given function `f`
+with access to the current match and capture groups.
+
+`f` must be callable with a [`RegexMatch`](@ref) and return a [`print`](@ref)-able object.
+
+See also [`SubstitutionString`](@ref), [`@s_str`](@ref).
+
+# Examples
+```jldoctest
+julia> s = "ax ay az bx by bz";
+
+julia> replace(s, r"([ab])([xy])" => RegexReplacer(match -> uppercase(match[1]) * match[2]))
+"Ax Ay az Bx By bz"
+
+julia> template = "the {animal} is {activity}";
+
+julia> variables = Dict("animal" => "fox", "activity" => "running");
+
+julia> replace(template, r"{(.*?)}" => RegexReplacer(match -> variables[match[1]]))
+"the fox is running"
+```
+"""
 struct RegexReplacer
     f::Function
 end

base/strings/util.jl

@@ -582,6 +582,8 @@ where `s` is the matched substring (when `pat` is a `AbstractPattern` or `Abstra
 character (when `pat` is an `AbstractChar` or a collection of `AbstractChar`).
 If `pat` is a regular expression and `r` is a [`SubstitutionString`](@ref), then capture group
 references in `r` are replaced with the corresponding matched text.
+If `pat` is a regular expression and `r` is a [`RegexReplacer`](@ref),
+then the matched substring is replaced with `r.f(m)` where `m` is a [`RegexMatch`](@ref).
 To remove instances of `pat` from `string`, set `r` to the empty `String` (`""`).
 
 # Examples

doc/src/base/strings.md

@@ -35,6 +35,7 @@ Base.match
 Base.eachmatch
 Base.RegexMatch
 Base.keys(::RegexMatch)
+Base.RegexReplacer
 Base.isless(::AbstractString, ::AbstractString)
 Base.:(==)(::AbstractString, ::AbstractString)
 Base.cmp(::AbstractString, ::AbstractString)