Add Text.replace_all({Pattern:Text}) and tweak API for replacement to

support placeholders

1 files changed, 97 insertions, 3 deletions

diff --git a/docs/text.md b/docs/text.md
index cf60f6a3..47f60e32 100644
--- a/docs/text.md
+++ b/docs/text.md
@@ -271,11 +271,13 @@ Patterns are used in a small, but very powerful API that handles many text
 functions that would normally be handled by a more extensive API:
 
 ```
+Text.has(pattern:Pattern)->Bool
 Text.find(pattern:Pattern, start=1, length=!&Int64?)->Int
 Text.find_all(pattern:Pattern)->[Text]
 Text.split(pattern:Pattern)->[Text]
-Text.replace(pattern:Pattern, replacement:Text)->[Text]
-Text.has(pattern:Pattern)->Bool
+Text.replace(pattern:Pattern, replacement:Text, placeholder:Pattern=$//)->[Text]
+Text.replace_all(replacements:{Pattern:Text}, placeholder:Pattern=$//)->[Text]
+Text.replace_chain(patterns:[Pattern], replacements:[Text], placeholder:Pattern=$//)->[Text]
 ```
 
 See [Text Functions](#Text-Functions) for the full API documentation.
@@ -838,7 +840,7 @@ See [Patterns](#patterns) for more information about patterns.
 
 **Usage:**  
 ```tomo
-replace(text: Text, pattern: Text, replacement: Text) -> Text
+replace(text: Text, pattern: Text, replacement: Text, placeholder: Pattern = $//) -> Text
 ```
 
 **Parameters:**
@@ -846,6 +848,8 @@ replace(text: Text, pattern: Text, replacement: Text) -> Text
 - `text`: The text in which to perform replacements.
 - `pattern`: The pattern to be replaced.
 - `replacement`: The text to replace the pattern with.
+- `placeholder`: If non-empty, the replacement text will have occurrences of the placeholder
+  pattern replaced with the matching text.
 
 **Returns:**  
 The text with occurrences of the pattern replaced.
@@ -857,6 +861,96 @@ The text with occurrences of the pattern replaced.
 
 >> "Hello world":replace("{id}", "xxx")
 = "xxx xxx"
+
+>> "Hello world":replace("{id}", "(@)", placeholder=$/@/)
+= "(Hello) (world)"
+```
+
+---
+
+## `replace_all`
+
+**Description:**  
+Takes a table mapping patterns to replacement texts and performs all the
+replacements in the table on the whole text. At each position, the first
+matching pattern's replacement is applied and the pattern matching moves on to
+*after* the replacement text, so replacement text is not recursively modified.
+See [Patterns](#patterns) for more information about patterns.
+
+**Usage:**  
+```tomo
+replace_all(replacements:{Pattern:Text}, placeholder: Pattern = $//) -> Text
+```
+
+**Parameters:**
+
+- `text`: The text in which to perform replacements.
+- `replacements`: A table mapping from patterns to the replacement text
+  associated with that pattern.
+- `placeholder`: If non-empty, the replacement text will have occurrences of
+  the placeholder pattern replaced with the matching text.
+
+**Returns:**  
+The text with all occurrences of the patterns replaced with their corresponding
+replacement text.
+
+**Example:**  
+```tomo
+>> "A <tag> & an amperand":replace_all({
+    $/&/: "&amp;",
+    $/</: "&lt;",
+    $/>/: "&gt;",
+    $/"/: "&quot",
+    $/'/: "&#39;",
+}
+= "A &lt;tag&gt; &amp; an ampersand"
+
+>> "Hello":replace_all({$/{lower}/:"[@]", $/{upper}/:"{@}"}, placeholder=$/@/)
+= "{H}[ello]"
+```
+
+---
+
+## `replace_chain`
+
+**Description:**  
+Takes an array of patterns and a corresponding array of replacement texts and
+if all patterns in the patterns array match _consecutively_, then the
+replacement texts are substituted for the corresponding matches. This is useful
+if you want to replace parts of a match with new text while leaving other parts
+unchanged.
+
+As as special case, if a pattern `$/?/` is sandwiched between corresponding
+matching quotes or matching braces, it will match the inside part of the nested
+or quoted pair.
+
+See [Patterns](#patterns) for more information about patterns.
+
+**Usage:**  
+```tomo
+replace_chain(patterns:[Pattern], replacements:[Text], placeholder: Pattern = $//) -> Text
+```
+
+**Parameters:**
+
+- `text`: The text in which to perform replacements.
+- `patterns`: An array of patterns to be matched consecutively.
+- `replacements`: An array of replacement texts corresponding to each pattern.
+  This must be the same length as `patterns` or an error will be raised.
+- `placeholder`: If non-empty, the replacement text will have occurrences of
+  the placeholder pattern replaced with the matching text.
+
+**Returns:**  
+The text with all occurrences of the patterns replaced with their corresponding
+replacement text.
+
+**Example:**  
+```tomo
+>> "  foo(blah(), 2)  ":replace_chain([$/foo(/, $/?/, $/)/], ["baz(", "@", ")"], placeholder=$/@/)
+= "  baz(blah(), 2)  "
+
+>> "  foo.field_name  ":replace_chain([$/{id}/, $/.field_name/], ["@", ".other_field"], placeholder=$/@/)
+= "  foo.other_field  "
 ```
 
 ---