mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-19 19:08:17 +00:00
Wez Furlong
42bf5c5e61
We've been hoping that mkdocs-material will ship the much anticipated search enhancements for some time, but it's time to recognize that we need to do something to improve the search results with how things work right now. This is a big commit that changes the titles of the various pages from the code-annotated synopsis to just the name of the function. This makes it much easier now to match things like `kumo.reject` directly, but `reject` remains awkward to find. I think this is the best that we can do at this time. A few functions have been annotated with the `status: deprecated` to show as deprecated in the toc/nav (shows with a little trash can next to the name).
154 lines
4.8 KiB
Markdown
154 lines
4.8 KiB
Markdown
# kumo.regex.compile
|
||
|
||
```lua
|
||
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"]')
|
||
```
|
||
|