lib/regex.x

Regular expressions over the bytes of a String.

Primary API

Regex

Regex.capture_count

int Regex.capture_count(Regex regex)

Returns the number of capturing groups in regex.

Source: lib/regex.x:630

Regex.capture_names

List Regex.capture_names(Regex regex)

Returns the names of the capturing groups of regex in capture order, with NULL for a group without a name.

Source: lib/regex.x:635

Regex.cleanup

void Regex.cleanup(Regex)

Provides the class default for Regex.cleanup.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Regex.compile

Regex Regex.compile(String pattern)

Compiles pattern and returns the Regex, owned by the current scope.

Raises: <bad-arg> with why, the pattern, and the byte offset of the problem when the pattern does not parse.

Source: lib/regex.x:624

Regex.equal

int Regex.equal(Regex, Regex)

Provides the class default for Regex.equal.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Regex.escape

String Regex.escape(String literal)

Returns literal with every ASCII byte that is not a letter, digit, or underscore escaped, so that it matches itself inside a pattern.

Source: lib/regex.x:640

Regex.find_all

List Regex.find_all(Regex r, String subject)

Returns every non-overlapping match of r in subject, in order. An empty match advances one byte. No match returns an empty List.

Source: lib/regex.x:663

Regex.free

void Regex.free(Regex)

Provides the class default for Regex.free.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Regex.hash

unsigned Regex.hash(Regex)

Provides the class default for Regex.hash.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Regex.match

RegexMatch Regex.match(Regex r, String subject)

Returns the first match of r in subject, or NULL.

Source: lib/regex.x:658

Regex.match_from

RegexMatch Regex.match_from(Regex r, String subject, int offset)

Returns the first match of r in subject at or after the byte offset, or NULL. An offset beyond the end of subject finds nothing.

Source: lib/regex.x:654

Regex.pattern

String Regex.pattern(Regex regex)

Returns the text regex was compiled from.

Source: lib/regex.x:627

Regex.replace

String Regex.replace(Regex regex, String subject, String replacement)

Returns subject with the first match of regex replaced. In replacement, $0 through $9 and ${name} insert a capture and $$ is a dollar sign.

Source: lib/regex.x:689

Regex.replace_all

String Regex.replace_all(Regex regex, String subject, String replacement)

Returns subject with every match of regex replaced, expanding replacement as replace does.

Source: lib/regex.x:695

Regex.replace_fn

String Regex.replace_fn(Regex regex, String subject, Func fn)

Returns subject with every match of regex replaced by what fn returns for its RegexMatch, inserted as is.

Raises: whatever fn raises.

Source: lib/regex.x:702

Regex.repr

String Regex.repr(Regex)

Provides the class default for Regex.repr.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Regex.split

List Regex.split(Regex regex, String subject)

Returns the text of subject between the matches of regex, keeping an empty field where two matches touch or a match sits at either end.

Source: lib/regex.x:674

Regex.str

String Regex.str(Regex)

Provides the class default for Regex.str.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Regex.var

Var Regex.var(Regex)

Provides the class default for Regex.var.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Regex.write_repr

Buffer Regex.write_repr(Regex, Buffer)

Provides the class default for Regex.write_repr.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Regex.write_str

Buffer Regex.write_str(Regex, Buffer)

Provides the class default for Regex.write_str.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

RegexCapture

RegexCapture.end

int RegexCapture.end(RegexCapture capture)

Returns the byte offset just past the capture, or -1.

Source: lib/regex.x:742

RegexCapture.index

int RegexCapture.index(RegexCapture capture)

Returns the capture number, with 0 for the whole match.

Source: lib/regex.x:727

RegexCapture.matched

int RegexCapture.matched(RegexCapture capture)

Reports whether the capture took part in the match.

Source: lib/regex.x:733

RegexCapture.name

String RegexCapture.name(RegexCapture capture)

Returns the capture’s name, or NULL.

Source: lib/regex.x:730

RegexCapture.start

int RegexCapture.start(RegexCapture capture)

Returns the byte offset where the capture starts, or -1.

Source: lib/regex.x:739

RegexCapture.text

String RegexCapture.text(RegexCapture capture)

Returns the matched text, or NULL for a capture that did not take part.

Source: lib/regex.x:736

RegexMatch

RegexMatch.capture

RegexCapture RegexMatch.capture(RegexMatch found, Var key)

Returns the capture of found selected by key: a capture number, or a name as a Symbol or String. NULL when there is no such capture.

Source: lib/regex.x:708

RegexMatch.getindex

String RegexMatch.getindex(RegexMatch found, Var key)

Returns the text of the capture selected by key, or NULL when the capture does not exist or did not take part in the match.

Source: lib/regex.x:721

Var

Var.regex

Regex Var.regex(Var)

Provides the class default for Var.regex.

See Classes and system macros for the default behavior.

Source: lib/regex.x:27

Var.regexcapture

RegexCapture Var.regexcapture(Var value)

Reads a RegexCapture back out of a Var, as foreach does.

Source: lib/regex.x:745

Var.regexmatch

RegexMatch Var.regexmatch(Var value)

Reads a RegexMatch back out of a Var, as foreach does.

Source: lib/regex.x:748

Public types

Regex

class Regex struct { String pattern; _RegexNode program; int capture_count; List capture_names; int caseless, multiline, dotall; } *

A compiled pattern. Regex.compile makes one; the scope that made it frees it. A RegexMatch is the List of RegexCaptures of one match, indexed by capture number or name; each capture is the List of its index, name, whether it took part, text, start, and end.

Source: lib/regex.x:27

RegexCapture

typedef List RegexCapture

One capture of a match: index, name, matched, text, start, end.

Source: lib/regex.x:36

RegexMatch

typedef List RegexMatch

The captures of one match, with the whole match at index 0.

Source: lib/regex.x:39

Design notes

A Regex is a compiled pattern, owned by the scope that compiled it. A RegexMatch and a RegexCapture are immutable Lists, so their Strings and offsets stay valid after the next match. Matching backtracks over a small node tree; a repeated single byte class runs as a loop, so the common .* and \w+ forms do not recurse per byte.

The syntax is the byte-oriented subset described in the book’s “Patterns” section: sets, ., anchors, word boundaries, greedy and lazy repetition, alternation, numbered and named captures, and the leading (?i), (?m), and (?s) flags.

Tests and examples

make verify (unittest/test-regex.x).