Jison Parser Generator

0.4.18 verified Thu Apr 23 auth: no javascript abandoned

Jison is a JavaScript parser generator that creates bottom-up parsers from user-defined grammars. It supports grammars defined in either a JSON format or a Bison-style syntax, outputting a standalone JavaScript file capable of parsing the specified language. The API is intentionally designed to be similar to Bison's, making it approachable for developers familiar with traditional parser generators like Yacc or Bison. As of its latest release, 0.4.18, published in 2014, the project appears to be largely unmaintained. It generates parsers that can be used as command-line tools or programmatically within a CommonJS environment. Its primary differentiator is providing a Bison-like grammar definition and parser generation workflow targeting JavaScript.

Common errors

error ReferenceError: require is not defined ↓

cause Attempting to use `require()` in an ES Module context or using `import` for a CommonJS-only package.

fix

Ensure your file is treated as CommonJS (e.g., .js file without "type": "module" in package.json, or specifically use a CJS environment). If you must use Jison in an ESM context, consider a dynamic import: const { Parser } = await import('jison');.

error jison: command not found ↓

cause The `jison` command-line interface (CLI) is not installed globally or is not in your system's PATH.

fix

Install jison globally: npm install -g jison. If already installed, ensure your PATH environment variable includes the npm global bin directory.

error Error: Parse error on line X: [...] Unexpected 'TOKEN' ↓

cause The input string does not conform to the grammar defined for the parser, or there's an ambiguity/error in the grammar itself.

fix

Review your input string against the grammar rules. If the input is valid according to your intent, debug your grammar definition for ambiguities, missing rules, or incorrect token definitions. Use Jison's debug mode (jison -t) for more detailed parser output.

Warnings

breaking Jison version 0.4.18 was released in 2014 and is no longer actively maintained. It may have compatibility issues with modern Node.js versions, security vulnerabilities, or unaddressed bugs. Use with caution in new projects. ↓

fix Consider alternative, actively maintained parser generator libraries for JavaScript (e.g., Nearley, PEG.js) for new development. For existing projects, thoroughly test compatibility and consider vendoring a patched version.

gotcha Jison is a CommonJS-only package. It cannot be imported directly using ES module `import` syntax in modern JavaScript environments. Attempting to do so will result in `ReferenceError: require is not defined` or similar import errors. ↓

fix Always use `const Parser = require('jison').Parser;` syntax. If your project is pure ESM, you may need to use a wrapper or a dynamic `import()` call if `jison` is the only CJS dependency.

gotcha The documentation and examples primarily use Bison-style or JSON-encoded grammars. While powerful, understanding context-free grammars and LALR/SLR parsing algorithms is essential for effective use and debugging of Jison-generated parsers. ↓

fix Familiarize yourself with the concepts of parser generators and context-free grammars. Refer to the official Jison documentation or the Bison manual for fundamental understanding before writing complex grammars.

Install

npm install jison

yarn add jison

pnpm add jison

Imports

Parser
wrong
```
import { Parser } from 'jison';
```
correct
```
const Parser = require('jison').Parser;
```
Jison 0.4.18 is a CommonJS module and does not support ES module `import` syntax. Attempting to use `import` will result in a runtime error.
jison CLI
wrong
```
node jison mygrammar.jison
```
correct
```
jison mygrammar.jison
```
The `jison` executable is typically installed globally via `npm install -g jison` and run directly from the command line. It's not intended to be executed directly with `node`.
Whole module
wrong
```
import jison from 'jison';
```
correct
```
const jison = require('jison');
```
This imports the entire Jison module object, which contains the `Parser` class and other internal utilities. Primarily used for programmatic generation.

Quickstart

This quickstart demonstrates how to programmatically define a grammar, instantiate a Jison parser, and use it to parse an arithmetic expression, including error handling.

const Parser = require("jison").Parser;

// A basic calculator grammar in JSON format
const grammar = {
    "lex": {
        "rules": [
           ["\s+", "/* skip whitespace */"],
           ["([0-9]+(\.[0-9]+)?)\b", "return 'NUMBER';"],
           ["\*", "return '*';"],
           ["/", "return '/';"],
           ["-", "return '-';"],
           ["\+", "return '+';"],
           ["\^", "return '^';"],
           ["\(", "return '(';"],
           ["\)", "return ')';"],
           ["$$", "return 'EOF';"]
        ]
    },

    "bnf": {
        "expressions" :[
            ["e EOF", "return $1;" ]
        ],
        "e" :[
            ["e + e", "$$ = $1 + $3;"],
            ["e - e", "$$ = $1 - $3;"],
            ["e * e", "$$ = $1 * $3;"],
            ["e / e", "$$ = $1 / $3;"],
            ["e ^ e", "$$ = Math.pow($1, $3);"],
            ["-
            ", "$$ = -$2;"],
            ["(
            )", "$$ = $2;"],
            ["NUMBER", "$$ = Number($1);"]
        ]
    }
};

const parser = new Parser(grammar);

// Parse a simple arithmetic expression
const result = parser.parse("2 + 3 * (4 - 1)");
console.log(`Parsed result: ${result}`); // Expected: 11

try {
    parser.parse("2 + 3 $ 5"); // Should throw a lexical error
} catch (e) {
    console.error(`Error parsing invalid input: ${e.message}`);
}

// Demonstrate generation (optional, usually written to file)
const parserSource = parser.generate();
// console.log(parserSource.substring(0, 200) + '...'); // Output first 200 chars of generated parser source