/jscc

JS/CC LALR(1) Parser Generator: A LALR(1) Parser Generator for JavaScript written in JavaScript

Primary LanguageJavaScriptOtherNOASSERTION

Build Status Build Status codecov npm

JS/CC LALR(1) Parser Generator
Copyright © 2007-2016 by Phorward Software Technologies; Jan Max Meyer; Brobston Development, Inc.; and other contributors
http://jscc.brobston.com ++ contact<>phorward-software<>com

INTRODUCTION

JS/CC is the first available parser development system for JavaScript and ECMAScript-derivates. It has been developed, both, with the intention of building a productive compiler development system and with the intention of creating an easy-to-use academic environment for people interested in how parse table generation is done generally in bottom-up parsing.

JS/CC brings a lex/yacc-like toolchain into the world of ECMAScript.

LICENSE

JS/CC is initially written by Jan Max Meyer (Phorward Software Technologies) with contributions by Louis P. Santillan and Sergiy Shatunov. Work to migrate JS/CC to GitHub, add modularity, and package for npm and Bower was done by Andrew Brobston. JS/CC is released under the terms and conditions of the 3-clause BSD license.

REQUIREMENTS

To use JS/CC, you need either Mozilla/Rhino, Node.js, Nashorn, or an ordinary ECMAScript compatible web browser! Versions through 0.37.0 supported Mozilla/Spidermonkey, Google V8, and Microsoft JScript. If resumed support for these platforms is desired, pull requests are welcome.

The build system uses Gulp. Google's Closure Compiler is used for verifying and minifying the code for the various platforms. Code contributions should ensure that all tests pass (using the Mocha framework, with the TDD code style and Chai assertion library) and that there are no Closure Compiler warnings or errors.

The npm package is named jscc-parser, as jscc was already taken.

ABOUT

JS/CC is a platform-independent software that unions both: A regular expression-based lexical analyzer generator matching individual tokens from the input character stream and a LALR(1) parser generator, computing the parse tables for a given context-free grammar specification to build a stand-alone, working parser. The context-free grammar fed to JS/CC is defined in a Backus-Naur-Form-based meta language, and allows the insertion of individual semantic code to be evaluated on a rule's reduction. JS/CC itself has been entirely written in JavaScript so it can be executed in many different ways: as platform-independent, browser-based JavaScript embedded on a Website, as as a Mozilla/Rhino or Java Nashorn interpreted application, or a Node shell script on Windows, *nix, Linux and Mac OSX. However, for productive execution, it is recommended to use the command-line versions. These versions are capable of assembling a complete compiler from a JS/CC parser specification, which is then stored to a .js JavaScript source file.

To use JS/CC and for understanding its internals and behavior, some knowledge of context-free grammars, bottom-up parsing techniques and compiler construction theory, in general, is assumed.

BUILDING

  1. Ensure that you have Node.js and npm. See https://docs.npmjs.com/getting-started/installing-node for details. Building and testing JS/CC most recently used Node versions 4.4.7 and 6.3.1, but other versions will likely work also.
  2. Ensure that you have Gulp version 3.x. See https://github.com/gulpjs/gulp/blob/master/docs/getting-started.md. Gulp version 4.x may work but has not been tested.
  3. Ensure that Java 8 or later is installed and that the JAVA_HOME environment variable points to the correct path of this installation. Builds and tests have been done with Oracle's distribution of Java 8. OpenJDK 8 may work but has not been tested.
  4. From the root project directory, run npm update.
  5. To run the default build target, simply run gulp. The default build target downloads some additional dependencies, generates documentation, and builds for the four platforms currently supported. To run Mocha tests, first build with gulp, then run gulp test. For other targets, see gulpfile.js.

USE

JS/CC can be used as a JavaScript module or with one of the command-line runners.

As a Module

After var jscc = require("jscc-parser") or equivalent, call the jscc function with an object containing options:

Option Type Default Description
out_file string Empty string, meaning to print to standard output or the engine's equivalent The path of the output file.
src_file string Empty string, meaning to read from standard input or the engine's equivalent. The path of the input grammar file.
tpl_file string A default template file for generic compilation tasks. The path of the input template file.
input string or function None If a string, the contents of the input grammar. If a function, a function that returns the contents of the grammar. When input is specified, src_file is ignored.
template string or function None If a string, the contents of the template. If a function with no arguments, a function that returns the contents of the template. When template is specified, tpl_file is ignored.
outputCallback function(string) None A function with a parameter that will be called with the output. When outputCallback is specified, out_file is ignored.
dump_nfa boolean false Whether to output the nondeterministic finite automata for debugging purposes.
dump_dfa boolean false Whether to output the deterministic finite automata for debugging purposes.
verbose boolean false Makes output slightly chattier. Will probably be deprecated in favor of using only logLevel at some point.
logLevel string or member of the jscc.enums.LOG_LEVEL enumeration (FATAL, ERROR, WARN, INFO, DEBUG, TRACE) WARN The logging level.
throwIfErrors boolean false Whether to throw an exception before completion of the main method if there are any compilation errors.
exitIfErrors boolean false Whether to exit the process with a non-zero exit code if there are any errors, provided that the platform permits doing so. Intended for use with shell scripts.

From the Command Line

After building JS/CC, the bin directory should contain shell scripts for both *nix and Windows. There are scripts for each platform. For example, to run using the Nashorn engine on Linux:

./bin/jscc-nashorn.sh --src_file "./path/to/src" --out_file "./path/to/output" --logLevel INFO

The throwIfErrors and exitIfErrors options are not supported from the command line because each runner sets those options according to its needs.

GRAMMAR FILES

See the online documentation for information on the grammar file syntax that JS/CC requires.