feat: named capture groups and reference (#66)

Author: mdjastrzebski

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,17 +1,17 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: "[Bug]"
+title: '[Bug]'
 labels: ''
 assignees: ''
-
 ---
 
 **Describe the bug**
 A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1.
 2.
 3.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,10 +1,9 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
-title: "[Feature]"
+title: '[Feature]'
 labels: enhancement
 assignees: ''
-
 ---
 
 **Is your feature request related to a problem? Please describe.**
@@ -17,10 +16,11 @@ A clear and concise description of what you want to happen.
 A clear and concise description of any alternative solutions or features you've considered.
 
 **Checklist**
+
 - [ ] Implementation
 - [ ] Tests
-- [ ] API docs 
-- [ ] README docs (if relevant) 
+- [ ] API docs
+- [ ] README docs (if relevant)
 - [ ] Example docs & tests (if relevant)
 
 **Additional context**

.watchmanconfig

@@ -1 +1 @@
-{}
+{}

.yarnrc.yml

@@ -3,8 +3,8 @@ nmHoistingLimits: workspaces
 
 plugins:
   - path: .yarn/plugins/@yarnpkg/plugin-interactive-tools.cjs
-    spec: "@yarnpkg/plugin-interactive-tools"
+    spec: '@yarnpkg/plugin-interactive-tools'
   - path: .yarn/plugins/@yarnpkg/plugin-workspace-tools.cjs
-    spec: "@yarnpkg/plugin-workspace-tools"
+    spec: '@yarnpkg/plugin-workspace-tools'
 
 yarnPath: .yarn/releases/yarn-3.6.1.cjs

CODE_OF_CONDUCT.md

@@ -1,4 +1,3 @@
-
 # Contributor Covenant Code of Conduct
 
 ## Our Pledge
@@ -18,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
+- Focusing on what is best not just for us as individuals, but for the overall
   community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or advances of
+- The use of sexualized language or imagery, and sexual attention or advances of
   any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
   without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities

README.md

@@ -152,7 +152,6 @@ See [Character Classes API doc](https://callstack.github.io/ts-regex-builder/api
 | `lookbehind(...)`         | `(?<=...)`   | Match preceding text without consuming it                                |
 | `negativeLookbehind(...)` | `(?<!...)`   | Reject preceding text without consuming it                               |
 
-
 See [Assertions API doc](https://callstack.github.io/ts-regex-builder/api/assertions) for more info.
 
 ## Examples

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';

lefthook.yml

@@ -2,10 +2,10 @@ pre-commit:
   parallel: true
   commands:
     lint:
-      glob: "*.{js,ts,jsx,tsx}"
+      glob: '*.{js,ts,jsx,tsx}'
       run: npx eslint {staged_files}
     types:
-      glob: "*.{js,ts, jsx, tsx}"
+      glob: '*.{js,ts, jsx, tsx}'
       run: npx tsc --noEmit
 commit-msg:
   parallel: true

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 tagContent = zeroOrMore(any, { greedy: false });
+
+  const tagMatcher = buildRegExp(
+    [
+      '<',
+      capture(tagName, { name: 'tag' }),
+      '>',
+      capture(tagContent, { name: 'content' }),
+      '</',
+      ref('tag'),
+      '>',
+    ],
+    { 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>>');
+});

src/constructs/__tests__/capture.test.tsx

@@ -1,4 +1,15 @@
-import { capture, oneOrMore } from '../..';
+import {
+  any,
+  anyOf,
+  buildRegExp,
+  capture,
+  digit,
+  negated,
+  oneOrMore,
+  ref,
+  word,
+  wordBoundary,
+} from '../..';
 
 test('`capture` pattern', () => {
   expect(capture('a')).toEqualRegex(/(a)/);
@@ -12,3 +23,100 @@ 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', { name: 'xyz' })).toEqualRegex('(?<xyz>a)');
+  expect(capture('abc', { name: 'xyz' })).toEqualRegex('(?<xyz>abc)');
+  expect(capture(oneOrMore('abc'), { name: 'xyz' })).toEqualRegex('(?<xyz>(?:abc)+)');
+  expect(oneOrMore(capture('abc', { name: 'xyz' }))).toEqualRegex('(?<xyz>abc)+');
+});
+
+test('named `capture` matching', () => {
+  expect(capture('b', { name: 'x1' })).toMatchGroups('ab', ['b', 'b']);
+  expect(capture('b', { name: 'x1' })).toMatchNamedGroups('ab', { x1: 'b' });
+
+  expect(['a', capture('b', { name: 'x1' })]).toMatchGroups('ab', ['ab', 'b']);
+  expect(['a', capture('b', { name: 'x1' })]).toMatchNamedGroups('ab', { x1: 'b' });
+
+  expect([capture('a'), capture('b', { name: 'x1' }), capture('c', { name: 'x2' })]).toMatchGroups(
+    'abc',
+    ['abc', 'a', 'b', 'c'],
+  );
+  expect([
+    capture('a'),
+    capture('b', { name: 'x1' }),
+    capture('c', { name: 'x2' }),
+  ]).toMatchNamedGroups('abc', { x1: 'b', x2: 'c' });
+});
+
+test('`reference` pattern', () => {
+  expect([ref('ref0')]).toEqualRegex(/\k<ref0>/);
+  expect([ref('xyz')]).toEqualRegex(/\k<xyz>/);
+  expect([capture(any, { name: 'ref0' }), ' ', ref('ref0')]).toEqualRegex('(?<ref0>.) \\k<ref0>');
+
+  expect(['xx', capture(any, { name: 'r123' }), ' ', ref('r123'), 'xx']).toEqualRegex(
+    'xx(?<r123>.) \\k<r123>xx',
+  );
+});
+
+test('`reference` matching basic case', () => {
+  expect([capture(word, { name: 'a' }), ref('a')]).toMatchString('aa');
+  expect([capture(digit, { name: 'a' }), ref('a')]).toMatchString('11');
+
+  expect([capture(any, { name: 'a' }), ref('a')]).not.toMatchString('ab');
+  expect([capture(digit, { name: 'a' }), ref('a')]).not.toMatchString('1a');
+  expect([capture(digit, { name: 'a' }), ref('a')]).not.toMatchString('a1');
+});
+
+test('`reference` matching variable case', () => {
+  const someRef = ref('test');
+  expect([capture(word, { name: someRef.name }), someRef]).toMatchString('aa');
+  expect([capture(digit, { name: someRef.name }), someRef]).toMatchString('11');
+
+  expect([capture(any, { name: someRef.name }), someRef]).not.toMatchString('ab');
+  expect([capture(digit, { name: someRef.name }), someRef]).not.toMatchString('1a');
+  expect([capture(digit, { name: someRef.name }), someRef]).not.toMatchString('a1');
+});
+
+test('`reference` matching HTML attributes', () => {
+  const quoteChars = anyOf('"\'');
+  const htmlAttributeRegex = buildRegExp([
+    wordBoundary,
+    capture(oneOrMore(word), { name: 'name' }),
+    '=',
+    capture(quoteChars, { name: 'quote' }),
+    capture(oneOrMore(negated(quoteChars)), { name: 'value' }),
+    ref('quote'),
+  ]);
+
+  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' />`);
+});

src/constructs/capture.ts

@@ -6,19 +6,70 @@ 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 type CaptureOptions = {
+  /**
+   * Name to be given to the capturing group.
+   */
+  name?: string;
+};
+
+export interface Reference 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 {@link ref}
+ */
+export function capture(sequence: RegexSequence, options?: CaptureOptions): Capture {
   return {
     type: 'capture',
     children: ensureArray(sequence),
+    options,
     encode: encodeCapture,
   };
 }
 
+/**
+ * Creates a reference, also known as backreference, which allows matching
+ * again the exact text that a capturing group previously matched.
+ *
+ * In order to form a valid regex, the reference must use the same name as
+ * a capturing group earlier in the expression.
+ *
+ * @param name - Name of the capturing group to reference.
+ */
+export function ref(name: string): Reference {
+  return {
+    type: 'reference',
+    name,
+    encode: encodeReference,
+  };
+}
+
 function encodeCapture(this: Capture): EncodeResult {
+  const name = this.options?.name;
+  if (name) {
+    return {
+      precedence: 'atom',
+      pattern: `(?<${name}>${encodeSequence(this.children).pattern})`,
+    };
+  }
+
   return {
     precedence: 'atom',
     pattern: `(${encodeSequence(this.children).pattern})`,
   };
 }
+
+function encodeReference(this: Reference): EncodeResult {
+  return {
+    precedence: 'atom',
+    pattern: `\\k<${this.name}>`,
+  };
+}

src/index.ts

@@ -1,15 +1,21 @@
+// 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,
   nonWordBoundary,
   notWordBoundary,
   startOfString,
   wordBoundary,
 } from './constructs/anchors';
-export { capture } from './constructs/capture';
+export { capture, ref } from './constructs/capture';
 export {
   any,
   anyOf,

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;
     }
   }
 }

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;
+    }
+  }
+}

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;
     }
   }
 }

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;
+    }
+  }
+}

website/docs/api/captures.md

@@ -0,0 +1,65 @@
+---
+id: captures
+title: Captures
+---
+
+### `capture()`
+
+```ts
+function capture(
+  sequence: RegexSequence,
+  options?: {
+    name?: string;
+  },
+): Capture;
+```
+
+Regex syntax:
+
+- `(...)` for capturing groups (no `name` option)
+- `(?<name>...)` for named capturing groups (`name` option)
+
+Captures, also known as capturing groups, extract and store parts of the matched string for later use.
+
+Capture results are available using array-like [`match()` result object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match#using_match).
+
+#### Named groups
+
+When using `name` options, the group becomes a [named capturing group](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Named_capturing_group) allowing to refer to it using name instead of index.
+
+Named capture results are available using [`groups`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match#using_named_capturing_groups) property on `match()` result.
+
+:::note
+
+TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required. E.g., `zeroOrMore("abc")` is encoded as `(?:abc)+`.
+
+:::
+
+### `ref()`
+
+```ts
+function ref(name: string): Reference;
+```
+
+Regex syntax: `\k<...>`.
+
+Creates a reference, also known as a backreference, which allows matching again the exact text that a capturing group previously matched. The reference must use the same name as some capturing group earlier in the expression to form a valid regex.
+
+Usage with `capture()`:
+
+```ts
+const regex = buildRegExp([
+  // Create a named capture using name from `someKey`.
+  capture(..., { name: 'someKey' }),
+  // ... some other elements ...
+
+  // Match the same text as matched by `capture` with the same name.
+  ref('someKey'),
+  ])
+```
+
+:::note
+
+TS Regex Builder doesn't support using ordinal backreferences (`\1`, `\2`, etc) because in complex regex patterns, these references are difficult to accurately use.
+
+:::

website/docs/api/constructs.md

@@ -19,30 +19,10 @@ The `choiceOf` (disjunction) construct matches one out of several possible seque
 
 Example: `choiceOf("color", "colour")` matches either `color` or `colour` pattern.
 
-### `capture()`
-
-```ts
-function capture(
-  sequence: RegexSequence,
-): Capture;
-```
-
-Regex syntax: `(...)`.
-
-Captures, also known as capturing groups, extract and store parts of the matched string for later use.
-
-:::note
-
-TS Regex Builder does not have a construct for non-capturing groups. Such groups are implicitly added when required. E.g., `zeroOrMore("abc")` is encoded as `(?:abc)+`.
-
-:::
-
 ### `regex()`
 
 ```ts
-function regex(
-  sequence: RegexSequence,
-): Regex;
+function regex(sequence: RegexSequence): Regex;
 ```
 
 Regex syntax: the pattern remains unchanged when wrapped by this construct.

website/docs/api/overview.md

@@ -100,5 +100,4 @@ See [Character Classes](./api/character-classes) for more info.
 | `lookbehind(...)`         | `(?<=...)`   | Match preceding text without consuming it                                |
 | `negativeLookbehind(...)` | `(?<!...)`   | Reject preceding text without consuming it                               |
 
-
 See [Assertions](./api/assertions) for more info.

website/docs/api/types.md

@@ -6,20 +6,15 @@ title: Types
 ### `RegexSequence`
 
 ```ts
-type RegexSequence = 
-    | RegexElement[]
-    | RegexElement;
+type RegexSequence = RegexElement[] | RegexElement;
 ```
 
 The sequence of regex elements forming a regular expression. For developer convenience, it also accepts a single element instead of an array.
 
 ### `RegexElement`
 
 ```ts
-type RegexElement = 
-    | RegexConstruct
-    | RegExp
-    | string;
+type RegexElement = RegexConstruct | RegExp | string;
 ```
 
 Regex elements are fundamental building blocks of a regular expression. These can be either further regex constructs, regular strings to be matched literally or `RegExp` literals (`/.../`) for including simple regexes as part of a larger structure.

website/sidebars.js

@@ -29,6 +29,7 @@ export default {
         'api/types',
         'api/builder',
         'api/constructs',
+        'api/captures',
         'api/quantifiers',
         'api/character-classes',
         'api/assertions',