Regex (std)
std/regex is written in Agentica: import Regex from "std/regex". It takes the syntax of RE2 and Go, gives the leftmost-first match, and counts positions in characters, as index_of and slice do. Its matcher has no backtracking, so a search takes time in proportion to the length of the text times the size of the pattern, whatever the input. Nothing in it halts: a bad pattern or template is an error.
Regex.compile(pattern: String) -> Result[Regex.Regex]
Regex.match?(text: String, regex: Regex.Regex) -> Bool
Regex.match(text: String, regex: Regex.Regex) -> Result[Regex.Match]
Regex.find_all(text: String, regex: Regex.Regex) -> List[Regex.Match]
Regex.replace(text: String, regex: Regex.Regex, template: String) -> Result[String]
Regex.split(text: String, regex: Regex.Regex) -> List[String]
Regex.escape(text: String) -> String
Regex.named(match: Regex.Match, name: String) -> Result[Regex.Group]The text comes first, so a pipe reads like the call: text |> Regex.split(re). A fixed pattern is written as a regex literal, /pattern/flags; Regex.compile is for a pattern built at run time.
import Regex from "std/regex"
def read_year(text: String) -> Result[String]
found = try Regex.match(text, /(?P<year>\d{4})-\d{2}-\d{2}/)
year = try Regex.named(found, "year")
ok(year.text)
end
def main() -> Void
puts(read_year("released on 2026-11-01"))
puts(Regex.replace("Ada Lovelace", /(\w+) (\w+)/, "$2, $1"))
puts("a, b;c" |> Regex.split(/[,;]\s*/))
puts(Regex.find_all("7 apples, 12 pears", /\d+/).map do |m| m.text end)
puts(Regex.match?("No Digits", /digits/i))
fruit = Regex.compile("\\b" + Regex.escape("pears") + "\\b").unwrap!
puts(Regex.match?("7 pears", fruit))
puts(Regex.compile("(ab"))
endok("2026")
ok("Lovelace, Ada")
["a", "b", "c"]
["7", "12"]
true
true
error("character 4: missing ')' for the group at character 1", kind: "regex.syntax")Regex.escape(text) gives a pattern that matches text literally. A pattern given to Regex.compile is a String, so each backslash of the pattern is written twice: "\\d+" is the pattern \d+.
Regex literals #
A regex literal is Regex.compile of its body, checked when the program is compiled. The body is the pattern as written, with no string escapes: /\d+\.\d+/ is the pattern \d+\.\d+, and \/ is a slash. The file must import std/regex, in any form; without one the literal is CHECK-REGEX-IMPORT. A pattern that compile refuses is CHECK-INVALID-REGEX, at the character the error names, so a literal never fails at run time and needs no unwrap!. A literal in a function is built once, before main, even inside a loop.
- Flags follow the closing slash:
iignores case and is(?i);mlets.match a newline and is(?s)./a.b/imis the pattern(?is)a.b, which is also itssource. Another letter, or a flag written twice, isLEX-REGEX-FLAG. #{cannot appear in the body (LEX-REGEX-INTERPOLATION);\#{matches the text#{. Build a pattern from values withRegex.compile.- The body ends at the line end: a missing closing slash is
LEX-UNTERMINATED-REGEX. - After a value,
/is division:a / b / cdivides, andx /= 2is the compound operator. After an operator, a comma, an opening bracket or a keyword it starts a literal:[/a/, /b/],return /a/. A call needs its parentheses:puts(/x/);puts /x/is a division and an error. A line that starts with/ 2is a literal that does not end; put the/at the end of the line before. - A literal is not a
casepattern: test it in anifwithRegex.match?.
Watch out, coming from Ruby: ^ and $ are text anchors, so /^ERROR/ matches only at the start of the text; write /(?m)^ERROR/ for line starts. The m flag means “dot matches newline”, as in Ruby, while (?m) inside the pattern means line anchors. There is no =~ and no $1: use Regex.match and the groups of the match.
Matches #
struct Regex.Match
text: String # the whole match, the same as groups[0].text
start: Int # character index of its first character
stop: Int # character index after its last character
groups: List[Regex.Group] # groups[0] is the whole match
names: Map[String, Int] # group name to its index in groups
end
struct Regex.Group
text: String # "" when the group did not take part
start: Int # -1 when the group did not take part
stop: Int # -1 when the group did not take part
matched: Bool
endGroups are numbered from 1 by their opening parenthesis. Regex.named(m, name) reads a named group, and an unknown name is an error. A Regex.Regex holds the pattern as source; only compile and a regex literal make one. Printing a Regex.Regex shows source first, then its compiled program.
match?says whether the pattern matches anywhere. It keeps no groups, so it is the cheapest search.matchgives the leftmost-first match, orerror("no match"). Among alternatives the first that matches wins:a|abonabgivesa.find_allgives every match from left to right, without overlaps. After an empty match the search moves one character on, and an empty match right where the previous match ended is dropped, as in Go: replacingx*with-inabxdgives-a-b-d-(Python gives-a-b--d-).replacereplaces every match thatfind_allfinds.splitcuts the text at each match that takes at least one character and keeps the empty parts:,a,,b,split at,is["", "a", "", "b", ""]. An empty match separates nothing; to get the characters uses.split("").
Templates #
In the template of replace, $0 is the whole match, $1 to $N a group, ${name} a named group, ${N} a group by number, and $$ a dollar sign. $N takes every digit that follows, so $10 is group 10; write ${1}0 for group 1 and a 0. A group that did not take part gives "". The template is checked before any text is replaced: another $ form or a group the pattern does not have is an error, such as no group 10.
Watch the two forms that look alike: in an Agentica string "#{name}" puts the value of the variable name into the string, while "${name}" is template text that replace reads as the group called name. Write "#{...}" only to build the template from your own values.
Syntax #
- Literals: any character except
\ . + * ? ( ) | [ ] { } ^ $. A backslash before a punctuation character makes it literal. Escapes:\n \r \t \f \v,\x7Fand\x{10FFFF}. .matches any character except a newline; with(?s)it matches a newline too.- Classes:
[abc], ranges[a-z], negation[^a-z], escapes and the classes below inside. A]first in a class and a-first or last are literal. \d[0-9],\w[0-9A-Za-z_],\s[\t\n\f\r ], and their negations\D \W \S. They are ASCII only.- Anchors:
^and$are the start and the end of the text, or of a line with(?m);\Aand\zare always the start and the end of the text;\band\Bare an ASCII word boundary and its negation. - Groups:
(...)captures,(?:...)does not,(?P<name>...)and(?<name>...)capture with a name. - Alternation
|, leftmost-first. - Repetition:
*,+,?,{n},{n,},{n,m}, each lazy with a?after it (*?). A{that starts no repetition is literal:a{,3}matches the texta{,3}. - Flags:
(?i)ignores case (ASCII letters only),(?m)makes^and$work on lines,(?s)lets.match a newline.(?i-s)turns flags on and off, and(?i:...)sets them for a group. A flag set in the middle of a group lasts to the end of that group.
Not supported, each an error from compile: backreferences (\1), lookahead and lookbehind, atomic groups, possessive repetitions, \Q...\E, Unicode classes such as \pL, POSIX classes such as [[:alpha:]], the escapes \a and \0, octal escapes, and \b inside a class.
Where it differs from Ruby: ^ and $ are text anchors, not line anchors (write (?m)^ for a line start), and (?m) means lines, not “dot matches newline” ((?s) here). Where it differs from Python’s re: $ does not match before a final newline, \d \w \s \b are ASCII as with re.ASCII, \B matches in the empty text, as in Go, and the empty-match rule of find_all and split follows Go.
Errors and limits #
A compile error starts with the character where it is, counted from 1: character 4: missing ')' for the group at character 1. A pattern has at most 4096 characters, a repetition count at most 1000, at most 10000 instructions after its repetitions are expanded ((?:a{1000}){11} is too large), groups nested at most 256 deep and at most 256 groups.
Cost #
The matcher runs inside the VM and hands the machine back after each chunk of the text, so a long search shares it with other tasks and --max-steps stops it with RUNTIME-STEP-LIMIT. A search on a text of n characters with a pattern of m instructions and g groups takes O(n·m·g) time, and match? O(n·m). (a+)+$, which takes exponential time in a backtracking matcher, takes linear time here. To stop a search after some time, run it in a task and await it with a timeout (Task.await(task, timeout_ms)).
find_all returns every match at once, so a pattern that matches every character makes one Match per character. Compile a run-time pattern once, outside the loop that uses it; a literal is built once already.