PCRE2-based regular expression module. Supports Perl-compatible regex with compilation, matching, searching, replacement, and splitting.

:::note Optional capability This module is a typed facade over an optional PCRE2 backend. In builds without PCRE2 support, require("@eryx/regex") fails immediately with a clear capability error. :::

Flags string characters:

• i = case-insensitive
• m = multiline (^ and $ match line boundaries)
• s = dotall (. matches newlines)
• x = extended (ignore whitespace and # comments in pattern)
• u = UTF-8 mode
• U = ungreedy (swap greediness of quantifiers)
• n = no auto capture (plain parentheses don't capture)

Summary

Classes

Functions

API Reference

Classes

Regex

A compiled regular expression pattern.

Properties

Regex:isMatch

Test if the subject matches this pattern.

Regex:isMatch(subject: string, offset: number?) → boolean

Parameters

subject: string

the string to test

offset: number?

1-based start position (default 1)

Returns

boolean

boolean

Regex:find

Find the first match of this pattern in the subject. Returns nil if no match. The result table contains:

• match: the full matched text
• start: 1-based start position
• finish: 1-based end position (inclusive)
• [1], [2], ...: numbered capture groups
• named fields for named capture groups

Regex:find(subject: string, offset: number?) → MatchResult?

Parameters

subject: string

the string to search

offset: number?

1-based start position (default 1)

Returns

MatchResult?

MatchResult?

Regex:findAll

Find all non-overlapping matches in the subject.

Regex:findAll(subject: string) → { MatchResult }

Parameters

subject: string

the string to search

Returns

{ MatchResult }

{MatchResult}

Regex:replace

Replace matches in the subject with a replacement string. The replacement supports $0 (full match), $1, ${name} backreferences.

Regex:replace(subject: string, replacement: string, limit: number?) → string

Parameters

subject: string

the input string

replacement: string

the replacement template

limit: number?

max replacements (0 or nil = replace all)

Returns

string

string

Regex:split

Split the subject on matches of this pattern. If the pattern has captures, captured groups are included between splits.

Regex:split(subject: string, limit: number?) → { string }

Parameters

subject: string

the string to split

limit: number?

max number of pieces (0 or nil = no limit)

Returns

{ string }

{string}

Regex:captureCount

Return the number of capture groups in the pattern.

Regex:captureCount() → number

Returns

number

number

Regex:namedCaptures

Return a table mapping named capture group names to their group numbers.

Regex:namedCaptures() → { [string]: number }

Returns

{ [string]: number }

{[string]: number}

Functions

regex.new

Compile a regex pattern into a reusable Regex object.

regex.new(pattern: string, flags: string?) → Regex

Parameters

pattern: string

the PCRE2 regular expression

flags: string?

flag characters: i, m, s, x, u, U, n

Returns

Regex

Regex

regex.isMatch

Test if a pattern matches a subject. Convenience function that compiles the pattern each call; use regex.new() for repeated use.

regex.isMatch(pattern: string, subject: string, flags: string?) → boolean

Parameters

pattern: string

the PCRE2 regular expression

subject: string

the string to test

flags: string?

flag characters

Returns

boolean

boolean

regex.find

Find the first match of a pattern in a subject.

regex.find(pattern: string, subject: string, flags: string?) → MatchResult?

Parameters

pattern: string

the PCRE2 regular expression

subject: string

the string to search

flags: string?

flag characters

Returns

MatchResult?

MatchResult?

regex.findAll

Find all non-overlapping matches of a pattern in a subject.

regex.findAll(pattern: string, subject: string, flags: string?) → { MatchResult }

Parameters

pattern: string

the PCRE2 regular expression

subject: string

the string to search

flags: string?

flag characters

Returns

{ MatchResult }

{MatchResult}

regex.replace

Replace all matches of a pattern in a subject. Replacement supports $0, $1, ${name} backreferences.

regex.replace(pattern: string, subject: string, replacement: string, flags: string?) → string

Parameters

pattern: string

the PCRE2 regular expression

subject: string

the input string

replacement: string

the replacement template

flags: string?

flag characters

Returns

string

string

regex.split

Split a subject on all matches of a pattern.

regex.split(pattern: string, subject: string, flags: string?) → { string }

Parameters

pattern: string

the PCRE2 regular expression

subject: string

the string to split

flags: string?

flag characters

Returns

{ string }

{string}

regex.escape

Escape all PCRE2 metacharacters in a string so it can be used as a literal pattern.

regex.escape(str: string) → string

Parameters

str: string

the string to escape

Returns

string

string

Types

MatchResult

Result of a regex match operation.

type MatchResult = { [number | string]: string? }

match: string

start: number

finish: number

Constants

• Compile-time flag constants (Exact values depend on PCRE2, and are not documented here.)
• regex.CASELESS = 0
• regex.MULTILINE = 0
• regex.DOTALL = 0
• regex.EXTENDED = 0
• regex.UTF = 0
• regex.UNGREEDY = 0
• regex.NO_AUTO_CAPTURE = 0
• regex.ANCHORED = 0
• regex.ENDANCHORED = 0
• regex.UCP = 0
• regex.DUPNAMES = 0