regexp2

The engine supports Unicode character classes using \p{...} (positive) and \P{...} (negated). It supports Go Unicode categories, aliases, scripts, and properties. It also supports property selection syntax like \p{property=value} (e.g., \p{grapheme_cluster_break=regional_indicator}).

letter := regexp2.MustCompile(`\p{L}+`)
katakana := regexp2.MustCompile(`\p{Katakana}+`)
notEmoji := regexp2.MustCompile(`\P{Emoji}+`)

You can configure regexp2 to match the ECMAScript specification as closely as possible by enabling the ECMAScript flag.

Important Notes:

• This mode prioritizes the ECMAScript specification behavior over matching the C# RegexOptions.ECMAScript interpretation.
• To support the \u{CodePoint} syntax, you must provide both the ECMAScript and Unicode flags.

Install the regexp2 library using the standard Go toolchain. Note that version 2 requires the /v2 suffix in the module path and requires Go 1.25 or later.

go get github.com/dlclark/regexp2/v2@latest

Usage is similar to the standard Go regexp package. Use regexp2.Compile to create a regex state machine, or regexp2.MustCompile if you want the application to panic on an invalid pattern. The resulting *regexp2.Regexp is safe for concurrent use across goroutines.

re := regexp2.MustCompile(`Your pattern`)
if isMatch, _ := re.MatchString(`Something to match`); isMatch {
    //do something
}

By default, regexp2 matches the .NET engine. You can enable RE2 compatibility mode by passing the regexp2.RE2 option to Compile or MustCompile. This changes parsing behavior to support:

• Named ASCII character classes (e.g., [[:foo:]])
• Python-style capture groups (e.g., (?P<name>re))
• Python-style named backreferences (e.g., (?P=name))
• $ matching only the end of the string
• \d, \s, and \w matching RE2-specific character sets
• Relaxed character escape sequences (e.g., \_ matches literal _)

re := regexp2.MustCompile(`Your RE2-compatible pattern`, regexp2.RE2)
if isMatch, _ := re.MatchString(`Something to match`); isMatch {
    // do something
}

The OptimizationOptions struct controls runtime limits and caching behavior. By default, regexp2 uses DefaultOptimizationOptions to ensure that Compile is safe for mixed-cardinality inputs by providing sensible bounds on memory and stack usage.

Key behaviors for tuning:

• Stack Size: MaxBacktrackingStackSize prevents stack overflow. Use a negative value to allow unbounded growth.
• Caching: For replacement data, setting a value of 0 disables persistent retention, while -1 allows unbounded growth. For pooled buffers, 0 disables pooling and -1 allows all built-in size classes.

// Default values used if no options are provided:
// MaxBacktrackingStackSize: 100000
// MaxCachedRuneBufferLength: 256 KB
// MaxCachedReplaceBufferLength: 256 KB
// MaxCachedReplacerDataEntries: 16
// MaxCachedReplacerDataBytes: 4 KB
// DisableCharClassASCIIBitmap: false

The regexp2 matching results follow a hierarchical structure:

1. Match: The top-level result. It contains the entire match and a collection of Group objects.
2. Group: A named or numbered collection of captures.
   • A Group embeds a Capture representing its last capture for easy access.
   • A Group contains a slice of Captures ([]Capture), which is useful for patterns that allow repeated captures in a single group.
3. Capture: The most granular level, representing the specific start and end positions (in runes) of a matched substring.

When performing replacements using standard pattern strings (rather than a MatchEvaluator), regexp2 supports several special tokens to reference parts of the match or the surrounding text. These are represented by negative integer constants in the engine:

Note: These constants are used internally by the syntax.ReplacerData rules. When using standard replacement strings, you typically use group references (like $1, $2) which the engine maps to these logic paths.

The Regexp struct includes a MatchTimeout field of type time.Duration. A match will time out if it takes approximately more than this duration. This is a safety mechanism against catastrophic backtracking.

By default, MatchTimeout is set to DefaultMatchTimeout (the maximum possible duration), which effectively suppresses timeout checking. You can set a specific duration on your Regexp instance to enforce limits.

re, _ := regexp2.Compile("complex-pattern")
re.MatchTimeout = 100 * time.Millisecond

If you use MatchTimeout, regexp2 starts a background goroutine for the timeout clock. This can cause failures in testing tools like uber-go/goleak. To fix this, you must call regexp2.StopTimeoutClock() during test teardown.

You can also speed up tests by reducing the clock cycle rate using regexp2.SetTimeoutCheckPeriod. This must be called in an init() function because it is not thread-safe.

func TestSomething(t *testing.T) {
    defer goleak.VerifyNone(t)
    defer regexp2.StopTimeoutClock()

    // ... test
}

// Or in TestMain
func TestMain(m *testing.M) {
    // ... setup
    m.Run()
    regexp2.StopTimeoutClock()
    goleak.VerifyNone(t)
}

// Speed up testing in an init function
func init() {
    regexp2.SetTimeoutCheckPeriod(time.Millisecond)
}