or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

algorithm-selection.mdcli.mdgrammar-processing.mdindex.mdparser-creation.mdparser-generation.md
tile.json

tessl/npm-jison

A parser generator with Bison's API for creating bottom-up parsers from grammar definitions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jison@0.4.x

To install, run

npx @tessl/cli install tessl/npm-jison@0.4.0

index.mddocs/

Jison

Jison is a parser generator library for JavaScript that creates bottom-up parsers using an API similar to Bison. It takes JSON-encoded grammars or Bison-style grammar definitions and outputs JavaScript parsers capable of parsing languages described by those grammars. The library supports many of Bison's major features while adding its own enhancements, making it suitable for creating parsers programmatically or via command-line interface.

Package Information

  • Package Name: jison
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install jison or npm install jison -g for global CLI access

Core Imports

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

The main Jison object provides access to all functionality:

const jison = require("jison");

// Access parser constructor
const Parser = jison.Parser;

// Access generator factory
const Generator = jison.Generator;

// Access individual generator classes
const {
  LR0Generator,
  SLRGenerator, 
  LALRGenerator,
  LR1Generator,
  LLGenerator
} = jison;

For CLI functionality:

const cli = require("jison/lib/cli");

Basic Usage

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

// Define a simple grammar
const grammar = {
  "lex": {
    "rules": [
      ["\\s+", "/* skip whitespace */"],
      ["[0-9]+", "return 'NUMBER';"],
      ["\\+", "return '+';"],
      ["\\*", "return '*';"],
      ["\\(", "return '(';"],
      ["\\)", "return ')';"],
      ["$", "return 'EOF';"]
    ]
  },
  "bnf": {
    "expressions": [["e EOF", "return $1;"]],
    "e": [
      ["e + e", "$$ = $1 + $3;"],
      ["e * e", "$$ = $1 * $3;"],
      ["( e )", "$$ = $2;"],
      ["NUMBER", "$$ = Number(yytext);"]
    ]
  }
};

// Create parser
const parser = new Parser(grammar);

// Parse input
const result = parser.parse("2 + 3 * 4");
console.log(result); // 14

Architecture

Jison is built around several key components:

  • Parser Constructor: Main entry point for creating parsers from grammar definitions
  • Generator System: Factory pattern for creating different parser types (LR0, SLR, LALR, LR1, LL)
  • Grammar Processing: Internal classes for handling productions, nonterminals, and grammar analysis
  • Code Generation: System for generating standalone parser modules in various formats
  • CLI Interface: Command-line tool for generating parsers from grammar files
  • Utility Classes: Helper classes for object composition and set operations

Capabilities

Parser Creation

Core functionality for creating parsers from grammar definitions. Supports both JSON and Bison-style grammar formats with automatic algorithm selection.

/**
 * Create a parser from a grammar definition
 * @param grammar - Grammar definition (object or string)  
 * @param options - Parser generation options
 * @returns Parser instance with parse() method
 */
new jison.Parser(grammar, options);

/**
 * Factory function for creating parser generators
 * @param grammar - Grammar definition
 * @param options - Generation options including parser type
 * @returns Generator instance based on options.type
 */
new jison.Generator(grammar, options);

Parser Creation

Grammar Processing

Internal system for processing and analyzing grammar definitions including production rules, nonterminals, and operator precedence.

/**
 * Process a grammar definition into internal representation
 * @param grammar - Raw grammar object
 */
processGrammar(grammar);

/**
 * Build production rules from BNF grammar
 * @param bnf - BNF grammar object
 * @param productions - Production array to populate
 * @param nonterminals - Nonterminal symbols
 * @param symbols - All grammar symbols
 * @param operators - Operator precedence rules
 */
buildProductions(bnf, productions, nonterminals, symbols, operators);

Grammar Processing

Parser Generation

Code generation system that creates standalone parser modules in various formats (CommonJS, AMD, plain JavaScript) from processed grammars.

/**
 * Generate parser source code
 * @param options - Generation options
 * @returns Generated parser source code
 */
generate(options);

/**
 * Generate CommonJS module
 * @param options - Module generation options
 * @returns CommonJS module source
 */
generateCommonJSModule(options);

/**
 * Generate AMD module
 * @param options - AMD module options
 * @returns AMD module source
 */
generateAMDModule(options);

Parser Generation

Algorithm Selection

Support for multiple parsing algorithms including LR(0), SLR(1), LALR(1), LR(1), and LL(1) with automatic selection based on grammar complexity.

/**
 * LR(0) parser generator
 */
class LR0Generator extends Generator;

/**
 * SLR(1) parser generator  
 */
class SLRGenerator extends Generator;

/**
 * LALR(1) parser generator (default)
 */
class LALRGenerator extends Generator;

/**
 * Canonical LR(1) parser generator
 */
class LR1Generator extends Generator;

/**
 * LL(1) parser generator
 */
class LLGenerator extends Generator;

Algorithm Selection

Command Line Interface

CLI tool for generating parsers from grammar files with support for various output formats and parser algorithms.

/**
 * Main CLI entry point
 * @param opts - Command line options
 */
function main(opts);

/**
 * Generate parser string from grammar
 * @param opts - Generation options
 * @param grammar - Parsed grammar object
 * @returns Generated parser source
 */
function generateParserString(opts, grammar);

/**
 * Process grammar and lexer files
 * @param file - Grammar file content
 * @param lexFile - Lexer file content (optional)
 * @param jsonMode - Whether to parse as JSON
 * @returns Parsed grammar object
 */
function processGrammars(file, lexFile, jsonMode);

Command Line Interface

Types

/**
 * Main Jison module interface
 */
interface JisonModule {
  Parser: typeof Parser;
  Generator: typeof Generator;
  LR0Generator: typeof LR0Generator;
  SLRGenerator: typeof SLRGenerator;
  LALRGenerator: typeof LALRGenerator;
  LR1Generator: typeof LR1Generator;
  LLGenerator: typeof LLGenerator;
  version: string;
}

/**
 * Grammar definition object
 */
interface Grammar {
  lex?: LexicalGrammar;     // Lexical rules (optional)
  bnf?: BNFGrammar;         // BNF production rules
  ebnf?: EBNFGrammar;       // EBNF production rules (alternative to bnf)
  operators?: OperatorDef[]; // Operator precedence declarations
  tokens?: string[] | string; // Terminal symbols
  start?: string;           // Start symbol (optional)
  options?: ParserOptions;  // Parser generation options
}

/**
 * Lexical grammar definition
 */
interface LexicalGrammar {
  rules: LexRule[];         // Array of lexical rules
  options?: LexerOptions;   // Lexer options
}

/**
 * Lexical rule definition
 */
type LexRule = [string, string]; // [pattern, action]

/**
 * BNF grammar rules mapping nonterminals to productions
 */
interface BNFGrammar {
  [nonterminal: string]: string[] | string; // Productions as array or |-separated string
}

/**
 * EBNF grammar rules (alternative to BNF)
 */
interface EBNFGrammar {
  [nonterminal: string]: string[] | string; // EBNF productions
}

/**
 * Operator precedence and associativity declaration
 */
type OperatorDef = [string, ...string[]]; // [associativity, ...operators]

/**
 * Lexer options
 */
interface LexerOptions {
  ranges?: boolean;           // Include token range information
  flex?: boolean;             // Flex-like lexing behavior
  backtrack_lexer?: boolean;  // Backtracking lexer mode
}

/**
 * Parser generation options
 */
interface ParserOptions {
  type?: 'lr0' | 'slr' | 'lalr' | 'lr' | 'll'; // Parser algorithm
  moduleName?: string;      // Generated module name
  moduleType?: 'commonjs' | 'amd' | 'js'; // Module format
  debug?: boolean;          // Enable debug mode
}

/**
 * Generated parser interface
 */
interface GeneratedParser {
  parse(input: string): any; // Parse input string
  yy: object;               // Shared state object
  lexer?: Lexer;            // Associated lexer (if generated)
}

/**
 * Lexer interface for tokenization
 */
interface Lexer {
  setInput(input: string): void;    // Set input string
  lex(): string | number;           // Get next token
  EOF: number;                      // End-of-file token value
  yytext: string;                   // Current token text
  yylloc: object;                   // Current token location
}