tecs.regex#

Compiled regular expressions over Lua byte strings.

Patterns use the Rust regex crate's syntax. Compilation builds the automaton once; every method on the returned Regex reuses it. Inline flags such as (?i) and (?m) configure a pattern without a second options vocabulary.

local trailingDigits <const> = tecs.regex.compile([[(\d+)$]])

local frame <const> = trailingDigits:find("sprites/hero_04")
if frame ~= nil then
    print(frame.value, frame.first, frame.last)
end

print(trailingDigits:replaceAll("hero_04 orc_11", "N"))

Subjects remain byte strings, including strings that are not valid UTF-8. Match positions therefore follow Lua's string functions: 1-based, inclusive byte indices. An empty match has last == first - 1.

Module contents#

Types#

Functions#

Types#

tecs.regex.Captures record#

Contains a whole match and its populated capture groups.

record tecs.regex.Captures
    whole: Match
    groups: {Match}
    groupCount: integer
    named: {string: Match}
end

tecs.regex.Captures.whole field#

Read-only. Contains group zero, which covers the whole match.

tecs.regex.Captures.whole: Match

tecs.regex.Captures.groups field#

Read-only. Contains explicit groups by their 1-based index. An unmatched optional group leaves a hole.

tecs.regex.Captures.groups: {Match}

tecs.regex.Captures.groupCount field#

Read-only. Reports the number of explicit groups in the pattern, including groups that did not match.

tecs.regex.Captures.groupCount: integer

tecs.regex.Captures.named field#

Read-only. Maps matched group names to the same values in groups.

tecs.regex.Captures.named: {string: Match}

tecs.regex.Match record#

Describes one matched byte range.

record tecs.regex.Match
    value: string
    first: integer
    last: integer
    index: integer
    name: string
end

tecs.regex.Match.value field#

Read-only. Contains the bytes copied from the matched range.

tecs.regex.Match.value: string

tecs.regex.Match.first field#

Read-only. Reports the first matched byte using a 1-based index.

tecs.regex.Match.first: integer

tecs.regex.Match.last field#

Read-only. Reports the inclusive last matched byte. An empty match reports first - 1.

tecs.regex.Match.last: integer

tecs.regex.Match.index field#

Read-only. Reports the capture-group index, with zero for the whole match.

tecs.regex.Match.index: integer

tecs.regex.Match.name field#

Read-only. Contains the capture name, or nil for an unnamed group.

tecs.regex.Match.name: string

tecs.regex.Regex record#

Represents a compiled Rust regular expression.

record tecs.regex.Regex
    pattern: string

    captures: function(self, subject: string, init: integer): Captures
    find: function(self, subject: string, init: integer): Match
    isMatch: function(self, subject: string): boolean
    replace: function(
        self, subject: string, replacement: string
    ): string
    replaceAll: function(
        self, subject: string, replacement: string
    ): string
end

tecs.regex.Regex.pattern field#

Read-only. Contains the source pattern unchanged.

tecs.regex.Regex.pattern: string

tecs.regex.Regex:captures Instance#

Finds the first match and every capture group it populated.

groups may contain holes when optional groups do not participate; iterate through groupCount, not #groups. A named entry aliases the same Match stored at its numbered index.

function tecs.regex.Regex.captures(
    self, subject: string, init: integer
): Captures

Arguments

Returns

tecs.regex.Regex:find Instance#

Finds the first match at or after a byte position.

function tecs.regex.Regex.find(
    self, subject: string, init: integer
): Match

Arguments

Returns

Examples#

local regex <const> = require("tecs.regex").compile([[\d+]])
local found <const> = assert(regex:find("hp=100"))

assert(found.value == "100")

tecs.regex.Regex:isMatch Instance#

Reports whether any part of a subject matches.

function tecs.regex.Regex.isMatch(self, subject: string): boolean

Arguments

Returns

Examples#

local regex <const> = require("tecs.regex").compile([[\.(png|jpg)$]])

assert(regex:isMatch("sprite.png"))

tecs.regex.Regex:replace Instance#

Replaces the first match.

The method expands capture references in the replacement: $0 is the whole match, $1 is the first group, $name and ${name} select a named group, and $$ writes one dollar sign. A reference the pattern does not declare expands to an empty string.

function tecs.regex.Regex.replace(
    self, subject: string, replacement: string
): string

Arguments

Returns

Examples#

local regex <const> = require("tecs.regex").compile([[(\w+)=(\d+)]])

assert(regex:replace("hp=100 mp=50", "$1: $2") == "hp: 100 mp=50")

tecs.regex.Regex:replaceAll Instance#

Replaces every non-overlapping match.

function tecs.regex.Regex.replaceAll(
    self, subject: string, replacement: string
): string

Arguments

Returns

Examples#

local regex <const> = require("tecs.regex").compile([[\d+]])

assert(regex:replaceAll("room 12, floor 3", "#") == "room #, floor #")

Functions#

tecs.regex.compile Static#

Compiles a Rust regular expression.

Compilation raises on malformed syntax or a pattern that is not UTF-8. Rust's Unicode character classes work by default; use inline flags to change the expression, such as (?i) for case-insensitive matching or (?-u:.) for one arbitrary byte.

Keep the returned object and reuse it. The Lua collector releases its native allocation automatically.

function tecs.regex.compile(pattern: string): Regex

Arguments#

Returns#