RegExp Literal AST Parser

Common errors

• Error: Cannot find module 'regexpp2'

  cause `regexp-parser-literal` relies on `regexpp2` as a direct runtime dependency, which might not be installed in some environments (e.g., if using older npm versions or specific CI setups).
  fix Ensure `regexpp2` is explicitly installed in your project: `npm install regexpp2` or `yarn add regexpp2`.

• TypeError: (0 , regexp_parser_literal__WEBPACK_IMPORTED_MODULE_0__.parseRegExp) is not a function

  cause This error often occurs in CommonJS environments or specific bundler configurations when trying to import a named export incorrectly, or if the module resolution is misconfigured.
  fix For ES Modules, ensure you're using `import { parseRegExp } from 'regexp-parser-literal';`. For CommonJS, if transpilation is not handling it correctly, try `const { parseRegExp } = require('regexp-parser-literal');` or `const parser = require('regexp-parser-literal'); const ast = parser.parseRegExp(...)`.

Warnings

• breaking Major version updates of `regexpp2`, the underlying parsing engine, may introduce breaking changes to the AST structure or parsing behavior that could affect `regexp-parser-literal`. Always review the release notes for both libraries during upgrades.
  Fix: Pin `regexp-parser-literal` and `regexpp2` to compatible versions. Test thoroughly when upgrading either package.
• gotcha Incorrect handling of the `u` (Unicode) flag when parsing patterns can lead to unexpected AST structures or parsing errors, especially with Unicode escape sequences or astral plane characters. Ensure the `uFlag` parameter in `parsePattern` or `createRegExpParser` options is correctly set.
  Fix: Pass `true` for the `uFlag` parameter to `parsePattern` or configure the parser with `{ unicode: true }` in `createRegExpParser` when dealing with Unicode-aware regular expressions.
• gotcha Direct modification of the AST (Abstract Syntax Tree) without deep understanding of the `regexpp2` AST specification can easily lead to invalid or malformed regular expressions when `astToString` is used. The `astToString` function does not validate the semantic correctness of the AST.
  Fix: Refer to the `regexpp2` documentation for the AST specification. Perform thorough testing of any modified ASTs to ensure they generate valid and intended regular expressions.

Install

• npm install regexp-parser-literal npm
• yarn add regexp-parser-literal yarn
• pnpm add regexp-parser-literal pnpm

Imports

• parseRegExp
  wrong:

  import parseRegExp from 'regexp-parser-literal';

  correct:

  import { parseRegExp } from 'regexp-parser-literal';

  This is a named export, not the default export. Primarily used to parse a full regular expression string, including slashes and flags.
• astToString
  wrong:

  const astToString = require('regexp-parser-literal').astToString;

  correct:

  import { astToString } from 'regexp-parser-literal';

  CommonJS users must destructure named exports or access them as properties of the main export object. Essential for converting an AST back into a regular expression string.
• defaultRegExpParser
  wrong:

  import { RegExpParser } from 'regexp-parser-literal';

  correct:

  import { defaultRegExpParser } from 'regexp-parser-literal';

  `defaultRegExpParser` is an instantiated parser object from `regexpp2`, while `RegExpParser` is a type. Use this instance for methods like `parsePattern`.
• EMOJI_REGEX

  import { EMOJI_REGEX } from 'regexp-parser-literal';

  A pre-defined RegExp object exposed by the library, useful for emoji-related pattern matching or filtering.

Quickstart

Demonstrates parsing a full regex literal, a pattern, converting an AST back to a string, and utilizing the `EMOJI_REGEX`.

import { parseRegExp, astToString, EMOJI_REGEX } from 'regexp-parser-literal';
import { defaultRegExpParser } from 'regexp-parser-literal';

// Example 1: Parsing a complete regular expression literal
const regexInput = "/hello world!/gi";
const astLiteral = parseRegExp(regexInput);
console.log('Parsed AST Type:', astLiteral.type); // RegExpLiteral
console.log('Parsed AST Body Type:', astLiteral.body.type); // Pattern
console.log('Parsed AST Flags Type:', astLiteral.flags.type); // Flags
console.log('Extracted Flags:', astLiteral.flags.raw);

// Example 2: Parsing only a pattern string using the default parser instance
const patternInput = "foo|bar\\d+";
const patternAst = defaultRegExpParser.parsePattern(patternInput);
console.log('Parsed Pattern AST Type:', patternAst.type); // Pattern
console.log('Number of pattern elements:', patternAst.elements.length);

// Example 3: Converting an AST back to a string
// In a real scenario, you would modify the AST elements before stringification
const stringifiedRegex = astToString(astLiteral);
console.log('Stringified AST back to regex:', stringifiedRegex);

// Example 4: Using the provided EMOJI_REGEX
const textWithEmoji = "Hello 👋 world! 🌍";
console.log('Does text contain emoji?', EMOJI_REGEX.test(textWithEmoji));
console.log('Matching emojis:', textWithEmoji.match(EMOJI_REGEX)?.join(', '));