feat: support for lookarounds and non-capture groups

Author: PaulPhilp

docs/API.md

@@ -58,6 +58,65 @@ Regex syntax: `(...)`.
 
 Captures, also known as capturing groups, extract and store parts of the matched string for later use.
 
+### `nonCaptureGroup()`
+
+```ts
+function nonCaptureGroup(
+  sequence: RegexSequence
+): NonCaptureGroup
+```
+
+Regex syntax: `(?:...)`.
+
+Groups multiple tokens together without creating a capture group.
+
+### `positiveLookahead()`
+
+```ts
+function positiveLookahead(
+  sequence: RegexSequence
+): PositiveLookahead
+```
+
+Regex syntax: `(?=...)`.
+
+Matches a group after the main expression without including it in the result.
+
+### `negativeLookahead()`
+
+```ts
+function negativeLookahead(
+  sequence: RegexSequence
+): NegativeLookahead
+```
+
+Regex syntax: `(?!...)`.
+
+Specifies a group that can not match after the main expression (if it matches, the result is discarded).
+
+### `positiveLookbehind()`
+
+```ts
+function positiveLookahead(
+  sequence: RegexSequence
+): PositiveLookahead
+```
+
+Regex syntax: `(?<=...)`.
+
+Matches a group before the main expression without including it in the result.
+
+### `negativeLookbehind()`
+
+```ts
+function negativeLookahead(
+  sequence: RegexSequence
+): NegativeLookahead
+```
+
+Regex syntax: `(?<!...)`.
+
+Specifies a group that can not match before the main expression (if it matches, the result is discarded).
 ### `choiceOf()`
 
 ```ts

src/constructs/__tests__/negative-lookahead.test.ts

@@ -0,0 +1,37 @@
+import { negativeLookahead } from '../negative-lookahead';
+import { oneOrMore, zeroOrMore } from '../quantifiers';
+import { anyOf, digit } from '../character-class';
+import { capture } from '../capture';
+
+test('`Negative Lookahead` base cases', () => {
+  expect(negativeLookahead('a')).toEqualRegex(/(?!a)/);
+  expect(negativeLookahead('abc')).toEqualRegex(/(?!abc)/);
+  expect(negativeLookahead(oneOrMore('abc'))).toEqualRegex(/(?!(?:abc)+)/);
+  expect(oneOrMore(negativeLookahead('abc'))).toEqualRegex(/(?!abc)+/);
+});
+
+test('`Negative Lookahead` use cases', () => {
+  expect([negativeLookahead('$'), oneOrMore(digit)]).toMatchString('1 turkey costs 30$');
+  expect([negativeLookahead('a'), 'b']).toMatchString('abba');
+  expect(['a', negativeLookahead(capture('bba'))]).not.toMatchGroups('abba', ['a', 'bba']);
+  expect([negativeLookahead('-'), anyOf('+-'), zeroOrMore(digit)]).not.toMatchString('-123');
+  expect([negativeLookahead('-'), anyOf('+-'), zeroOrMore(digit)]).toMatchString('+123');
+});
+
+test('`Negative Lookahead` with multiple elements', () => {
+  expect(negativeLookahead(['abc', 'def'])).toEqualRegex(/(?!abcdef)/);
+  expect(negativeLookahead([oneOrMore('abc'), 'def'])).toEqualRegex(/(?!(?:abc)+def)/);
+  expect(negativeLookahead(['abc', oneOrMore('def')])).toEqualRegex(/(?!abc(?:def)+)/);
+});
+
+test('`Negative Lookahead` with special characters', () => {
+  expect(negativeLookahead(['$', '+'])).toEqualRegex(/(?!\$\+)/);
+  expect(negativeLookahead(['[', ']'])).toEqualRegex(/(?!\[\])/);
+  expect(negativeLookahead(['\\', '\\'])).toEqualRegex(/(?!\\\\)/);
+});
+
+test('`Negative Lookahead` with quantifiers', () => {
+  expect(negativeLookahead(zeroOrMore('abc'))).toEqualRegex(/(?!(?:abc)*)/);
+  expect(negativeLookahead(oneOrMore('abc'))).toEqualRegex(/(?!(?:abc)+)/);
+  expect(negativeLookahead(['abc', zeroOrMore('def')])).toEqualRegex(/(?!abc(?:def)*)/);
+});

src/constructs/__tests__/negative-lookbehind.test.ts

@@ -0,0 +1,26 @@
+import { negativeLookbehind } from '../negative-lookbehind';
+import { oneOrMore } from '../quantifiers';
+
+test('`Negative Lookbehind` with single character', () => {
+  expect(negativeLookbehind('a')).toEqualRegex(/(?<!a)/);
+  expect(negativeLookbehind('b')).toEqualRegex(/(?<!b)/);
+  expect(negativeLookbehind('c')).toEqualRegex(/(?<!c)/);
+});
+
+test('`Negative Lookbehind` with multiple characters', () => {
+  expect(negativeLookbehind('abc')).toEqualRegex(/(?<!abc)/);
+  expect(negativeLookbehind('def')).toEqualRegex(/(?<!def)/);
+  expect(negativeLookbehind('xyz')).toEqualRegex(/(?<!xyz)/);
+});
+
+test('`Negative Lookbehind` with quantifiers', () => {
+  expect(negativeLookbehind(oneOrMore('abc'))).toEqualRegex(/(?<!(?:abc)+)/);
+  expect(negativeLookbehind(oneOrMore('def'))).toEqualRegex(/(?<!(?:def)+)/);
+  expect(negativeLookbehind(oneOrMore('xyz'))).toEqualRegex(/(?<!(?:xyz)+)/);
+});
+
+test('`Negative Lookbehind` with special characters', () => {
+  expect(negativeLookbehind('-')).toEqualRegex(/(?<!-)/);
+  expect(negativeLookbehind('$')).toEqualRegex(/(?<!\$)/);
+  expect(negativeLookbehind('@')).toEqualRegex(/(?<!@)/);
+});

src/constructs/__tests__/non-capture-group.test.ts

@@ -0,0 +1,27 @@
+import { nonCaptureGroup } from '../non-capture-group';
+import { oneOrMore } from '../quantifiers';
+
+test('`NonCaptureGroup` base cases', () => {
+  expect(nonCaptureGroup('a')).toEqualRegex(/(:a)/);
+  expect(nonCaptureGroup('abc')).toEqualRegex(/(:abc)/);
+  expect(nonCaptureGroup(oneOrMore('abc'))).toEqualRegex(/(:(?:abc)+)/);
+  expect(oneOrMore(nonCaptureGroup('abc'))).toEqualRegex(/(:abc)+/);
+});
+
+test('`NonCaptureGroup` does not capture group', () => {
+  expect(nonCaptureGroup('b')).not.toMatchGroups('ab', ['b']);
+  expect(['a', nonCaptureGroup('b')]).not.toMatchGroups('ab', ['ab']);
+  expect(['a', nonCaptureGroup('b'), nonCaptureGroup('c')]).not.toMatchGroups('abc', ['abc']);
+});
+
+test('`NonCaptureGroup` with special characters', () => {
+  expect(nonCaptureGroup('$')).toEqualRegex(/(:\$)/);
+  expect(nonCaptureGroup('+')).toEqualRegex(/(:\+)/);
+  expect(nonCaptureGroup('\\')).toEqualRegex(/(:\\)/);
+});
+
+test('`NonCaptureGroup` with quantifiers', () => {
+  expect(nonCaptureGroup(oneOrMore('abc'))).toEqualRegex(/(:(?:abc)+)/);
+  expect(nonCaptureGroup(oneOrMore('def'))).toEqualRegex(/(:(?:def)+)/);
+  expect(nonCaptureGroup(oneOrMore('xyz'))).toEqualRegex(/(:(?:xyz)+)/);
+});

src/constructs/__tests__/positive-lookahead.test.ts

@@ -0,0 +1,40 @@
+import { positiveLookahead } from '../positive-lookahead';
+import { capture } from '../capture';
+import { oneOrMore, zeroOrMore } from '../quantifiers';
+import { digit, word } from '../character-class';
+
+test('`Positive Lookahead` base cases', () => {
+  expect(positiveLookahead('a')).toEqualRegex(/(?=a)/);
+  expect([digit, positiveLookahead('abc')]).toEqualRegex(/\d(?=abc)/);
+  expect(positiveLookahead(oneOrMore('abc'))).toEqualRegex(/(?=(?:abc)+)/);
+  expect([zeroOrMore(word), positiveLookahead('abc')]).toEqualRegex(/\w*(?=abc)/);
+});
+
+test('`Positive Lookahead` use cases', () => {
+  expect([oneOrMore(digit), positiveLookahead('$')]).toMatchString('1 turkey costs 30$');
+  expect(['q', positiveLookahead('u')]).toMatchString('queen');
+  expect(['a', positiveLookahead('b'), positiveLookahead('c')]).not.toMatchString('abc');
+  expect(['a', positiveLookahead(capture('bba'))]).toMatchGroups('abba', ['a', 'bba']);
+});
+
+test('`Positive Lookahead` with multiple elements', () => {
+  expect(positiveLookahead(['a', 'b', 'c'])).toEqualRegex(/(?=abc)/);
+});
+
+test('`Positive Lookahead` with nested constructs', () => {
+  expect(positiveLookahead(oneOrMore(capture('abc')))).toEqualRegex(/(?=(abc)+)/);
+  expect(positiveLookahead([zeroOrMore(word), capture('abc')])).toEqualRegex(/(?=\w*(abc))/);
+});
+
+test('`Positive Lookahead` with special characters', () => {
+  expect(positiveLookahead(['$', capture('abc')])).toEqualRegex(/(?=\$(abc))/);
+  expect(positiveLookahead(['q', capture('u')])).toEqualRegex(/(?=q(u))/);
+});
+
+test('`Positive Lookahead` with capture group', () => {
+  expect(positiveLookahead(capture('bba'))).toEqualRegex(/(?=(bba))/);
+});
+
+test('`Positive Lookahead` with digit character class', () => {
+  expect(positiveLookahead([digit, 'abc'])).toEqualRegex(/(?=\dabc)/);
+});

src/constructs/__tests__/positive-lookbehind.test.ts

@@ -0,0 +1,59 @@
+import { positiveLookbehind } from '../positive-lookbehind';
+import { oneOrMore, zeroOrMore } from '../quantifiers';
+import { anyOf, digit, whitespace, word } from '../character-class';
+
+test('`Positive Lookbehind` base cases', () => {
+  expect(positiveLookbehind('a')).toEqualRegex(/(?<=a)/);
+  expect(positiveLookbehind('abc')).toEqualRegex(/(?<=abc)/);
+  expect(positiveLookbehind(oneOrMore('abc'))).toEqualRegex(/(?<=(?:abc)+)/);
+  expect(positiveLookbehind('abc')).toEqualRegex(/(?<=abc)/);
+});
+
+test('`Positve Lookbehind` use cases', () => {
+  expect([
+    zeroOrMore(whitespace),
+    word,
+    positiveLookbehind('s'),
+    oneOrMore(whitespace),
+  ]).toMatchString('too many cats to feed.');
+
+  expect([positiveLookbehind('USD'), zeroOrMore(whitespace), oneOrMore(digit)]).toMatchString(
+    'The price is USD 30',
+  );
+
+  expect([positiveLookbehind('USD'), zeroOrMore(whitespace), oneOrMore(digit)]).not.toMatchString(
+    'The price is CDN 30',
+  );
+
+  expect([positiveLookbehind('a'), 'b']).toMatchString('abba');
+
+  const mjsImport = [positiveLookbehind('.mjs')];
+  expect(mjsImport).toMatchString("import {Person} from './person.mjs';");
+  expect(mjsImport).not.toMatchString("import {Person} from './person.js';");
+  expect([anyOf('+-'), oneOrMore(digit), positiveLookbehind('-')]).not.toMatchString('+123');
+});
+
+test('`Positive Lookbehind` with multiple elements', () => {
+  expect(positiveLookbehind(['abc', 'def'])).toEqualRegex(/(?<=abcdef)/);
+  expect(positiveLookbehind([oneOrMore('abc'), 'def'])).toEqualRegex(/(?<=(?:abc)+def)/);
+  expect(positiveLookbehind(['abc', oneOrMore('def')])).toEqualRegex(/(?<=abc(?:def)+)/);
+});
+
+test('`Positive Lookbehind` with special characters', () => {
+  expect(positiveLookbehind(['$', '+'])).toEqualRegex(/(?<=\$\+)/);
+  expect(positiveLookbehind(['[', ']'])).toEqualRegex(/(?<=\[\])/);
+  expect(positiveLookbehind(['\\', '\\'])).toEqualRegex(/(?<=\\\\)/);
+});
+
+test('`Positive Lookbehind` with quantifiers', () => {
+  expect(positiveLookbehind(zeroOrMore('abc'))).toEqualRegex(/(?<=(?:abc)*)/);
+  expect(positiveLookbehind(oneOrMore('abc'))).toEqualRegex(/(?<=(?:abc)+)/);
+  expect(positiveLookbehind(['abc', zeroOrMore('def')])).toEqualRegex(/(?<=abc(?:def)*)/);
+});
+
+test('`Positive Lookbehind` with character classes', () => {
+  expect(positiveLookbehind(word)).toEqualRegex(/(?<=\w)/);
+  expect(positiveLookbehind(whitespace)).toEqualRegex(/(?<=\s)/);
+  expect(positiveLookbehind(digit)).toEqualRegex(/(?<=\d)/);
+  expect(positiveLookbehind(anyOf('abc'))).toEqualRegex(/(?<=[abc])/);
+});

src/constructs/negative-lookahead.ts

@@ -0,0 +1,38 @@
+import { encodeSequence } from '../encoder/encoder';
+import type { EncodeResult } from '../encoder/types';
+import { ensureArray } from '../utils/elements';
+import type { RegexConstruct, RegexElement, RegexSequence } from '../types';
+
+/**
+ * Negative lookahead assertion.
+ *
+ * A negative lookahead assertion is a zero-width assertion that matches a group of characters only if it is not followed by a specific group of characters.
+ *
+ * @example
+ * ```ts
+ * negativeLookahead("a");
+ * // /(?=a)/
+ *
+ * negativeLookahead(["a", "b", "c"]);
+ * // /(?=abc)/
+ * ```
+ */
+export interface NegativeLookahead extends RegexConstruct {
+  type: 'NegativeLookahead';
+  children: RegexElement[];
+}
+
+export function negativeLookahead(sequence: RegexSequence): NegativeLookahead {
+  return {
+    type: 'NegativeLookahead',
+    children: ensureArray(sequence),
+    encode: encodeNegativeLookahead,
+  };
+}
+
+function encodeNegativeLookahead(this: NegativeLookahead): EncodeResult {
+  return {
+    precedence: 'atom',
+    pattern: `(?!${encodeSequence(this.children).pattern})`,
+  };
+}

src/constructs/negative-lookbehind.ts

@@ -0,0 +1,38 @@
+import { encodeSequence } from '../encoder/encoder';
+import type { EncodeResult } from '../encoder/types';
+import { ensureArray } from '../utils/elements';
+import type { RegexConstruct, RegexElement, RegexSequence } from '../types';
+
+/**
+ * Negative lookbehind assertion.
+ *
+ * A negative lookbehind assertion is a zero-width assertion that matches a group of characters only if it is not preceded by a specific group of characters.
+ *
+ * @example
+ * ```ts
+ * negativeLookbehind("a");
+ * // /(?<!a)/
+ *
+ * negativeLookbehind(["a", "b", "c"]);
+ * // /(?<!abc)/
+ * ```
+ */
+export interface NegativeLookbehind extends RegexConstruct {
+  type: 'NegativeLookbehind';
+  children: RegexElement[];
+}
+
+export function negativeLookbehind(sequence: RegexSequence): NegativeLookbehind {
+  return {
+    type: 'NegativeLookbehind',
+    children: ensureArray(sequence),
+    encode: encodeNegativeLookbehind,
+  };
+}
+
+function encodeNegativeLookbehind(this: NegativeLookbehind): EncodeResult {
+  return {
+    precedence: 'atom',
+    pattern: `(?<!${encodeSequence(this.children).pattern})`,
+  };
+}

src/constructs/non-capture-group.ts

@@ -0,0 +1,38 @@
+import { encodeSequence } from '../encoder/encoder';
+import type { EncodeResult } from '../encoder/types';
+import { ensureArray } from '../utils/elements';
+import type { RegexConstruct, RegexElement, RegexSequence } from '../types';
+
+/**
+ * Non-capture group.
+ *
+ * A non-capture group is a group that does not capture the matched characters, allowing for more efficient matching.
+ *
+ * @example
+ * ```ts
+ * nonCaptureGroup("a");
+ * // /(?:a)/
+ *
+ * nonCaptureGroup(["a", "b", "c"]);
+ * // /(?:abc)/
+ * ```
+ */
+export interface NonCaptureGroup extends RegexConstruct {
+  type: 'NonCaptureGroup';
+  children: RegexElement[];
+}
+
+export function nonCaptureGroup(sequence: RegexSequence): NonCaptureGroup {
+  return {
+    type: 'NonCaptureGroup',
+    children: ensureArray(sequence),
+    encode: encodeNonCaptureGroup,
+  };
+}
+
+function encodeNonCaptureGroup(this: NonCaptureGroup): EncodeResult {
+  return {
+    precedence: 'atom',
+    pattern: `(:${encodeSequence(this.children).pattern})`,
+  };
+}