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').