Lrexlib Lua Regular Expression Bindings

To use Lrexlib, require the module corresponding to your chosen flavour (e.g., rex_pcre). The library provides functions for finding patterns and performing global substitutions.

Note that the module name follows the pattern rex_<flavour> (e.g., rex_pcre, rex_posix, etc.).

local rex = require "rex_pcre"
local subj = "We go to school"
local patt = "(\\w+)\\s+(\\w+)"
local repl = "%2 %1"

local from, to, cap1, cap2 = rex.find(subj, patt)
print(from, to, cap1, cap2)

local result = rex.gsub(subj, patt, repl)
print(result)

Lrexlib is installed using LuaRocks. You must specify a FLAVOUR during installation to choose which regular expression engine the bindings will use.

Available flavours:

• PCRE2 (Recommended for PCRE)
• PCRE (Obsolete PCRE version 1)
• POSIX
• oniguruma (Note: bindings are currently incomplete)
• TRE (Note: bindings are currently incomplete)
• GNU

luarocks install lrexlib-FLAVOUR

Returns an iterator for use in Lua's for construct to find all repeated matches.

Signature: rex.gmatch (subj, patt, [cf], [ef], [larg...]).

Returns:

• An iterator function. On each iteration, it returns all captures in order (or the entire match if no captures exist). Iteration stops when no more matches are found.

Use rex_tre.config([tb]) to retrieve the configuration parameters used during the TRE library build-time.

• If you provide a table tb, the function will populate that table with the configuration values.
• If no table is provided, a new table is created and returned.

local config = rex_tre.config()
print(config.some_param)

Matches a compiled regex using a DFA algorithm (PCRE 6.0+).

Signature: r:dfa_exec (subj, [init], [ef], [ovecsize], [wscount]).

Returns:

• Success:
  1. Start point of matches (number)
  2. A table of end points (sorted by length, longest first)
  3. The return value of the underlying pcre_dfa_exec call.
• Failure: nil.

Example: If 3 matches start at 10 and end at 15, 20, and 25, it returns: 10, { 25, 20, 15 }, 3.

Searches for the first match of a pattern in a subject string.

Signature: rex.match (subj, patt, [init], [cf], [ef], [larg...]) or r:match (subj, [init], [ef]) (where r is a compiled regex object).

Parameters:

• subj: The string to search.
• patt: The regex pattern (string or compiled userdata).
• [init]: Start offset (default: 1).
• [cf]: Compilation flags.
• [ef]: Execution flags.
• [larg...]: Library-specific arguments.

Returns:

• Success: All substring matches ("captures") in order. If no captures are defined, returns the whole matched substring. Sub-patterns that didn't participate return false.
• Failure: nil.

For TRE-based regex objects, you can query the properties of the compiled pattern:

• r:have_approx(): Returns true if the pattern uses approximate matching, false otherwise.
• r:have_backrefs(): Returns true if the pattern contains backreferences, false otherwise.

You can set the default regex syntax for the Oniguruma library using rex_onig.setdefaultsyntax(syntax). This syntax will be used by all relevant functions unless a specific syntax is passed to them explicitly.

The syntax parameter must be a string derived from the ONIG_SYNTAX_xxx identifiers in oniguruma.h by omitting the ONIG_SYNTAX_ prefix. For example, ONIG_SYNTAX_JAVA becomes "JAVA".

If an invalid syntax string is provided, an error is raised.

rex_onig.setdefaultsyntax ("ASIS") -- use plain text syntax as the default
rex_onig.setdefaultsyntax ("PERL") -- use PERL regex syntax as the default

When using the PCRE binding, rex.new allows specifying a locale.

Signature: rex.new (patt, [cf], [lo])

Parameters:

• lo: A string (e.g., "French_France.1252") or userdata from rex_pcre.maketables().
• Default: Built-in PCRE set of character tables.

A method for compiled regex objects to find the first match.

Signature: r:tfind (subj, [init], [ef]).

Returns:

• Success:
  1. Start point (number)
  2. End point (number)
  3. Substring matches (captures) in a table. For PCRE/PCRE2/Oniguruma, this table also includes named subpattern matches keyed by name.
• Failure: nil.

Searches for the first match and returns its boundaries and captures.

Signature: rex.find (subj, patt, [init], [cf], [ef], [larg...]) or r:find (subj, [init], [ef]).

Returns:

• Success:
  1. Start point (number)
  2. End point (number)
  3. All substring matches ("captures") in order (or false for non-participating sub-patterns).
• Failure: nil.