diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/text.md | 100 |
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({ + $/&/: "&", + $/</: "<", + $/>/: ">", + $/"/: """, + $/'/: "'", +} += "A <tag> & 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 " ``` --- |