ebnf

library0.1.0jsnpmunverified

The `ebnf` package provides a JavaScript and TypeScript-compatible library for generating Abstract Syntax Tree (AST) parsers from formal grammars defined in either Backus-Naur Form (BNF) or W3C Extended Backus-Naur Form (EBNF). It is currently at version 1.9.1. The library differentiates itself by offering direct AST generation, browser compatibility, and built-in TypeScript type definitions, making it suitable for both Node.js and client-side applications. Releases appear to be driven by bug fixes and minor improvements, without a strict time-based cadence. It's particularly useful for projects requiring custom language parsing or syntax highlighting, such as Domain Specific Languages (DSLs) or code analysis tools.

data

npm install ebnf

github ↗package ↗

INSTALL

IMPORT

SIG · EBNF

ebnf

datajavascriptv0.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Grammars

✓ import { Grammars } from 'ebnf';

✗ const Grammars = require('ebnf');

While CommonJS `require` might work in some environments (e.g., Webpack), ESM `import` is the idiomatic and recommended way to access `Grammars`.

Grammars.BNF.Parser

✓ import { Grammars } from 'ebnf'; const bnfParser = new Grammars.BNF.Parser(bnfGrammar);

✗ import { BNF } from 'ebnf'; // Incorrect path, BNF is nested

The Parser classes are nested under `Grammars.BNF` and `Grammars.W3C` respectively.

Grammars.W3C.Parser

✓ import { Grammars } from 'ebnf'; const w3cParser = new Grammars.W3C.Parser(w3cGrammar);

✗ import { W3CParser } from 'ebnf';

Ensure correct capitalization and nesting when accessing the W3C Parser class.

This quickstart demonstrates how to define a simple arithmetic grammar using BNF, create a parser instance, and then use it to generate an Abstract Syntax Tree (AST) for a given expression.

import { Grammars } from 'ebnf'; const mathGrammar = ` <Equation> ::= <BinaryOperation> | <Term> <Term> ::= "(" <RULE_WHITESPACE> <Equation> <RULE_WHITESPACE> ")" | "(" <RULE_WHITESPACE> <Number> <RULE_WHITESPACE> ")" | <RULE_WHITESPACE> <Number> <RULE_WHITESPACE> <BinaryOperation> ::= <Term> <RULE_WHITESPACE> <Operator> <RULE_WHITESPACE> <Term> <Number> ::= <RULE_NEGATIVE> <RULE_NON_ZERO> <RULE_NUMBER_LIST> | <RULE_NON_ZERO> <RULE_NUMBER_LIST> | <RULE_DIGIT> <Operator> ::= "+" | "-" | "*" | "/" | "^" <RULE_NUMBER_LIST> ::= <RULE_DIGIT> <RULE_NUMBER_LIST> | <RULE_DIGIT> <RULE_NEGATIVE> ::= "-" <RULE_NON_ZERO> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" <RULE_DIGIT> ::= "0" | <RULE_NON_ZERO> <RULE_WHITESPACE> ::= <RULE_WS> | "" <RULE_WS> ::= " " <RULE_WHITESPACE> | "\n" <RULE_WHITESPACE> | " " | "\n" `; // Create a BNF parser instance with the defined grammar const parser = new Grammars.BNF.Parser(mathGrammar); // Parse an arithmetic expression and get the Abstract Syntax Tree (AST) const ast = parser.getAST('(2 + (2 * -123)) * 5332'); console.log(JSON.stringify(ast, null, 2)); /* Expected AST structure (simplified representation): { "type": "Equation", "text": "(2 + (2 * -123)) * 5332", "children": [ // ... detailed AST nodes for operations and numbers ] } */

Debug

Known issues

gotchaVersion 1.9.1 included a fix to 'remove eval' from the internal implementation. While not explicitly marked as a breaking change for external API, prior versions might have used `eval` internally, which can carry security risks if not properly sandboxed, especially if user-supplied grammar definitions were possible.

fix

Upgrade to version 1.9.1 or later to mitigate potential security implications related to `eval` usage. Ensure all grammar definitions, especially those originating from untrusted sources, are thoroughly validated before being passed to the parser.

affects: <1.9.1

gotchaThe library differentiates between two EBNF styles: standard BNF and W3C EBNF (compatible with Railroad Diagram Generator). Grammars must adhere strictly to one of these two forms for correct parsing. Mixing notations or using unsupported EBNF extensions will lead to parsing errors.

fix

Explicitly choose either `Grammars.BNF.Parser` or `Grammars.W3C.Parser` and ensure your grammar strictly follows the conventions of the chosen format. Consult the respective specifications (BNF, W3C EBNF) for syntax details.

affects: >=1.0.0

gotchaBy default, rules defined with `ALL_UPPER_AND_SNAKE_CASE` in the grammar are not emitted in the resulting AST, simplifying the tree for common use cases like whitespace or comments. This behavior can be surprising if you expect all defined rules to appear in the AST.

fix

If you need `ALL_UPPER_AND_SNAKE_CASE` rules to be present in the AST, you can deactivate this default behavior by setting the `keepUpperRules: true` flag in the parser's options (if supported, verify against latest documentation/source). Otherwise, design your grammar to use different naming conventions for rules intended to be part of the AST.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'ebnf' or its corresponding type declarations.

The `ebnf` package is not installed, or the TypeScript compiler cannot locate its type definitions.

fix

Run `npm install ebnf` (or `yarn add ebnf`) to install the package. If using TypeScript, ensure `tsconfig.json` correctly includes `node_modules/@types` or that the package's bundled types are being picked up.

TypeError: Cannot read properties of undefined (reading 'Parser')

This usually occurs when trying to access `Grammars.BNF.Parser` or `Grammars.W3C.Parser` but `Grammars` itself is undefined or incorrectly imported.

fix

Verify that `import { Grammars } from 'ebnf';` is used correctly and that the package is installed. If using CommonJS, ensure `const { Grammars } = require('ebnf');` is being used, though ESM imports are preferred.

Error: Invalid grammar, production 'SomeRule' is not defined.

A non-terminal rule referenced in the grammar (e.g., `<SomeRule>`) does not have a corresponding definition in the provided grammar string.

fix

Review your EBNF/BNF grammar string and ensure all referenced non-terminal rules are explicitly defined. Check for typos in rule names.

Error: Line X, column Y: Unexpected token 'Z'.

The parser encountered a token (character or sequence) in the input string that does not match any expected rule at that position according to the grammar.

fix

Inspect the input string at the specified line and column. Compare it against your grammar definition to identify which rule is failing to match. This often points to incorrect grammar syntax, missing terminals, or an input string that doesn't conform to the defined language. Consider simplifying the grammar or the input to isolate the issue.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/menduz/node-ebnf ↗

packagehttps://www.npmjs.com/package/ebnf ↗