DominScript — regex

10 functionsnamespace regexsource plugins/regex/RegexPlugin.c

POSIX extended-regex thin wrapper for DominScript. The pattern dialect is POSIX Extended Regular Expressions (ERE), the same dialect as egrep / grep -E — the regex.h baseline on every supported platform (glibc on Linux; MinGW/UCRT on Windows ship a POSIX-compatible regex.h, e.g. through tre).

Handle model

regex.Compile returns an i64 handle that owns the compiled pattern and its last-match buffer: a successful regex.Match stores the match positions inside the handle, and the Group / GroupStart / GroupEnd verbs then read from it. The matched text is copied into the handle, so the script may mutate or drop the source string afterwards.

Threading

Each handle owns its own last-match state — Match on handle A does not affect handle B. Concurrent Match calls on the same handle are unsafe, matching the single-owner convention of the rest of the plugin family.

Compile and release

Building a pattern handle and giving it back.

regex.Compile

regex.Compile($Pattern) -> i64 handle | -1

Compiles a POSIX ERE pattern and returns a handle. Returns -1 when the pattern does not compile.

Parameters

Parameter	Type	Description
Pattern	string	POSIX extended regular expression.

regex.CompileFlags

regex.CompileFlags($Pattern, $Flags) -> i64 handle | -1

Like regex.Compile, with a flag bitmask: 1 = REG_ICASE (case-insensitive), 2 = REG_NEWLINE (^/$ match line ends; . excludes newline), 4 = REG_NOSUB (no capture-group bookkeeping; faster when groups are not needed).

Parameters

Parameter	Type	Description
Pattern	string	POSIX extended regular expression.
Flags	int	Bitmask: 1 ICASE · 2 NEWLINE · 4 NOSUB.

regex.Free

regex.Free($Handle) -> i32 0

Releases the handle. Idempotent — Free on an unknown handle also returns 0.

Parameters

Parameter	Type	Description
Handle	int	Handle from regex.Compile.

When to use

Free every compiled handle when done; handles are a finite per-process resource.

Matching and groups

Running the pattern and reading the last match.

regex.Match

regex.Match($Handle, $Text) -> i32 1|0

Runs the pattern against the text; returns 1 on match, 0 otherwise. On success the match positions are stored in the handle so subsequent Group / GroupStart / GroupEnd calls refer to this match.

Parameters

Parameter	Type	Description
Handle	int	Handle from regex.Compile.
Text	string	The text to search; copied into the handle.

regex.GroupCount

regex.GroupCount($Handle) -> i32

The number of capture groups in the compiled pattern (not counting group 0, the whole match).

Parameters

Parameter	Type	Description
Handle	int	Handle from regex.Compile.

regex.Group

regex.Group($Handle, $Index) -> string

The text of a capture group from the last successful Match. Index 0 is the entire match, 1..N are the capture groups. Returns "" when there is no last match or the index is out of range.

Parameters

Parameter	Type	Description
Handle	int	Handle from regex.Compile.
Index	int	0 = whole match, 1..N = capture groups.

regex.GroupStart

regex.GroupStart($Handle, $Index) -> i64

Byte offset where the group starts in the matched text; -1 when there is no last match or the index is out of range.

Parameters

Parameter	Type	Description
Handle	int	Handle from regex.Compile.
Index	int	0 = whole match, 1..N = capture groups.

regex.GroupEnd

regex.GroupEnd($Handle, $Index) -> i64

Byte offset one past the end of the group; -1 when there is no last match or the index is out of range.

Parameters

Parameter	Type	Description
Handle	int	Handle from regex.Compile.
Index	int	0 = whole match, 1..N = capture groups.

Replacement

Rewriting text with capture-group escapes.

regex.Replace

regex.Replace($Handle, $Text, $Replacement) -> string

Replaces the first match in the text. Escape syntax inside the replacement: \0..\9 insert capture group N (\0 = whole match), \\ is a literal backslash, \& a literal &. Any other \x pair stays verbatim, so plain replacement text needs no escaping.

Parameters

Parameter	Type	Description
Handle	int	Handle from regex.Compile.
Text	string	Input text.
Replacement	string	Replacement with \N group escapes.

regex.ReplaceAll

regex.ReplaceAll($Handle, $Text, $Replacement) -> string

Replaces every non-overlapping match; same replacement escape syntax as regex.Replace.

Parameters

Parameter	Type	Description
Handle	int	Handle from regex.Compile.
Text	string	Input text.
Replacement	string	Replacement with \N group escapes.

Worked example

plugin "../plugins/regex/RegexPlugin";
plugin "../plugins/print/PrintPlugin";

void main()
{
    i64 $R = regex.Compile("([_[:alnum:]]+)@([_[:alnum:]]+\\.[_[:alnum:]]+)");
    printf("compile_ok=%d\n", $R > 0);
    printf("group_count=%d\n", regex.GroupCount($R));

    string $T1[64] = "alice@example.com";
    printf("match1=%d\n", regex.Match($R, $T1));
    printf("g0=%s g1=%s g2=%s\n",
           regex.Group($R, 0), regex.Group($R, 1), regex.Group($R, 2));

    regex.Free($R);
}

Output after running

compile_ok=1
group_count=2
match1=1
g0=alice@example.com g1=alice g2=example.com