re
LPeg 1.1's official re frontend, bundled so require("re") returns it.
This is upstream's Lua source, carried rather than reimplemented: it compiles re pattern text into LPeg patterns at runtime, and its compile, match, find, gsub and updatelocale behave exactly as LPeg's own documentation describes. It is here for Lua that already requires it, and because nupp.peg.compile reaches it for a grammar only known at run time.
Write nupp.peg instead. It accepts the same syntax at either phase: a comptime grammar is parsed and validated by the compiler and carries typed captures, and a genuinely dynamic one compiles through nupp.peg.compile and returns Peg<...any>. Both spellings select the same native LPeg feature, so requiring this module directly buys no portability -- only untyped results.
Module contents
Functions
| Function | Kind | Description |
|---|---|---|
compile | function | Compiles re pattern text into an LPeg pattern. |
find | function | Searches s for the first position at or after i where the pattern matches. |
gsub | function | Replaces every match of the pattern in s. |
match | function | Matches a pattern against s, anchored at i. |
updatelocale | function | Rereads the locale, so the predefined classes follow it. |
Functions#
re.compilefunction#
function re.compile(p, defs): anyCompiles re pattern text into an LPeg pattern.
An argument that is already an LPeg pattern is handed back unchanged, so a caller may accept either spelling. Nothing is cached here: match, find and gsub keep their own caches, and a pattern compiled with definitions is not a function of its text alone.
Arguments
| Name | Type | Description |
|---|---|---|
p | any | the pattern text, or an LPeg pattern to pass through |
defs | any | the values |
Returns
| Type | Description |
|---|---|
any | the compiled LPeg pattern |
Raises
| Type | Condition |
|---|---|
string | when the text is not a well-formed pattern, or names something |
re.findfunction#
function re.find(s, p, i): ((integer, integer) | (nil))Searches s for the first position at or after i where the pattern matches.
The pattern's own captures are discarded: what a search returns is where the match is, and a caller wanting the captures matches at the position it reports.
Arguments
| Name | Type | Description |
|---|---|---|
s | any | the subject bytes |
p | any | the pattern text, or an LPeg pattern |
i | any | the 1-based position to begin searching at, or nil for the beginning |
Returns
| Type | Description |
|---|---|
((integer, integer) | (nil)) | the 1-based positions the match begins and ends at, both inclusive, or nil when the pattern matches nowhere at or after |
Raises
| Type | Condition |
|---|---|
string | when the text is not a well-formed pattern |
re.gsubfunction#
function re.gsub(s, p, rep): stringReplaces every match of the pattern in s.
Arguments
| Name | Type | Description |
|---|---|---|
s | any | the subject bytes |
p | any | the pattern text, or an LPeg pattern |
rep | any | a replacement string, a table the first capture indexes, or a function of the captures |
Returns
| Type | Description |
|---|---|
string | the subject with every match replaced |
Raises
| Type | Condition |
|---|---|
string | when the text is not a well-formed pattern |
re.matchfunction#
function re.match(s, p, i): ...anyMatches a pattern against s, anchored at i.
The pattern has to match at the starting position rather than somewhere after it; find is the searching form. Compiled patterns are cached weakly by their text, so repeating one does not recompile it. A pattern needing definitions cannot be spelled here, because the cache is keyed by text alone: compile it with compile and match the result.
Arguments
| Name | Type | Description |
|---|---|---|
s | any | the subject bytes |
p | any | the pattern text, or an LPeg pattern |
i | any | the 1-based position to match at, or nil for the beginning |
Returns
| Type | Description |
|---|---|
...any | the pattern's captures, or the position after the match when it captures nothing, or nil when it does not match |
Raises
| Type | Condition |
|---|---|
string | when the text is not a well-formed pattern |
re.updatelocalefunction#
function re.updatelocale()Rereads the locale, so the predefined classes follow it.
%a, %d, %s and the rest of the predefined classes are read out of the locale when this module loads. Call this after changing the locale to rebuild them. It also empties the pattern caches match, find and gsub keep, since a cached pattern still holds the classes it was compiled against.