feat: named capture groups and reference

[mdjastrzebski]

Summary

1. capture(...) generates a Capturing Group ((...) in regex syntax). When calling String.match() or Regex.exec(), the result will be Array-like object. At index 0 it will hold whole matched regex, at indexes 1 and later it will hold values captured by consecutive capturing groups in the regex.

2. capture(..., { name: 'aaa' }) generates a Named Capturing Group ((?<aaa>...) in regex). It results are also available on the match() result at specified indexes like regular Capturing Group. In addition to that, match result will also expose matched results by name, under result.group.aaa, etc. for each Named Capturing Group in the regex.

3. Captured value can also be used during matching using Backreferences. Backreference can either refer to Capuring Group order (\1, \2, etc) or name (\k<aaa>, etc). In TS Regex Builder to use backreference we need to do following:

// Define reference named "quote" const quote = reference('quote'); const regex = buildRegExp([ // make capture use name "quote" by giving it a reference ( capture(anyOf(`'"`), { name: quoteRef }), // => (?<quote>['"]) // some other patterns (not important) zeroOrMore(word), // reference back the value captured in the "quote" reference by putting reference here quoteRef, // => \k<quote> ]);

Alternatives

Base idea:

// Named capture => (?<aaa>...) capture(..., { name: 'aaa' }); // Named capture + backreference => (?<aaa>...) + \k<aaa> const someRef = reference('some'); capture(..., { name: someRef });

Alternative 1: separete name and ref options:

// Named capture capture(..., { name: 'aaa' }) // Named capture + backreference const someRef = reference('some'); capture(..., { ref: someRef })

Alternative 2: explicitly define namedCapture:

// Named capture namedCapture("aaa", [...]); // Named capture + backreference const someRef = namedReference("aaa"); namedCapture(someRef, [...]);

Test plan

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (65022ee) to head (6525391).

Additional details and impacted files

@@ Coverage Diff @@ ## main #66 +/- ## ========================================= Coverage 100.00% 100.00% ========================================= Files 16 16 Lines 183 190 +7 Branches 41 42 +1 ========================================= + Hits 183 190 +7 

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mdjastrzebski]

CC: @PaulPhilp

[mdjastrzebski]

Merging this PR in a more restrictive syntax, capture(..., { name: 'groupName' }) and ref('groupName').