silk.text.regex_shape.

When to use#

Use RegexShape.of in static code that needs to know whether a pattern is valid and which capture groups it has before the program runs, such as a library that types a pattern's captures. Use silk.text.regex to compile and search at run time.

Details#

RegexShape.of reads a pattern the way Regex.compile does: the same ECMAScript Unicode (u) grammar, the same error messages and offsets, and the same Unicode property names. It builds no program. Two resource limits are checked only by Regex.compile, because only the program reveals them: too many class ranges and too many nested quantifiers.

A typed pattern names its groups after fields, so a group name here must be an ASCII identifier written out; a name with a \u escape or a non-ASCII character is reported as an error even though Regex.compile accepts it.

Reading a pattern is static work and counts against the static evaluation budget: a run of plain characters costs a few dozen steps a byte, and a group or quantified term a few hundred, so patterns of several hundred bytes fit comfortably while one with hundreds of groups does not.

Examples#

Read a pattern's groups at compile time#

import silk.core.static_sequence { StaticSequence }
import silk.text.regex_shape { RegexGroup, RegexShape }

static fn secondName() -> string<'static> {
  let shape = RegexShape.of("(?<year>\\d{4})-(?<month>\\d{2})?")
  if !shape.valid {
    compileError(shape.message)
  }
  let month = StaticSequence.at<RegexGroup>(shape.groups, 1)
  if !month.optional {
    compileError("month sits under ?")
  }
  return month.name
}

pub fn main() -> i32 {
  if secondName() != "month" {
    return 1
  }
  return 0
}

Import as RegexShape with import silk.text.regex_shape { RegexShape }.

Public declarations: 2.

RegexGroup#

pub struct RegexGroup

One capture group of a pattern.

Field number#

pub number: usize

The group's number: 1 for the first group that captures, counting each ( in pattern order.

Field name#

pub name: string<'static>

The name in (?<name>...), or empty for an unnamed group.

Field offset#

pub offset: usize

The byte offset of the group's ( in the pattern.

Field optional#

pub optional: bool

Whether a match can leave the group unset: it sits under ?, * or a {0,n} repetition, in one alternative of a |, or inside a negative lookaround.

RegexShape#

pub struct RegexShape

Whether a pattern is valid and, when it is, its capture groups.

Field valid#

pub valid: bool

Whether Regex.compile would accept the pattern.

Field limit#

pub limit: bool

For an invalid pattern, whether it exceeds a resource limit rather than breaking the grammar.

Field message#

pub message: string<'static>

What is wrong, as RegexError.message words it; empty for a valid pattern and a size limit.

Field offset#

pub offset: usize

The byte offset in the pattern where the problem was found, as RegexError.offset gives it.

Field groups#

pub groups: Intrinsic.StaticSequence<RegexGroup>

The capture groups in number order, group 1 first; empty for an invalid pattern.

Implementation RegexShape#

impl RegexShape

Associated function of#

pub static fn of(pattern: string) -> RegexShape

Reads an ECMAScript Unicode (u) pattern as Regex.compile would, without compiling it.

Details#

A valid pattern lists every capture group, named or not, in number order. An invalid one carries the message and offset Regex.compile would report, and limit for a pattern longer than 65,536 bytes, groups nested deeper than 255 levels, or 255 or more captures. Group names must be ASCII identifiers written out, as the module documentation explains.

Category: Text.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.