feat: named capture groups & backreferences

wip

chore: more tests

feat: improved refs

refactor: merge name and ref

refactor: self code review

refactor: tweaks

refactor: rename reference to ref

feat: example with html tags

chore: self code review

Author: mdjastrzebski

Diff for: jest-setup.ts

@@ -1,4 +1,6 @@
 import './test-utils/to-equal-regex';
 import './test-utils/to-match-groups';
 import './test-utils/to-match-all-groups';
+import './test-utils/to-match-named-groups';
+import './test-utils/to-match-all-named-groups';
 import './test-utils/to-match-string';

Diff for: src/__tests__/example-html-tags.ts

@@ -0,0 +1,42 @@
+import {
+  any,
+  buildRegExp,
+  capture,
+  charClass,
+  charRange,
+  digit,
+  oneOrMore,
+  ref,
+  zeroOrMore,
+} from '..';
+
+test('example: html tag matching', () => {
+  const tagName = oneOrMore(charClass(charRange('a', 'z'), digit));
+
+  const tagRef = ref('tag');
+  const tagMatcher = buildRegExp(
+    [
+      '<',
+      capture(tagName, { as: tagRef }),
+      '>',
+      capture(zeroOrMore(any, { greedy: false }), { as: 'content' }),
+      '</',
+      tagRef,
+      '>',
+    ],
+    { ignoreCase: true, global: true },
+  );
+
+  expect(tagMatcher).toMatchAllNamedGroups('<a>abc</a>', [{ tag: 'a', content: 'abc' }]);
+  expect(tagMatcher).toMatchAllNamedGroups('<a><b>abc</b></a>', [
+    { tag: 'a', content: '<b>abc</b>' },
+  ]);
+  expect(tagMatcher).toMatchAllNamedGroups('<a>abc1</a><b>abc2</b>', [
+    { tag: 'a', content: 'abc1' },
+    { tag: 'b', content: 'abc2' },
+  ]);
+
+  expect(tagMatcher).not.toMatchString('<a>abc</b>');
+
+  expect(tagMatcher).toEqualRegex('<(?<tag>[a-z\\d]+)>(?<content>.*?)<\\/\\k<tag>>');
+});

Diff for: src/constructs/__tests__/capture.test.tsx

@@ -1,4 +1,15 @@
-import { capture, oneOrMore } from '../..';
+import {
+  any,
+  anyOf,
+  buildRegExp,
+  capture,
+  digit,
+  inverted,
+  oneOrMore,
+  ref,
+  word,
+  wordBoundary,
+} from '../..';
 
 test('`capture` pattern', () => {
   expect(capture('a')).toEqualRegex(/(a)/);
@@ -12,3 +23,96 @@ test('`capture` matching', () => {
   expect(['a', capture('b')]).toMatchGroups('ab', ['ab', 'b']);
   expect(['a', capture('b'), capture('c')]).toMatchGroups('abc', ['abc', 'b', 'c']);
 });
+
+test('named `capture` pattern', () => {
+  expect(capture('a', { as: 'xyz' })).toEqualRegex('(?<xyz>a)');
+  expect(capture('abc', { as: 'xyz' })).toEqualRegex('(?<xyz>abc)');
+  expect(capture(oneOrMore('abc'), { as: 'xyz' })).toEqualRegex('(?<xyz>(?:abc)+)');
+  expect(oneOrMore(capture('abc', { as: 'xyz' }))).toEqualRegex('(?<xyz>abc)+');
+});
+
+test('named `capture` matching', () => {
+  expect(capture('b', { as: 'x1' })).toMatchGroups('ab', ['b', 'b']);
+  expect(capture('b', { as: 'x1' })).toMatchNamedGroups('ab', { x1: 'b' });
+
+  expect(['a', capture('b', { as: 'x1' })]).toMatchGroups('ab', ['ab', 'b']);
+  expect(['a', capture('b', { as: 'x1' })]).toMatchNamedGroups('ab', { x1: 'b' });
+
+  expect([capture('a'), capture('b', { as: 'x1' }), capture('c', { as: 'x2' })]).toMatchGroups(
+    'abc',
+    ['abc', 'a', 'b', 'c'],
+  );
+  expect([capture('a'), capture('b', { as: 'x1' }), capture('c', { as: 'x2' })]).toMatchNamedGroups(
+    'abc',
+    { x1: 'b', x2: 'c' },
+  );
+});
+
+// Should have `ref0` as name.
+const firstRef = ref();
+
+test('`reference` pattern', () => {
+  expect([firstRef]).toEqualRegex(/\k<ref0>/);
+  expect([ref('xyz')]).toEqualRegex(/\k<xyz>/);
+  expect([capture(any, { as: firstRef }), ' ', firstRef]).toEqualRegex('(?<ref0>.) \\k<ref0>');
+
+  const otherRef = ref('r123');
+  expect(['xx', capture(any, { as: otherRef }), ' ', otherRef, 'xx']).toEqualRegex(
+    'xx(?<r123>.) \\k<r123>xx',
+  );
+});
+
+test('`reference` matching basic case', () => {
+  const someRef = ref();
+  expect([capture(word, { as: someRef }), someRef]).toMatchString('aa');
+  expect([capture(digit, { as: someRef }), someRef]).toMatchString('11');
+
+  expect([capture(any, { as: someRef }), someRef]).not.toMatchString('ab');
+
+  expect([capture(digit, { as: someRef }), someRef]).not.toMatchString('1a');
+  expect([capture(digit, { as: someRef }), someRef]).not.toMatchString('a1');
+});
+
+test('`reference` matching HTML attributes', () => {
+  const quoteRef = ref('quote');
+  const quote = anyOf('"\'');
+  const htmlAttributeRegex = buildRegExp([
+    wordBoundary,
+    capture(oneOrMore(word), { as: 'name' }),
+    '=',
+    capture(quote, { as: quoteRef }),
+    capture(oneOrMore(inverted(quote)), { as: 'value' }),
+    quoteRef,
+  ]);
+
+  expect(htmlAttributeRegex).toMatchNamedGroups('a="b"', {
+    name: 'a',
+    quote: '"',
+    value: 'b',
+  });
+  expect(htmlAttributeRegex).toMatchNamedGroups('aa="bbb"', {
+    name: 'aa',
+    quote: '"',
+    value: 'bbb',
+  });
+  expect(htmlAttributeRegex).toMatchNamedGroups(`aa='bbb'`, {
+    name: 'aa',
+    quote: `'`,
+    value: 'bbb',
+  });
+  expect(htmlAttributeRegex).toMatchNamedGroups('<input type="number" />', {
+    quote: '"',
+    name: 'type',
+    value: 'number',
+  });
+  expect(htmlAttributeRegex).toMatchNamedGroups(`<input type='number' />`, {
+    quote: "'",
+    name: 'type',
+    value: 'number',
+  });
+
+  expect(htmlAttributeRegex).not.toMatchString(`aa="bbb'`);
+  expect(htmlAttributeRegex).not.toMatchString(`aa='bbb"`);
+  expect(htmlAttributeRegex).not.toMatchString(`<input type='number" />`);
+  expect(htmlAttributeRegex).not.toMatchString(`<input type="number' />`);
+});

Diff for: src/constructs/capture.ts

@@ -6,19 +6,71 @@ import type { RegexConstruct, RegexElement, RegexSequence } from '../types';
 export interface Capture extends RegexConstruct {
   type: 'capture';
   children: RegexElement[];
+  options?: CaptureOptions;
 }
 
-export function capture(sequence: RegexSequence): Capture {
+export interface CaptureOptions {
+  /**
+   * Either a name to be given to the capturing group or a `Reference` object ({@link ref})
+   * that will allow to match the captured text again later. */
+  as?: Backreference | string;
+}
+
+export interface Backreference extends RegexConstruct {
+  type: 'reference';
+  name: string;
+}
+
+/**
+ * Creates a capturing group which allows the matched pattern to be available:
+ * - in the match results (`String.match`, `String.matchAll`, or `RegExp.exec`)
+ * - in the regex itself, through backreferences (@see ref)
+ */
+export function capture(sequence: RegexSequence, options?: CaptureOptions): Capture {
   return {
     type: 'capture',
     children: ensureArray(sequence),
+    options,
     encode: encodeCapture,
   };
 }
 
+let counter = 0;
+
+/**
+ * Creates a backreference to a capturing group.
+ *
+ * Backreferences allows to match the same text that was previously captured by a capturing group.
+ *
+ * @param name - Name to be given to the capturing group which receives this `Backreference`. If not provided, a unique name will be generated.
+ */
+export function ref(name?: string): Backreference {
+  return {
+    type: 'reference',
+    name: name ?? `ref${counter++}`,
+    encode: encodeReference,
+  };
+}
+
 function encodeCapture(this: Capture): EncodeResult {
+  const ref = this.options?.as;
+  if (ref) {
+    const refName = typeof ref === 'string' ? ref : ref?.name;
+    return {
+      precedence: 'atom',
+      pattern: `(?<${refName}>${encodeSequence(this.children).pattern})`,
+    };
+  }
+
   return {
     precedence: 'atom',
     pattern: `(${encodeSequence(this.children).pattern})`,
   };
 }
+
+function encodeReference(this: Backreference): EncodeResult {
+  return {
+    precedence: 'atom',
+    pattern: `\\k<${this.name}>`,
+  };
+}

Diff for: src/index.ts

@@ -1,9 +1,15 @@
+// Types
 export type * from './types';
+export type { CaptureOptions } from './constructs/capture';
+export type { QuantifierOptions } from './constructs/quantifiers';
+export type { RepeatOptions } from './constructs/repeat';
 
+// Builders
 export { buildPattern, buildRegExp } from './builders';
 
+// Constructs
 export { endOfString, notWordBoundary, startOfString, wordBoundary } from './constructs/anchors';
-export { capture } from './constructs/capture';
+export { capture, ref } from './constructs/capture';
 export {
   any,
   anyOf,

Diff for: test-utils/to-equal-regex.ts

@@ -4,18 +4,23 @@ import { wrapRegExp } from './utils';
 export function toEqualRegex(
   this: jest.MatcherContext,
   received: RegExp | RegexSequence,
-  expected: RegExp,
+  expected: RegExp | string,
 ) {
   received = wrapRegExp(received);
 
   const options = {
     isNot: this.isNot,
   };
 
+  const expectedSource = typeof expected === 'string' ? expected : expected.source;
+  const expectedFlags = typeof expected === 'string' ? undefined : expected.flags;
+
   return {
-    pass: expected.source === received.source && expected.flags === received.flags,
+    pass:
+      expectedSource === received.source &&
+      (expectedFlags === undefined || expectedFlags === received.flags),
     message: () =>
-      this.utils.matcherHint('toHavePattern', undefined, undefined, options) +
+      this.utils.matcherHint('toEqualRegex', undefined, undefined, options) +
       '\n\n' +
       `Expected: ${this.isNot ? 'not ' : ''}${this.utils.printExpected(expected)}\n` +
       `Received: ${this.utils.printReceived(received)}`,
@@ -28,7 +33,7 @@ declare global {
   namespace jest {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     interface Matchers<R, T = {}> {
-      toEqualRegex(expected: RegExp): R;
+      toEqualRegex(expected: RegExp | string): R;
     }
   }
 }

Diff for: test-utils/to-match-all-named-groups.ts

@@ -0,0 +1,36 @@
+import type { RegexSequence } from '../src/types';
+import { wrapRegExp } from './utils';
+
+export function toMatchAllNamedGroups(
+  this: jest.MatcherContext,
+  received: RegExp | RegexSequence,
+  inputText: string,
+  expectedGroups: Array<Record<string, string>>,
+) {
+  const receivedRegex = wrapRegExp(received);
+  const matchResult = inputText.matchAll(receivedRegex);
+  const receivedGroups = matchResult ? [...matchResult].map((r) => r.groups) : null;
+  const options = {
+    isNot: this.isNot,
+  };
+
+  return {
+    pass: this.equals(receivedGroups, expectedGroups),
+    message: () =>
+      this.utils.matcherHint('toMatchGroups', undefined, undefined, options) +
+      '\n\n' +
+      `Expected: ${this.isNot ? 'not ' : ''}${this.utils.printExpected(expectedGroups)}\n` +
+      `Received: ${this.utils.printReceived(receivedGroups)}`,
+  };
+}
+
+expect.extend({ toMatchAllNamedGroups });
+
+declare global {
+  namespace jest {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    interface Matchers<R, T = {}> {
+      toMatchAllNamedGroups(inputText: string, expectedGroups: Array<Record<string, string>>): R;
+    }
+  }
+}

Diff for: test-utils/to-match-groups.ts

@@ -4,11 +4,11 @@ import { wrapRegExp } from './utils';
 export function toMatchGroups(
   this: jest.MatcherContext,
   received: RegExp | RegexSequence,
-  expectedString: string,
+  inputText: string,
   expectedGroups: string[],
 ) {
   const receivedRegex = wrapRegExp(received);
-  const matchResult = expectedString.match(receivedRegex);
+  const matchResult = inputText.match(receivedRegex);
   const receivedGroups = matchResult ? [...matchResult] : null;
   const options = {
     isNot: this.isNot,
@@ -30,7 +30,7 @@ declare global {
   namespace jest {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     interface Matchers<R, T = {}> {
-      toMatchGroups(input: string, expected: string[]): R;
+      toMatchGroups(inputText: string, expectedGroups: string[]): R;
     }
   }
 }

Diff for: test-utils/to-match-named-groups.ts

@@ -0,0 +1,36 @@
+import type { RegexSequence } from '../src/types';
+import { wrapRegExp } from './utils';
+
+export function toMatchNamedGroups(
+  this: jest.MatcherContext,
+  received: RegExp | RegexSequence,
+  inputText: string,
+  expectedGroups: Record<string, string>,
+) {
+  const receivedRegex = wrapRegExp(received);
+  const matchResult = inputText.match(receivedRegex);
+  const receivedGroups = matchResult ? matchResult.groups : null;
+  const options = {
+    isNot: this.isNot,
+  };
+
+  return {
+    pass: this.equals(receivedGroups, expectedGroups),
+    message: () =>
+      this.utils.matcherHint('toMatchGroups', undefined, undefined, options) +
+      '\n\n' +
+      `Expected: ${this.isNot ? 'not ' : ''}${this.utils.printExpected(expectedGroups)}\n` +
+      `Received: ${this.utils.printReceived(receivedGroups)}`,
+  };
+}
+
+expect.extend({ toMatchNamedGroups });
+
+declare global {
+  namespace jest {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    interface Matchers<R, T = {}> {
+      toMatchNamedGroups(inputText: string, expectedGroups: Record<string, string>): R;
+    }
+  }
+}