[feature] Stateful streaming replacement: appendReplacement / appendTail equivalent by jbachorik · Pull Request #54 · DataDog/java-reggie

jbachorik · 2026-05-08T13:06:34Z

What does this PR do?

Adds MatchCursor — a stateful streaming cursor for incremental match-and-replace, analogous to JDK Matcher.appendReplacement / appendTail. Also introduces the NamedGroupResult sub-interface and extends MatchResultImpl with optional named-group support.

Motivation

Implements #46. ReggieMatcher.replaceAll(Function) covers the common case, but callers that need to accumulate a StringBuilder incrementally across matches (e.g. interleaving non-match content with per-match computed replacements) have no equivalent API today.

Related Issue(s)

Closes #46

Change Type

Checklist

I have read the CONTRIBUTING.md guidelines
All existing tests pass (./gradlew build)
I have added tests for my changes
I have updated documentation (if applicable)
My commits are signed

Performance Impact

MatchCursor.findNext() returns MatchResult directly (not Optional) to stay allocation-free on the hot path. Named-group index is parsed once at cursor construction from the pattern string.

Additional Notes

New public API:

ReggieMatcher.cursor(String) — factory method
MatchCursor — implements Iterator<MatchResult> and AutoCloseable
- findNext() → MatchResult or null (exhausted / closed)
- appendReplacement(StringBuilder, String) → MatchCursor (fluent)
- appendTail(StringBuilder) → StringBuilder
- reset(String) — restarts cursor on new input, safe to call at any point
- close() — resets all state
NamedGroupResult — extends MatchResult with group(String name)
MatchResult.hasNamedGroups() — default false; MatchResultImpl overrides to true when named groups are present

Acceptance criteria satisfied:

MatchCursor implements Iterator<MatchResult> and AutoCloseable ✓
findNext() advances cursor; null signals exhaustion ✓
reset(String) may be called at any point, including mid-iteration ✓
Only non-overlapping sequential matches ✓
Numeric ($1, $2) and named (${name}) backreferences ✓
Non-participating groups follow JDK Matcher.appendReplacement behavior ✓
appendReplacement returns MatchCursor (fluent) ✓
appendTail returns StringBuilder ✓
Thread-safety: not shared; each thread must use its own ReggieMatcher and cursor (documented) ✓
Invalid-state throws IllegalStateException / NullPointerException as appropriate ✓
findNext() may be called without appendReplacement() to skip a match ✓
findNext() after appendTail() returns null (not an error) ✓
close() resets all fields ✓
Coexists with replaceAll(Function) ✓

20 tests covering all behaviours added in MatchCursorTest.

🤖 Generated with Claude Code via muse implement

Implements #46 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jbachorik · 2026-05-08T13:09:38Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 85c141e565

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Adds a new stateful, streaming match-and-replace API to reggie-runtime via MatchCursor, analogous to java.util.regex.Matcher.appendReplacement/appendTail, and introduces named-group support hooks (NamedGroupResult, MatchResult.hasNamedGroups()).

Changes:

Introduces MatchCursor (iterator-style cursor with findNext(), appendReplacement(), appendTail(), reset(), close()).
Adds named-group result support via NamedGroupResult and extends MatchResult/MatchResultImpl accordingly.
Adds MatchCursorTest covering streaming replacement behaviors.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchCursor.java	New streaming cursor implementation (iteration, replacement expansion, named-group parsing).
reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/ReggieMatcher.java	Adds `cursor(String)` factory method to create a `MatchCursor`.
reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/NamedGroupResult.java	New sub-interface for named-group lookup (`group(String)`).
reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchResultImpl.java	Extends result implementation with optional named-group index support.
reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchResult.java	Adds `hasNamedGroups()` default method for capability checks.
reggie-runtime/src/test/java/com/datadoghq/reggie/runtime/MatchCursorTest.java	New test suite validating cursor iteration/replacement semantics and state transitions.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- MatchCursor.java:211 — fix digit-greedy loop in expandReplacement to stop before a digit that would push group number past groupCount (JDK appendReplacement semantics), so $12 with 1 group emits group(1) + literal '2' - MatchCursor.java:88 — findNext() now consumes the peeked buffer from hasNext() to avoid skipping matches when caller mixes hasNext() with findNext() - MatchResultImpl.java — revert to implements MatchResult only; remove nameIndex field - NamedMatchResultImpl.java — new package-private class extends MatchResultImpl implements NamedGroupResult; only instantiated when pattern has named groups; requireNonNull guard on nameIndex - MatchCursor.java:125 — appendTail() clears lastMatch/peeked references after tail is appended - MatchCursorTest.java:191 — add ready.await() before start.countDown() so all threads reach barrier before race starts Co-Authored-By: muse <muse@noreply>

jbachorik · 2026-05-08T13:44:01Z

@copilot review

jbachorik · 2026-05-08T13:44:05Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cb5297eebf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Google Java Format requires the parameters to fit on one line when within the 100-char limit; put all 5 params on the same continuation line to satisfy the spotlessJavaCheck CI task. Agent-Logs-Url: https://github.com/DataDog/java-reggie/sessions/f4a2f7a8-d99e-4c39-9666-25404e355f5d Co-authored-by: jbachorik <738413+jbachorik@users.noreply.github.com>

Copilot · 2026-05-08T13:48:05Z

Fixed the CI failure (commit e844992): the NamedMatchResultImpl constructor parameters were split across multiple lines, but Google Java Format requires them on a single continuation line when they fit within the 100-char limit. Running spotlessApply logic manually fixed the spotlessJavaCheck violation that was breaking the build.

jbachorik · 2026-05-08T14:35:15Z

@copilot resolve the merge conflicts in this pull request

…h-limit, self-ref backrefs) Main added: - Named group extraction directly into MatchResult/MatchResultImpl (group/start/end by name) - split(String, int) with JDK semantics - Self-referencing backreference support in RECURSIVE_DESCENT - NameEnrichingMatcher for enriching results with named groups Conflict resolution in MatchResult.java: - Dropped hasNamedGroups() (our addition) in favour of main's group/start/end(String) defaults - NamedGroupResult simplified to a marker interface (named group methods now in MatchResult) - NamedMatchResultImpl delegates named-group storage to MatchResultImpl's 5-arg constructor Co-authored-by: jbachorik <738413+jbachorik@users.noreply.github.com>

Copilot · 2026-05-08T14:45:14Z

Resolved in commit 7fc4118. The only true conflict was in MatchResult.java — our hasNamedGroups() default vs. main's group/start/end(String name) defaults. Resolution: took main's approach (named-group methods directly in the interface) and updated our additions accordingly:

NamedGroupResult simplified to a marker interface (the methods it declared are now in MatchResult)
NamedMatchResultImpl simplified to delegate named-group storage to MatchResultImpl's 5-arg constructor (no redundant field/overrides)
MatchResultImpl Javadoc cleaned up

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

(?|...) resets group numbering per-alternative; the previous monotonic scan mapped named groups in later alternatives to wrong indices. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jbachorik · 2026-05-08T15:04:20Z

@copilot review

jbachorik · 2026-05-08T15:04:25Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b52f400a06

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

- MatchCursor uses matcher.nameToIndex (authoritative, handles branch-reset) instead of re-parsing the pattern — removes parseNamedGroups() entirely - expandReplacement throws IllegalArgumentException for $<non-digit> per JDK - reset()/cursor() validate input is non-null via Objects.requireNonNull - MatchResult.hasNamedGroups() default false; NamedGroupResult overrides true - Add hasNext()/next() and mixed-iteration tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jbachorik · 2026-05-08T15:14:04Z

@copilot review

Copilot · 2026-05-08T16:05:22Z

CI is green on the latest commit (646b615). All tests pass. The code review tooling found no new issues — the PR is clean and ready for merge.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 646b615304

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…onstruction paths Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jbachorik · 2026-05-08T16:23:06Z

@copilot please review

jbachorik · 2026-05-08T16:23:08Z

@codex please review

Copilot · 2026-05-08T16:26:25Z

The PR is in good shape. Here's what I found after reviewing the full diff, including the two newest commits (9c334da, c64ee8f):

MatchCursor — no issues:

findNext() correctly drains peeked before advancing searchPos
hasNext() saves/restores lastMatch so appendReplacement() still sees the active match after a lookahead
appendTail() clears lastMatch, peeked, peekedValid to release references immediately
reset() and constructor both call requireNonNull on input
expandReplacement() follows JDK semantics: \\ → literal, \$ → literal, $N/${name} → group, anything else → IllegalArgumentException

MatchResultImpl.hasNamedGroups() — correct:
The new @Override delegates to !nameToIndex.isEmpty(), which covers all three construction paths:

4-arg constructor (no names) → emptyMap → false ✓
5-arg constructor (with names) → non-empty map → true ✓
JavaRegexFallbackMatcher.toMatchResult() (passes javaPattern.namedGroups()) → true when named groups are present ✓

NamedMatchResultImpl — harmless redundancy:
NamedGroupResult.hasNamedGroups() returns true as a default, but since MatchResultImpl.hasNamedGroups() is a concrete @Override, it takes priority for NamedMatchResultImpl instances. The interface default is effectively dead code here, but it doesn't cause bugs.

Tests — good coverage: the new namedGroupFallbackHasNamedGroupsTrue (fallback path), testHasNamedGroups_directMatchResultImplConstruction (direct 5-arg ctor path), and all three iterator-mixing tests cover the non-trivial interaction points.

CI is in progress on c64ee8f; the previous four runs were all green. No blocking issues found — ready to merge once CI completes.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c64ee8f08d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jbachorik · 2026-05-08T16:38:55Z

@copilot please review

jbachorik · 2026-05-08T16:38:58Z

@codex please review

Copilot · 2026-05-08T16:41:40Z

CI is green on the latest commit (625918c). All 35 tests pass. Here's a quick summary of the current state:

MatchCursor — no issues:

findNext() correctly drains peeked before advancing searchPos
hasNext() saves/restores lastMatch so appendReplacement() still sees the active match after a lookahead
appendTail() clears lastMatch, peeked, peekedValid immediately
reset() and constructor both call requireNonNull on input
expandReplacement() follows JDK semantics: \\ → literal, \$ → literal, $N/${name} → group, anything else → IllegalArgumentException

MatchResultImpl.hasNamedGroups() — correct:

Delegates to !nameToIndex.isEmpty() covering all construction paths (4-arg with empty map → false, 5-arg with names → true)

NamedGroupResult — clean marker interface with hasNamedGroups() default true

Tests — 35 tests covering all acceptance criteria including iterator mixing, peeked buffer semantics, and edge cases.

The PR is clean and ready for merge.

CI is green on the latest commit (625918c). All 35 tests pass. No outstanding issues — the PR is clean and ready for merge.

CI is green on the latest commit (625918c). No issues found in the review:

MatchCursor: state machine is correct — peeked/lastMatch interaction handles all mixing patterns (hasNext→findNext, hasNext→appendReplacement, next→appendReplacement), appendTail() and close() clear all refs
expandReplacement: JDK-aligned — \\x → literal x, \$ → literal $, $N/${name} → group value, anything else → IllegalArgumentException; trailing $ and $$ throw; out-of-range group throws IndexOutOfBoundsException
MatchResultImpl.hasNamedGroups(): covers all three construction paths (4-arg → emptyMap → false, 5-arg with names → true, fallback via JavaRegexFallbackMatcher → true when names present)
NamedMatchResultImpl: correctly takes priority over the NamedGroupResult interface default since MatchResultImpl.hasNamedGroups() is a concrete @Override
35 tests — comprehensive coverage including edge cases, thread-safety, Iterator mixing, and replacement semantics

CI is green on the latest commit (625918c). No new issues found. The PR is clean and ready for merge.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 625918ce8f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jbachorik · 2026-05-08T16:57:03Z

@copilot please review

jbachorik · 2026-05-08T16:57:04Z

@codex please review

Copilot · 2026-05-08T16:58:40Z

CI is green on the latest commit (8241d39). No new issues found:

MatchCursor: all state-machine invariants are correct — findNext() clears lastMatch on exhaustion (so appendReplacement() correctly throws after a null return), peeked buffer is drained before advancing, hasNext() saves/restores lastMatch, appendTail()/close() clear all refs
expandReplacement(): JDK-aligned — \\x → literal, \$ → literal $, $N/${name} → group value, trailing $/$$/$x → IllegalArgumentException, out-of-range $N → IndexOutOfBoundsException
MatchResultImpl.hasNamedGroups(): delegates to !nameToIndex.isEmpty() covering all construction paths
NamedMatchResultImpl: correctly inherits the concrete hasNamedGroups() override from MatchResultImpl
35 tests — comprehensive coverage including all edge cases

The PR is clean and ready for merge.

CI is green on the latest commit (8241d39). No new issues found — the PR is clean and ready for merge. (See the detailed review above.)

chatgpt-codex-connector · 2026-05-08T17:01:03Z

Codex Review: Didn't find any major issues. More of your lovely PRs please.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

feat: add MatchCursor stateful streaming replacement API

85c141e

Implements #46 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jbachorik added the AI Generated or assisted by AI label May 8, 2026

jbachorik requested a review from Copilot May 8, 2026 13:09

Copilot started reviewing on behalf of jbachorik May 8, 2026 13:09 View session

chatgpt-codex-connector Bot reviewed May 8, 2026

View reviewed changes

Comment thread reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchCursor.java

Copilot AI reviewed May 8, 2026

View reviewed changes

Copilot started work on behalf of jbachorik May 8, 2026 13:44 View session

chatgpt-codex-connector Bot reviewed May 8, 2026

View reviewed changes

Comment thread reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchCursor.java Outdated

Copilot finished work on behalf of jbachorik May 8, 2026 13:49

Copilot started work on behalf of jbachorik May 8, 2026 14:35 View session

Copilot finished work on behalf of jbachorik May 8, 2026 14:46

jbachorik requested a review from Copilot May 8, 2026 14:46

Copilot started reviewing on behalf of jbachorik May 8, 2026 14:47 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

fix: handle branch-reset groups in parseNamedGroups

b52f400

(?|...) resets group numbering per-alternative; the previous monotonic scan mapped named groups in later alternatives to wrong indices. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot started work on behalf of jbachorik May 8, 2026 15:04 View session

chatgpt-codex-connector Bot reviewed May 8, 2026

View reviewed changes

Comment thread reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchCursor.java Outdated

Comment thread reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchCursor.java Outdated

Copilot started work on behalf of jbachorik May 8, 2026 16:04 View session

Copilot finished work on behalf of jbachorik May 8, 2026 16:06

chatgpt-codex-connector Bot reviewed May 8, 2026

View reviewed changes

Comment thread reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchResult.java

jbachorik and others added 2 commits May 8, 2026 18:21

fix: hasNamedGroups() via MatchResultImpl.nameToIndex, covering all c…

9c334da

…onstruction paths Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: import Map instead of using FQN in NamedGroupCorrectnessTest

c64ee8f

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot started work on behalf of jbachorik May 8, 2026 16:23 View session

Copilot finished work on behalf of jbachorik May 8, 2026 16:27

chatgpt-codex-connector Bot reviewed May 8, 2026

View reviewed changes

Comment thread reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchCursor.java

fix: clear lastMatch in findNext() on exhaustion/no-match

625918c

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot started work on behalf of jbachorik May 8, 2026 16:39 View session

chatgpt-codex-connector Bot reviewed May 8, 2026

View reviewed changes

Comment thread reggie-runtime/src/main/java/com/datadoghq/reggie/runtime/MatchResult.java

Copilot finished work on behalf of jbachorik May 8, 2026 16:43

fix: delegate hasNamedGroups() through HybridMatcher.OffsetMatchResult

8241d39

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot started work on behalf of jbachorik May 8, 2026 16:57 View session

jbachorik marked this pull request as ready for review May 8, 2026 17:16

jbachorik merged commit 5cf7fcb into main May 8, 2026
8 of 9 checks passed

jbachorik deleted the muse/feature-stateful-streaming-replacement branch May 8, 2026 17:18

jbachorik added this to the 0.2.0 milestone May 8, 2026

Conversation

jbachorik commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Motivation

Related Issue(s)

Change Type

Checklist

Performance Impact

Additional Notes

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI commented May 8, 2026

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

Copilot AI commented May 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

Copilot AI commented May 8, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

jbachorik commented May 8, 2026

Uh oh!

Copilot AI commented May 8, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

jbachorik commented May 8, 2026 •

edited

Loading

Copilot AI commented May 8, 2026 •

edited

Loading

Copilot AI commented May 8, 2026 •

edited

Loading