Skip to content

About

ECMA-262 (JavaScript) regular expressions for Java: the grammar and the answers of RegExp, every flag, over UTF-8 and UTF-16.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

96 Commits

Folders and files

Repository files navigation

corvus-regex-ecma262 for Java

Regular expressions with the grammar and the answers of ECMA-262, the RegExp of JavaScript, for Java 17 and later.

  • Every flag: d, g, i, m, s, u, v and y, with the grammar of each. Without u or v a pattern is read by the Annex B grammar and matched by UTF-16 code unit, as ECMA-262 matches it; with them, by code point. The v flag has nested classes, the difference and the intersection of classes, strings in a class and the seven properties of strings.

  • ECMAScript 2025: lookbehind, named groups (and a name shared between alternatives), modifier groups such as (?i:...), and every Unicode property ECMA-262 lists, from tables of Unicode the library carries, so a pattern answers the same whatever JDK runs it.

  • The grammar of ECMAScript 2020, which JSON Schema 2020-12 names, and a choice of Unicode version, each independent of the other: Regex.builder(pattern) takes an Edition (CURRENT, the default, or ES2020) and a UnicodeVersion (DEFAULT for V8's version, which is 17 today, or V13, V17, V18 or LATEST, which is 18 today). Both are settled when a pattern is compiled and cost a match nothing. The 2020 grammar refuses what later editions added: the d and v flags, modifier groups, a group name used twice, and property names outside its tables. A version's tables load when a pattern first asks for it.

  • Text as a String (UTF-16, lone surrogates and all) or as UTF-8 bytes (Utf8Text, checked once, or a byte[], checked on each call). Nothing is transcoded, and a match allocates nothing once the thread's working memory has grown.

  • isMatch, find, findAll, captures, capturesAll, replace and replaceAll (with every $ form of GetSubstitution) and split, each as RegExp and String.prototype define it.

  • A pattern without a backreference is matched in time proportional to its size times the text. A pattern can be given a match timeout, as a Regex of .NET can, which bounds the time and the backtracking memory of every match, and a pattern has limits of size, so with a timeout neither a pattern nor a text from outside can make a program hang. Regex.setDefaultMatchTimeout, or the system property corvus.regex.defaultMatchTimeout, gives every pattern one. Regex.tryCompile(pattern, flags, timeout) and the builder's tryBuild() give a pattern its own and return a CompileResult (the Regex, or the RegexException of why not) in place of throwing, so a validator needs neither the default nor a catch.

  • Two modes of searching for where a match can start. By default the library's own searches, which read a text eight bytes at a time and need nothing of the JVM. Started with --add-modules jdk.incubator.vector, the JVM gives the library the Vector API, and from JDK 21 on it searches a vector at a time (32 bytes with AVX2); on JDK 17, whose JIT allocated for the Vector API's masks, it stays with its own. The module is incubating in every JDK so far, so adding it is how a program opts in; without it, nothing of the Vector API is loaded. Both modes give the same answers, and CI runs everything in each.

Compliance. Over the ECMA-262 test data (what V8 says about its patterns and texts, test262's patterns and exec calls, the global search, replace and split among them, and texts of bytes that are not UTF-8, which it refuses), the library gives every answer right and none wrong, refuses no valid pattern, accepts no invalid one and reaches no limit, over UTF-8 and over UTF-16. It does the same on the data as the data's own scripts write it for Unicode 13 and 18 and for the grammar of ECMAScript 2020. CI runs all of it on every change.

It is a port of the Rust crate corvus-regex-ecma262 at v0.1.3, with the crate's search layer (docs/port-checklist.md), and it follows the design of the .NET engine Corvus.Regex.Ecma262.

import io.github.corvusdotnet.regex.ecma262.CompileResult;
import io.github.corvusdotnet.regex.ecma262.Edition;
import io.github.corvusdotnet.regex.ecma262.Regex;
import io.github.corvusdotnet.regex.ecma262.UnicodeVersion;
import java.time.Duration;

Regex re = Regex.compile("(?<year>\\d{4})-(?<month>\\d{2})", "u", Duration.ofMillis(100));
re.isMatch("on 2026-10-22");                              // true
re.captures("on 2026-10-22").group("month");             // "10"
re.replaceAll("2026-10-22", "$<month>/$<year>");          // "10/2026-22"

// ECMAScript 2020 as its edition was published, with the Unicode of its year, and a match timeout of its own.
CompileResult greek = Regex.builder("^\\p{Script=Greek}+$")
        .flags("u")
        .matchTimeout(Duration.ofSeconds(1))
        .edition(Edition.ES2020)
        .unicodeVersion(UnicodeVersion.V13)
        .tryBuild();
greek.isOk();                                             // true

Installing

From Maven Central, for Java 17 and later, at the latest version there:

<dependency>
  <groupId>io.github.corvus-dotnet</groupId>
  <artifactId>corvus-regex-ecma262</artifactId>
  <version><!-- the latest version --></version>
</dependency>

or with Gradle, implementation("io.github.corvus-dotnet:corvus-regex-ecma262:<version>"). The library has no dependency. For the Vector API's searches, start the JVM with --add-modules jdk.incubator.vector (JDK 21 or later).

Benchmarks

The central benchmark site runs this repository's harness image, ghcr.io/corvus-dotnet/corvus-regex-ecma262-java, each night beside the engines of every other source: this library over UTF-8 and UTF-16 in both modes, java.util.regex, TRegex (the regex engine of GraalJS, run by GraalVM's Node) and V8, over the Industry workloads of dotnet/performance, with each ECMA-262 engine's compliance over the test data. This repository publishes no figures of its own. tools/benchmarks/run.sh <workloads.json> <texts> <out.json> runs the same harness anywhere (see the script for what it needs).

TRegex's compliance takes too long to work out every night, so it is worked out once (TREGEX_COMPLIANCE=1, which runs tools/benchmarks/tregex-compliance.py) and checked in as tools/benchmarks/compliance-tregex.json, its compliance file: the counts, the script and the calls it makes, and what it leaves out (UTF-8). A JavaScript engine cannot be stopped in a match, so a watchdog thread in GraalVM's Node ends the process at an answer that passes 2 seconds; that answer is unanswered, and a new process goes on from the next. Once three answers of a record have reached the limit, its other answers are unanswered without being asked. The limit is the wall clock's, so the run is made with nothing else running on the machine. The file gives the commit of the test data it was made at (dataCommit): the page judges the counts against what that commit asks, and CI fails when it is not the commit CI checks the data out at, so moving CI's pin means working it out again. A change to the harness alone, such as new counts, is released as a harness release (gh release create harness-<version>.<n> --latest=false), which publishes the harness image and no package.

Releasing

Every merged pull request releases what it changed, unless it is labelled no_release. auto-release.yml gives the library the next patch version when pom.xml or src/main/ changed since its last tag, and makes a GitHub release tagged v<version> on the merge commit: maven-publish.yml writes the version into pom.xml (which holds 0.0.0-SNAPSHOT), runs the tests and the test data in both modes, then signs and publishes it to Maven Central, and harness-image.yml publishes the harness image under the same tag. When only the harness changed (Dockerfile, tools/benchmarks/), the release is harness-<version>.<n>, which publishes the image alone. A pull request that needs a minor or major version sets nextVersion for the package in .github/release.json; a minor version is a breaking change. A pull request labelled no_release releases nothing, and its changes ship with the next release.

Building

JDK 25 and Maven 3.9: mvn verify builds the library for Java 17 with warnings denied (the Vector API's searches compile against the incubating module, whose warning only JDK 25's javac can leave out) and runs the tests in both modes. The templates of src/template are expanded into one class per encoding by python3 tools/expand.py (the expanded files are checked in, and CI runs it with --check). The Unicode tables of each version (Tables<major>.java, Strings<major>.java) and the property names of ECMAScript 2020 (Es2020.java) are written from the Rust crate's by tools/unicode, and CI checks them against the crate. The test data runs with

javac -encoding UTF-8 -d tools/dataset/out -cp target/classes tools/dataset/Dataset.java
java -Xss4m -cp target/classes:tools/dataset/out Dataset <ecma262-regex-test-data>/data wrong-cases.tsv

Licence

Apache 2.0.

About

ECMA-262 (JavaScript) regular expressions for Java: the grammar and the answers of RegExp, every flag, over UTF-8 and UTF-16.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages