{"id":10505,"library":"apg-lite","title":"APG Lite Parser","description":"apg-lite is a lightweight JavaScript parser for ABNF (Augmented Backus-Naur Form) grammars, supporting a simplified subset of SABNF operators. It functions strictly as a parser, requiring grammar objects to be pre-generated using `apg-js` (version 4.3.0 or higher) with its `--lite` option. Currently at version 1.0.5, it parses only JavaScript strings, a key distinction from `apg-js` which handles arbitrary arrays of positive integers. The library retains only User-Defined Terminals (UDT), positive look-ahead (AND), and negative look-ahead (NOT) operators from the SABNF superset. It offers simplified AST manipulation, parse tree tracing for debugging, and statistics collection for profiling, all encapsulated within a single ECMAScript Module (ESM) compatible JavaScript file. The package is actively maintained, with a release cadence driven by bug fixes and minor enhancements, as demonstrated by recent updates to its robust, dependency-free URI parser.","status":"active","version":"1.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/ldthomas/apg-lite","tags":["javascript","APG","parser","ABNF","SABNF"],"install":[{"cmd":"npm install apg-lite","lang":"bash","label":"npm"},{"cmd":"yarn add apg-lite","lang":"bash","label":"yarn"},{"cmd":"pnpm add apg-lite","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary parser module is ESM-only and typically exports a class or factory function like 'Parser'.","wrong":"const { Parser } = require('apg-lite/lib/parser')","symbol":"Parser","correct":"import { Parser } from 'apg-lite/lib/parser'"},{"note":"The specialized URI parser is a self-contained ESM module provided as an example, suitable for direct import.","wrong":"const { UriParser } = require('apg-lite/uri-app/UriParser')","symbol":"UriParser","correct":"import { UriParser } from 'apg-lite/uri-app/UriParser'"},{"note":"`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.","wrong":"import { Parser } from 'apg-lite/lib/web-parser'","symbol":"webParserScript","correct":"<script src=\"./node_modules/apg-lite/lib/web-parser.js\"></script>"}],"quickstart":{"code":"import { UriParser } from 'apg-lite/uri-app/UriParser';\n\nconst uriStrings = [\n  'http://user:pass@host:80/path?query#fragment',\n  'mailto:john.doe@example.com',\n  'ftp://ftp.example.com/dir/file.txt',\n  '//example.org/schema-relative/path',\n  'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==',\n  '' // Empty string for demonstration\n];\n\nconsole.log('Parsing various URI strings:');\nuriStrings.forEach(uriStr => {\n  try {\n    const parser = new UriParser(uriStr);\n    const result = parser.parse();\n    if (result.success) {\n      console.log(`\\nURI: '${uriStr}'`);\n      console.log('  Parse successful. Result:', JSON.stringify(result.ast, null, 2));\n    } else {\n      console.error(`\\nURI: '${uriStr}'`);\n      console.error('  Parse failed. Error:', result.error);\n    }\n  } catch (e) {\n    console.error(`\\nError parsing URI '${uriStr}':`, e.message);\n  }\n});\n","lang":"typescript","description":"Demonstrates how to import and use the self-contained UriParser to parse various URI strings, logging success or failure with the resulting AST."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<1.0.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to use CommonJS `require()` in an ECMAScript Module (ESM) context or a browser where `apg-lite` is loaded via standard script tags.","error":"ReferenceError: require is not defined"},{"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.","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`).","error":"SyntaxError: Cannot use import statement outside a module"},{"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()`.","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.","error":"TypeError: Parser is not a constructor"}],"ecosystem":"npm"}