APG Lite Parser

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` in an ECMAScript Module (ESM) context or a browser where `apg-lite` is loaded via standard script tags.
  fix For Node.js, ensure your project or file is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extensions) and use `import` statements. For browsers, use `<script src="..."></script>` for `web-parser.js`.

• SyntaxError: Cannot use import statement outside a module

  cause Using an `import` statement in a Node.js file that is treated as CommonJS (e.g., `.js` file without `"type": "module"` in `package.json`).
  fix Either change your Node.js project to use ESM by adding `"type": "module"` to `package.json`, or rename the file to have a `.mjs` extension. Alternatively, if bundling for a browser, ensure your bundler supports ESM.

• TypeError: Parser is not a constructor

  cause Incorrectly importing or accessing the `Parser` class/function from `apg-lite`, or attempting to use a CommonJS `require()` result as a constructor when it's an ESM export.
  fix Verify the correct ESM import path (e.g., `import { Parser } from 'apg-lite/lib/parser'`) and ensure your environment supports ESM. If `Parser` is a factory function, use `Parser()` instead of `new Parser()`.

Warnings

• breaking apg-lite is a parser *only*. It does not generate grammars. Grammar objects must be pre-generated using `apg-js` (v4.3.0+) with the `--lite` option. Directly feeding ABNF definitions to `apg-lite` will not work.
  Fix: Use `apg-js` (version 4.3.0 or higher) with its `--lite` option to generate the grammar object files, then import those generated objects into your `apg-lite` application.
• breaking apg-lite only parses JavaScript strings. It does not support parsing arbitrary arrays of positive integers, a feature available in the full `apg-js` library.
  Fix: Ensure all input for `apg-lite` parsers is a JavaScript string. If you require parsing integer arrays, consider using the full `apg-js` library instead.
• breaking apg-lite supports only three SABNF superset operators: User-Defined Terminals (UDT), positive look-ahead (AND), and negative look-ahead (NOT). Grammars utilizing other SABNF operators (e.g., semantic validation, case-sensitive/insensitive string literals) will not be correctly processed or will fail.
  Fix: Simplify your ABNF/SABNF grammars to rely solely on the supported UDT, AND, and NOT operators for use with `apg-lite`. For full SABNF feature support, use `apg-js`.
• gotcha Version 1.0.5 fixed a critical bug in the URI grammar definition where previous versions incorrectly allowed empty strings for IPv4 octets. Relying on pre-1.0.5 URI parsing behavior may lead to incorrectly validated URIs.
  Fix: Update to `apg-lite` version 1.0.5 or higher to ensure correct and RFC-compliant URI parsing behavior, especially if using the `UriParser`.

Install

• npm install apg-lite npm
• yarn add apg-lite yarn
• pnpm add apg-lite pnpm

Imports

• Parser
  wrong:

  const { Parser } = require('apg-lite/lib/parser')

  correct:

  import { Parser } from 'apg-lite/lib/parser'

  The primary parser module is ESM-only and typically exports a class or factory function like 'Parser'.
• UriParser
  wrong:

  const { UriParser } = require('apg-lite/uri-app/UriParser')

  correct:

  import { UriParser } from 'apg-lite/uri-app/UriParser'

  The specialized URI parser is a self-contained ESM module provided as an example, suitable for direct import.
• webParserScript
  wrong:

  import { Parser } from 'apg-lite/lib/web-parser'

  correct:

  <script src="./node_modules/apg-lite/lib/web-parser.js"></script>

  `web-parser.js` is designed for direct inclusion via a `<script>` tag in web pages, making global objects available rather than named ESM exports for direct import.

Quickstart

Demonstrates how to import and use the self-contained UriParser to parse various URI strings, logging success or failure with the resulting AST.

import { UriParser } from 'apg-lite/uri-app/UriParser';

const uriStrings = [
  'http://user:pass@host:80/path?query#fragment',
  'mailto:john.doe@example.com',
  'ftp://ftp.example.com/dir/file.txt',
  '//example.org/schema-relative/path',
  'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==',
  '' // Empty string for demonstration
];

console.log('Parsing various URI strings:');
uriStrings.forEach(uriStr => {
  try {
    const parser = new UriParser(uriStr);
    const result = parser.parse();
    if (result.success) {
      console.log(`\nURI: '${uriStr}'`);
      console.log('  Parse successful. Result:', JSON.stringify(result.ast, null, 2));
    } else {
      console.error(`\nURI: '${uriStr}'`);
      console.error('  Parse failed. Error:', result.error);
    }
  } catch (e) {
    console.error(`\nError parsing URI '${uriStr}':`, e.message);
  }
});