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:723

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:728

Regex.compile

Regex Regex.compile(String pattern)

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

Raises: <malformed> with reason, the pattern, and the byte offset of the problem when the pattern does not parse.

Source: lib/regex.x:717

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:733

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:758

Regex.match

RegexMatch Regex.match(Regex r, String subject)

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

Source: lib/regex.x:753

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:749

Regex.pattern

String Regex.pattern(Regex regex)

Returns the text regex was compiled from.

Source: lib/regex.x:720

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:785

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:791

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:798

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:769

RegexCapture

RegexCapture.end

int RegexCapture.end(RegexCapture capture)

Returns the byte offset after the capture, or -1.

Source: lib/regex.x:840

RegexCapture.index

int RegexCapture.index(RegexCapture capture)

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

Source: lib/regex.x:825

RegexCapture.matched

int RegexCapture.matched(RegexCapture capture)

Reports whether the capture took part in the match.

Source: lib/regex.x:831

RegexCapture.name

String RegexCapture.name(RegexCapture capture)

Returns the capture’s name, or NULL.

Source: lib/regex.x:828

RegexCapture.start

int RegexCapture.start(RegexCapture capture)

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

Source: lib/regex.x:837

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:834

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:806

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:819

Var

Var.regexcapture

meta native RegexCapture Var.regexcapture(Var v)

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

Source: lib/regex.x:843

Var.regexmatch

meta native RegexMatch Var.regexmatch(Var value)

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

Source: lib/regex.x:846

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:23

RegexCapture

typedef List RegexCapture

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

Source: lib/regex.x:34

RegexMatch

typedef List RegexMatch

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

Source: lib/regex.x:37

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 in the book’s “Patterns” section.

Tests and examples

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