Skip to main content
Version: Unreleased

Regex API

Regular expression helpers are available under ptool.re and p.re.

ptool.re.compile​

v0.1.0 - Introduced.

ptool.re.compile(pattern[, opts]) compiles a regular expression and returns a Regex object.

  • pattern (string, required): The regex pattern.
  • opts (table, optional): Compile options. Currently supported:
    • case_insensitive (boolean, optional): Whether matching is case-insensitive. Defaults to false.

Example:

local re = ptool.re.compile("(?P<name>\\w+)", { case_insensitive = true })
print(re:is_match("Alice")) -- true

ptool.re.escape​

v0.1.0 - Introduced.

ptool.re.escape(text) escapes plain text into a regex literal string.

  • text (string, required): The text to escape.
  • Returns: The escaped string.

Example:

local keyword = "a+b?"
local re = ptool.re.compile("^" .. ptool.re.escape(keyword) .. "$")
print(re:is_match("a+b?")) -- true

Regex​

v0.1.0 - Introduced.

Regex represents a compiled regular expression returned by ptool.re.compile(...).

It is implemented as a Lua userdata.

Methods:

  • re:is_match(input) -> boolean
  • re:find(input[, init]) -> Match|nil
  • re:find_all(input) -> Match[]
  • re:captures(input) -> Captures|nil
  • re:captures_all(input) -> Captures[]
  • re:replace(input, replacement) -> string
  • re:replace_all(input, replacement) -> string
  • re:split(input[, limit]) -> string[]

is_match​

Canonical API name: ptool.re.Regex:is_match.

re:is_match(input) checks whether the regex matches input.

  • input (string, required): The input text.
  • Returns: boolean.

find​

Canonical API name: ptool.re.Regex:find.

re:find(input[, init]) returns the first match in input, or nil.

  • input (string, required): The input text.

Parameter notes:

  • init is a 1-based start position and defaults to 1.
  • limit must be greater than 0.

Return structures:

  • Match:
    • start (integer): The 1-based start index.
    • finish (integer): The end index, directly usable with string.sub.
    • text (string): The matched text.
  • Captures:
    • full (string): The full matched text.
    • groups (table): An array of capture groups in capture order. Unmatched groups are nil.
    • named (table): A mapping of named capture groups, keyed by group name.

find_all​

Canonical API name: ptool.re.Regex:find_all.

re:find_all(input) returns all matches in input as a Match[].

captures​

Canonical API name: ptool.re.Regex:captures.

re:captures(input) returns the first capture set in input, or nil.

captures_all​

Canonical API name: ptool.re.Regex:captures_all.

re:captures_all(input) returns all capture sets in input as a Captures[].

replace​

Canonical API name: ptool.re.Regex:replace.

re:replace(input, replacement) replaces the first match in input.

replace_all​

Canonical API name: ptool.re.Regex:replace_all.

re:replace_all(input, replacement) replaces all matches in input.

split​

Canonical API name: ptool.re.Regex:split.

re:split(input[, limit]) splits input using the regex as the separator.

Example:

local re = ptool.re.compile("(?P<word>\\w+)")
local cap = re:captures("hello world")
print(cap.full)         -- hello
print(cap.named.word)   -- hello
print(re:replace_all("a b c", "_")) -- _ _ _