mirror of
https://github.com/mailscope/kumomta.git
synced 2026-09-09 03:52:13 +00:00
150 lines
4.7 KiB
Markdown
150 lines
4.7 KiB
Markdown
# `kumo.regex.compile(PATTERN)`
|
||
|
||
{{since('2024.09.02-c5476b89')}}
|
||
|
||
Compiles the regular expression `PATTERN`.
|
||
The supported syntax is [described in the Rust regex crate
|
||
documentation](https://docs.rs/regex/latest/regex/index.html#syntax), augmented
|
||
by [fancy regex
|
||
extensions](https://docs.rs/fancy-regex/latest/fancy_regex/#syntax), and is
|
||
similar to Perl-Compatible Regex, with a few differences.
|
||
|
||
!!! note
|
||
In lua string literals backslash **must always** be escaped by a backslash,
|
||
so you will need to write `\\` in cases where in other languages you
|
||
might have been able to get away with just a single backslash.
|
||
|
||
The return from this function is a `Regex` object that has the following
|
||
methods:
|
||
|
||
## regex:captures(HAYSTACK)
|
||
|
||
Searches for the first match of this regex in the haystack given, and if found,
|
||
returns a table keyed by the captures defined in the regex. Index 0 corresponds
|
||
to the full match. Each subsequent capture group is indexed by the order of its
|
||
opening `(`.
|
||
|
||
```lua
|
||
local re = kumo.regex.compile "'([^']+)'\\s+\\((\\d{4})\\)"
|
||
local cap = re:captures "Not my favorite movie: 'Citizen Kane' (1941)."
|
||
assert(cap[0] == "'Citizen Kane' (1941)")
|
||
assert(cap[1] == 'Citizen Kane')
|
||
assert(cap[2] == '1941')
|
||
```
|
||
|
||
Named capture groups are also supported; in addition to the numeric indices
|
||
described above, if you have used a named capture group, you can also index
|
||
the result by its name:
|
||
|
||
```lua
|
||
local re = kumo.regex.compile "'(?<title>[^']+)'\\s+\\((?<year>\\d{4})\\)"
|
||
local cap = re:captures "Not my favorite movie: 'Citizen Kane' (1941)."
|
||
assert(cap[0] == "'Citizen Kane' (1941)")
|
||
assert(cap.title == 'Citizen Kane')
|
||
assert(cap.year == '1941')
|
||
```
|
||
|
||
## regex:is_match(HAYSTACK)
|
||
|
||
Returns true if and only if there is a match for the regex anywhere in the
|
||
haystack given.
|
||
|
||
It is recommended to use this method if all you need to do is test whether a
|
||
match exists, since the underlying matching engine may be able to do less work.
|
||
|
||
```lua
|
||
local re = kumo.regex.compile 'oo'
|
||
assert(re:is_match 'foo')
|
||
```
|
||
|
||
## regex:find(HAYSTACK)
|
||
|
||
Searches for the first match of this regex in the haystack given, and if found,
|
||
returns it as a string.
|
||
|
||
```lua
|
||
local re = kumo.regex.compile 'o+'
|
||
assert(re:find 'food' == 'oo')
|
||
assert(re:find 'fooood' == 'oooo')
|
||
```
|
||
|
||
## regex:find_all(HAYSTACK)
|
||
|
||
Searchs for successive non-overlapping matches in the given haystack, returning
|
||
the matches as an array-like table of the matching strings.
|
||
|
||
```lua
|
||
local re = kumo.regex.compile '\\b\\w{13}\\b'
|
||
local res =
|
||
re:find_all 'Retroactively relinquishing remunerations is reprehensible.'
|
||
assert(
|
||
kumo.json_encode(res)
|
||
== '["Retroactively","relinquishing","remunerations","reprehensible"]'
|
||
)
|
||
```
|
||
|
||
## regex:replace(TEXT, REPLACEMENT)
|
||
|
||
Replaces the leftmost-first match with the replacement provided. `$N` and
|
||
`$name` in the replacement string are expanded to match capture groups defined
|
||
in the regex.
|
||
|
||
If no match is found, then a copy of the string is returned unchanged.
|
||
|
||
All instances of `$name` in the replacement text is replaced with the
|
||
corresponding capture group name.
|
||
|
||
`name` may be an integer corresponding to the index of the capture group
|
||
(counted by order of opening parenthesis where `0` is the entire match) or it can
|
||
be a name (consisting of letters, digits or underscores) corresponding to a
|
||
named capture group.
|
||
|
||
If `name` isn’t a valid capture group (whether the name doesn’t exist or isn’t
|
||
a valid index), then it is replaced with the empty string.
|
||
|
||
The longest possible `name` is used. e.g., `$1a` looks up the capture group
|
||
named `1a` and not the capture group at index `1`. To exert more precise
|
||
control over the name, use braces, e.g., `${1}a`.
|
||
|
||
To write a literal `$` use `$$`.
|
||
|
||
```lua
|
||
local re = kumo.regex.compile '[^01]+'
|
||
assert(re:replace('1078910', '') == '1010')
|
||
```
|
||
|
||
```lua
|
||
local re = kumo.regex.compile '(?P<last>[^,\\s]+),\\s+(?P<first>\\S+)'
|
||
assert(
|
||
re:replace('Springsteen, Bruce', '$first $last') == 'Bruce Springsteen'
|
||
)
|
||
```
|
||
|
||
## regex:replace_all(TEXT, REPLACEMENT)
|
||
|
||
Replaces all non-overlapping matches in text with the replacement provided.
|
||
This is the same as calling `replacen` with `limit` set to `0`.
|
||
|
||
See the documentation for `replace` for details on how to access capturing
|
||
group matches in the replacement string.
|
||
|
||
## regex:replacen(TEXT, LIMIT, REPLACEMENT)
|
||
|
||
Replaces at most limit non-overlapping matches in text with the replacement
|
||
provided. If limit is `0`, then all non-overlapping matches are replaced.
|
||
|
||
See the documentation for `replace` for details on how to access capturing
|
||
group matches in the replacement string.
|
||
|
||
## regex:split(TEXT)
|
||
|
||
Splits `text` by the regex, returning each delimited string in an array-style
|
||
table.
|
||
|
||
```lua
|
||
local re = kumo.regex.compile '[ \\t]+'
|
||
local res = re:split 'a b \t c\td e'
|
||
assert(kumo.json_encode(res) == '["a","b","c","d","e"]')
|
||
```
|
||
|