RegEx API

Compiled regular expressions with PCRE2 syntax: named groups, lookarounds, match objects, and substitution.

Overview

The global identifier RegEx is a constructor namespace. Calling one of its constructors returns a regex instance whose methods are invoked as r.method(...). Successful searches yield RegExMatch instances with their own method set.

Conventions

• Pattern syntax. Patterns use PCRE2 syntax: lookarounds, named groups ((?<name>...)), Unicode classes, alternation, quantifiers, back-references, and inline flags ((?i), (?m), ...).
• Strings. All subjects, replacements, and group strings are Zym strings. Offsets are byte positions in the UTF-8 representation of the subject.
• Indices. Group 0 is the whole match. Capturing groups are numbered from 1; negative indices are rejected at runtime as invalid.
• Group lookup. Methods that take a name argument (string, start, end) accept either a number (group index) or a string (named-capture identifier). Other types raise a runtime error.
• Assignment aliases. Plain assignment (r2 = r1) makes r2 refer to the same compiled pattern as r1. Recompiling through one name is visible through the other.
• Errors. Bad argument types raise a Zym runtime error of the form RegEx.method(args) ... or RegExMatch.method(args) .... Calling search, searchAll, or sub on an uncompiled or invalid pattern raises ... pattern is not compiled.

Construction

Compiles pattern and returns a new regex instance. Returns null if the pattern fails to compile. This is the common entry point.

• pattern (string) — the regular expression source, in PCRE2 syntax

Returns: A compiled regex instance, or null on a compile failure.

var r = RegEx.create("([")
if (r == null) {
    print("invalid pattern")
}

Returns an uncompiled regex instance; call r.compile(pattern) before use. Provided for the rare case where you want to build an uncompiled instance and decide the pattern later. Otherwise, prefer RegEx.create.

Compilation & State

Returns true when a pattern has been successfully compiled, false otherwise.

Returns the most recently supplied source pattern, or "" for an instance that has never been compiled. clear() invalidates the compiled state but does not zero this string.

Compiles pattern, replacing any previous pattern. Returns true on success, false on a syntax error.

• pattern (string) — the regular expression source, in PCRE2 syntax

Drops the compiled pattern so the instance becomes invalid. After this call isValid() is false; pattern() still reports the last source string that was supplied. Returns null.

var r = RegEx.empty()
print(r.isValid())        // false
print(r.compile("\\d+"))  // true
print(r.pattern())        // "\\d+"
r.clear()
print(r.isValid())        // false
print(r.pattern())        // still "\\d+"

Group Metadata

Returns the number of capturing groups in the pattern, excluding group 0. Returns 0 for an uncompiled instance.

Returns a list of the named-capture identifiers declared in the pattern, in the order they appear. Unnamed groups are not represented; use groupCount() for the total number of capturing groups.

var r = RegEx.create("(?<year>\\d{4})-(\\d{2})")
print(r.groupCount())   // 2
print(r.names())        // list with one entry: "year"

Matching

Searches subject for the first match. Returns a RegExMatch instance, or null if nothing matches.

• subject (string) — the string to search
• offset (number, optional) — byte offset to start from (default: 0)
• end (number, optional) — byte offset to stop at; -1 means end-of-string (default: -1)

Returns every non-overlapping match in subject as a list of RegExMatch instances. Returns an empty list when nothing matches.

• subject (string) — the string to search
• offset (number, optional) — byte offset to start from (default: 0)
• end (number, optional) — byte offset to stop at; -1 means end-of-string (default: -1)

Substitutes matches in subject with replacement and returns the resulting string. The replacement string supports back-references (\\1, \\g<name>).

• subject (string) — the string to operate on
• replacement (string) — the replacement text; may contain back-references
• all (boolean, optional) — replace every match when true; replace only the first when false (default: false)
• offset (number, optional) — byte offset to start from (default: 0)
• end (number, optional) — byte offset to stop at; -1 means no limit (default: -1)

var r = RegEx.create("\\d+")
print(r.sub("hello 42 world 7", "X", false))  // "hello X world 7"
print(r.sub("hello 42 world 7", "X", true))   // "hello X world X"

RegExMatch

Returned by r.search and r.searchAll. Methods are invoked as m.method(...).

Returns the original subject the match was produced from.

Returns the number of capturing groups, excluding group 0.

Returns a map of named-group identifier to group index.

Returns all matched substrings as a list, with the whole match at index 0 followed by each capturing group. Unmatched groups are empty strings.

Returns the substring for the given group.

• name (number or string) — group index, or named-capture identifier

Returns the byte offset where the group starts.

• name (number or string) — group index, or named-capture identifier

Returns the byte offset just past the end of the group.

• name (number or string) — group index, or named-capture identifier

Examples

Find a Single Match

var r = RegEx.create("(?<word>\\w+)\\s+(\\d+)")
var m = r.search("hello 42 world 7")
print(m.string(0))        // "hello 42"
print(m.string("word"))   // "hello"
print(m.string(2))        // "42"
print(m.start(0))         // 0
print(m.end(0))           // 8

Iterate Every Match

var r = RegEx.create("\\d+")
var hits = r.searchAll("hello 42 world 7")
for (var i = 0; i < length(hits); i = i + 1) {
    print(hits[i].string(0))   // "42", then "7"
}

Extract Named Groups

var r = RegEx.create("(?<key>\\w+)=(?<value>\\w+)")
var m = r.search("mode=fast")
print(m.strings())          // list: "mode=fast", "mode", "fast"
print(m.names())            // map: "key" -> 1, "value" -> 2
print(m.string("value"))    // "fast"