{"id":12900,"library":"bnf-parser","title":"BNF Parser","description":"bnf-parser is a deterministic compiler/parser library for Backus-Naur Form (BNF) grammars, currently at version 4.1.3. It differentiates itself by compiling BNF definitions directly into WebAssembly modules, enabling high-performance parsing. This compilation process also generates TypeScript type definitions for the resulting Abstract Syntax Tree (AST), making it easier to work with parsed outputs in type-safe environments. The compiled WebAssembly artifacts are platform-agnostic, capable of running wherever `WebAssembly.Instance()` is supported, and are bundled into a single JavaScript file for easy integration with bundlers. The library primarily functions as a `devDependency`, with its `bnf-compile` CLI tool generating standalone parser artifacts that do not require `bnf-parser` as a runtime dependency. Releases appear to be frequent, with several patch versions addressing memory management, compatibility, and bug fixes since the major v4.0.0 release.","status":"active","version":"4.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/AjaniBilby/BNF-parser","tags":["javascript","ast","bnf","compile","parse","typescript","webpack ready","precompiled","webassembly"],"install":[{"cmd":"npm install bnf-parser","lang":"bash","label":"npm"},{"cmd":"yarn add bnf-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add bnf-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For parsers generated by `bnf-compile`, import the specific generated module. `bnf-parser` is ESM-only since v4.0.0, so CommonJS `require` will fail.","wrong":"const syntax = require('./bnf/your_syntax_name.js');","symbol":"Parser","correct":"import * as syntax from './bnf/your_syntax_name.js';"},{"note":"The generated parser exports a function named 'Parse_EntryPointName' where 'EntryPointName' is your BNF's root rule (e.g., 'Program').","symbol":"ParseFunction","correct":"import { Parse_Program } from './bnf/your_syntax_name.js';"},{"note":"Since v4.0.0, all previous APIs were moved under the `legacy` namespace. Direct import from `bnf-parser` will not expose the older API.","wrong":"import { Parse } from 'bnf-parser';","symbol":"Legacy API","correct":"import { Parse } from 'bnf-parser/legacy';"}],"quickstart":{"code":"import * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { execSync } from 'node:child_process';\n\n// 1. Define your BNF grammar\nconst bnfContent = `program ::= chunk+ ;\nchunk ::= \"a\"+ \"b\"+ ;`;\nconst bnfFilePath = path.join(process.cwd(), 'syntax.bnf');\nfs.writeFileSync(bnfFilePath, bnfContent);\n\n// 2. Compile the BNF to a WebAssembly parser using the CLI\n// This is typically run as a build step or dev script\ntry {\n  console.log('Compiling BNF...');\n  execSync(`npx bnf-compile ${bnfFilePath} --outDir ./bnf-output`, { stdio: 'inherit' });\n  console.log('Compilation successful!');\n} catch (error) {\n  console.error('BNF compilation failed:', error.message);\n  process.exit(1);\n}\n\n// 3. Import and use the generated parser\n// The path should match your --outDir and BNF file name\nimport('./bnf-output/syntax.js').then(syntax => {\n  const inputString = \"abbaabab\";\n  console.log(`Parsing input: \"${inputString}\"`);\n  const tree = syntax.Parse_Program(inputString).root;\n  \n  console.log('Parsed AST:', JSON.stringify(tree, null, 2));\n  \n  const firstChunk = tree.value[0];\n  if (firstChunk && firstChunk.type === 'Term_chunk') {\n    console.log(`Type of first chunk: ${firstChunk.type}`);\n    const firstBs = firstChunk.value[1]; // Assuming chunk is ['a+', 'b+']\n    if (firstBs && Array.isArray(firstBs.value)) {\n      const bCount = firstBs.value.length;\n      console.log(`Count of 'b's in the first 'b+' sequence: ${bCount}`);\n    }\n  }\n}).catch(error => {\n  console.error('Failed to import or use generated parser:', error);\n});\n","lang":"typescript","description":"This quickstart demonstrates how to compile a BNF grammar into a WebAssembly parser using the `bnf-compile` CLI tool and then import and utilize the generated TypeScript parser to process an input string and inspect its Abstract Syntax Tree (AST)."},"warnings":[{"fix":"Update imports to use `import { Symbol } from 'bnf-parser/legacy';` for older APIs. For new compilation-based workflows, use `npx bnf-compile` and import the generated ES module. Ensure your project is configured for ESM or use a bundler.","message":"Version 4.0.0 introduced significant breaking changes, including moving all previous APIs to a new `legacy` namespace and changing the package type to 'module', making it ESM-only. Existing `require()` statements or direct imports of older APIs will no longer work without modification.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to `bnf-parser@4.1.1` or newer. If issues persist with extremely large inputs, consider optimizing your BNF grammar to reduce complexity or segmenting inputs if feasible.","message":"Prior to version 4.1.1, the WebAssembly module could experience memory overgrowth, potentially leading to crashes or unexpected behavior, especially with long or complex input strings or grammars that involve extensive backtracking.","severity":"gotcha","affected_versions":"<4.1.1"},{"fix":"Install `bnf-parser` with `--save-dev`. Ensure your build process properly includes the `bnf-compile` step and that your runtime code only imports the generated parser files, not the `bnf-parser` library directly.","message":"The `bnf-parser` package is designed to be a `devDependency`. The primary workflow involves using its CLI (`bnf-compile`) to generate standalone parser artifacts. These generated artifacts do not require `bnf-parser` as a runtime dependency in your production bundles.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Upgrade to `bnf-parser@4.0.5` or newer to ensure correct handling of hexadecimal literals and robust CLI behavior.","message":"Early v4.x versions (pre-4.0.5) had issues with hexadecimal character encoding in literals (e.g., `\\x6b`) within BNF definitions and the `bnf-compile` CLI could crash when provided with invalid starting paths.","severity":"gotcha","affected_versions":"<4.0.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your import statements to use ES module syntax (e.g., `import * as syntax from './path/to/parser.js';`) and ensure your project's `package.json` is configured for ES modules (`\"type\": \"module\"`) or your bundler is correctly configured for ESM.","cause":"Attempting to import `bnf-parser` or its generated artifacts using CommonJS `require()` syntax in a module context after the package transitioned to ESM in v4.0.0.","error":"TypeError: require is not a function"},{"fix":"Upgrade `bnf-parser` to `4.1.1` or newer to benefit from memory usage fixes. Review your BNF grammar for potential infinite recursion or excessively complex rules. For very large inputs, consider processing them in smaller chunks if your grammar allows.","cause":"The WebAssembly parser attempted to allocate more memory than available, often due to extremely large input strings, highly recursive grammars, or a bug in older versions of the parser module.","error":"WebAssembly.RuntimeError: out of memory"},{"fix":"Upgrade to `bnf-parser@4.0.1` or newer, as this bug was addressed shortly after the v4.0.0 release.","cause":"A specific bug in `bnf-parser` v4.0.0 caused incorrect parsing or counting behavior when applying repetition operators directly to character ranges.","error":"Count not working when applied directly to a range (i.e. \"a\"->\"z\"+)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"bnf-compile"}