Skip to main content

Getting Started

The package has two main functions. parseRegex parses patterns, and parseSubstitution parses substitution strings.

Requirements​

  • Node.js 18+
  • An active commercial subscription
  • npm, pnpm, or yarn

Install​

Install the package from npm:

npm install @r101/parser

Core API​

Parse a pattern with a flavor and its active flags:

import { Flavors, parseRegex } from '@r101/parser';

const pattern = '^(?<name>[a-z]+)-(?<id>\\d+)$';
const regexResult = parseRegex(pattern, {
  flavor: Flavors.PCRE2,
  flags: 'm',
});

The flags option is required. For a pattern with no flags, use an empty string.

Parse a substitution string with the same flavor:

import { Flavors, parseSubstitution } from '@r101/parser';

const substitutionResult = parseSubstitution('$&', {
  flavor: Flavors.PCRE2,
  flags: '',
});

parseSubstitution parses and validates the substitution syntax. It does not apply the substitution to matched text.

Parse result​

Both functions return the same result shape:

type ParseResult<T> = {
  tokens: T[];
  state: ParserState;
  patternError: boolean;
};

tokens remains available after a syntax error. Each invalid token contains a typed error code and its source position.

Options​

  • flavor selects one of the values in Flavors.
  • flags sets the active regex flags.
  • delimiter sets an optional pattern or substitution delimiter.
  • invalidFlagsBehavior selects throw or sanitize. The default is throw.
  • featureFlags changes supported optional syntax for a flavor.
  • overrideState supplies regex state to a related parse, such as capture data for a substitution.
  • decomposeQuotedLiterals exposes the atoms inside \Q...\E for analysis tools.

Runtime compatibility​

  • Browser: supported
  • Node.js: supported
  • Module formats: ESM and CommonJS
  • Tree shaking: supported

Next steps​