Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update docs

  • Loading branch information...
commit eaa3b638af567de39ac1faa5b10b2f1215440c04 1 parent 1e1837b
@zaach zaach authored
Showing with 39 additions and 247 deletions.
  1. +3 −1 Makefile
  2. +20 −236 README.md
  3. +16 −10 web/content/docs.html
View
4 Makefile
@@ -3,10 +3,12 @@ all: web preview
web:
cd web/ && nanoc compile
+ cp -r ../examples output/jison/
preview:
cd web/ && nanoc view
deploy:
git clone git@github.com:zaach/jison.git /tmp/jison-gh-pages
- cd /tmp/jison-gh-pages && git checkout gh-pages
+ cd /tmp/jison-gh-pages && git checkout gh-pages && rm -r ./*
+ cd - && cp -r output/jison/* /tmp/jison-gh-pages/
View
256 README.md
@@ -14,24 +14,32 @@ Briefly, Jison takes a JSON encoded grammar specification and outputs a JavaScri
Installation
------------
-**Prerequisite**: To run Jison from the command line, you'll need to have [Narwhal][2] installed and available from your `PATH`.
+Jison can be installed for [Narwhal](http://github.com/280north/narwhal) using its bundled `tusk` command or for [Node](http://nodejs.org) using [`npm`](http://github.com/isaacs/npm/)
-Clone the github repository:
+Using npm:
- git clone git://github.com/zaach/jison.git
+ sudo npm install jison
+
+Using tusk:
+
+ tusk install jison
Usage from the command line
-----------------------
+Clone the github repository for examples:
+
+ git clone git://github.com/zaach/jison.git
+ cd jison/examples
+
Now you're ready to generate some parsers:
- cd jison
- narwhal bin/jison examples/calculator.jison
+ jison calculator.jison
-This will generate a `calculator.js` file in your current working directory. This file can be used to parse an input file, like so:
+This will generate `calculator.js` in your current working directory. This file can be used to parse an input file, like so:
echo "2^32 / 1024" > testcalc
- narwhal calculator.js testcalc
+ node calculator.js testcalc
This will print out `4194304`.
@@ -43,6 +51,7 @@ You can generate parsers programatically from JavaScript as well. Assuming Jison
// mygenerator.js
var Parser = require("jison").Parser;
+ // a grammar in JSON
var grammar = {
"lex": {
"rules": [
@@ -70,240 +79,16 @@ You can generate parsers programatically from JavaScript as well. Assuming Jison
// throws lexical error
parser.parse("adfe34bc zxg");
-Using the generated parser
---------------------------
-So, you have generated your parser through the command line or JavaScript API and have saved it to disk. Now it can be put to use.
-
-As demonstrated before, the parser can be used from the command line:
-
- narwhal calculator.js testcalc
-
-Though, more ideally, the parser will be a dependency of another module. You can require it from another module like so:
-
- // mymodule.js
- var parser = require("./calculator").parser;
-
- function exec (input) {
- return parser.parse(input);
- }
-
- var twenty = exec("4 * 5");
-
-Or more succinctly:
-
- // mymodule.js
- function exec (input) {
- return require("./calculator").parse(input);
- }
-
- var twenty = exec("4 * 5");
-
-Using the parser in a web page
-----------------------------
-
-The generated parser script may be included in a web page without any need for a CommonJS loading environment. It's as simple as pointing to it via a scipt tag:
-
- <script src="calc.js"></script>
-
-When you generate the parser, you can specify the variable name it will be declared as:
-
- // mygenerator.js
- var parserSource = generator.generate({moduleName: "calc"});
- // then write parserSource to a file called, say, calc.js
-
-Whatever `moduleName` you specified will be the the variable you can access the parser from in your web page:
-
- <!-- mypage.html -->
- ...
- <script src="calc.js"></script>
- <script>
- calc.parse("42 / 0");
- </script>
- ...
-
-The moduleName you specify can also include a namespace, e.g:
- // mygenerator.js
- var parserSource = parser.generate({moduleName: "myCalculator.parser"});
-
-And could be used like so:
-
- <!-- mypage.html -->
- ...
- <script>
- var myCalculator = {};
- </script>
- <script src="calc.js"></script>
- <script>
- myCalculator.parser.parse("42 / 0");
- </script>
- ...
-
-Or something like that -- you get the picture.
-
-A demo of the calculator script used in a web page is [here](http://zaach.github.com/jison/demo/calc.html) and the source of the page and the narwhal script to generate the parser are [here](http://gist.github.com/265842).
-
-Specifying a language
----------------------
-The process of parsing a language involves two phases: **lexical analysis** (tokenizing) and **parsing**, which the Lex/Yacc and Flex/Bison combinations are famous for. Jison lets you specify a parser much like you would using Bison/Flex, with separate files for tokenization rules and for the language grammar, or with the tokenization rules embedded in the main grammar.
-
-For example, here is the grammar for the calculator parser:
-
- /* description: Parses end executes mathematical expressions. */
-
- /* lexical grammar */
- %lex
-
- %%
- \s+ {/* skip whitespace */}
- [0-9]+("."[0-9]+)?\b {return 'NUMBER';}
- "*" {return '*';}
- "/" {return '/';}
- "-" {return '-';}
- "+" {return '+';}
- "^" {return '^';}
- "(" {return '(';}
- ")" {return ')';}
- "PI" {return 'PI';}
- "E" {return 'E';}
- <<EOF>> {return 'EOF';}
-
- /lex
-
- /* operator associations and precedence */
-
- %left '+' '-'
- %left '*' '/'
- %left '^'
- %left UMINUS
-
- %start expressions
-
- %% /* language grammar */
-
- expressions
- : e EOF
- {print($1); 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);}
- | '-' e %prec UMINUS
- {$$ = -$2;}
- | '(' e ')'
- {$$ = $2;}
- | NUMBER
- {$$ = Number(yytext);}
- | E
- {$$ = Math.E;}
- | PI
- {$$ = Math.PI;}
- ;
-
-
-which compiles down to this JSON representation used directly by Jison:
-
- {
- "lex": {
- "rules": [
- ["\\s+", "/* skip whitespace */"],
- ["[0-9]+(?:\\.[0-9]+)?\\b", "return 'NUMBER';"],
- ["\\*", "return '*';"],
- ["\\/", "return '/';"],
- ["-", "return '-';"],
- ["\\+", "return '+';"],
- ["\\^", "return '^';"],
- ["\\(", "return '(';"],
- ["\\)", "return ')';"],
- ["PI\\b", "return 'PI';"],
- ["E\\b", "return 'E';"],
- ["$", "return 'EOF';"]
- ]
- },
-
- "operators": [
- ["left", "+", "-"],
- ["left", "*", "/"],
- ["left", "^"],
- ["left", "UMINUS"]
- ],
-
- "bnf": {
- "expressions" :[[ "e EOF", "print($1); 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);" ],
- [ "- e", "$$ = -$2;", {"prec": "UMINUS"} ],
- [ "( e )", "$$ = $2;" ],
- [ "NUMBER", "$$ = Number(yytext);" ],
- [ "E", "$$ = Math.E;" ],
- [ "PI", "$$ = Math.PI;" ]]
- }
- }
-
-Jison accepts both the Bison/Flex style formats, or the raw JSON format, e.g:
-
- narwhal bin/jison examples/calculator.jison
-or
- narwhal bin/jison examples/calculator.json
-
-When the lexical grammar resides in its own (.jisonlex) file, use that as the second argument to Jison, e.g.:
- narwhal bin/jison examples/classy.jison examples/classy.jisonlex
-
-More examples can be found in the `examples/` and `tests/parser/` directories.
-
-Sharing scope
-------------
-In Bison, code is expected to be lexically defined within the scope of the semantic actions. E.g., chunks of code may be included in the generated parser source, which are available from semantic actions.
-
-Jison is more modular. Instead of pulling code into the generated module, the generated module is expected to be required and used by other modules. This means that if you want to expose functionality to the semantic actions, you can't rely on it being available through lexical scoping. Instead, the parser has a `yy` property which is exposed to actions as the `yy` free variable. Any functionality attached to this property is available in both lexical and semantic actions through the `yy` free variable.
-
-An example from orderly.js:
-
- var parser = require("./orderly/parse").parser;
-
- // set parser's shared scope
- parser.yy = require("./orderly/scope");
-
- // returns the JSON object
- var parse = exports.parse = function (input) {
- return parser.parse(input);
- };
- ...
-
-The `scope` module contains logic for building data structures, which is used within the semantic actions.
-
-*TODO: More on this.*
-
-Lexical Analysis
-----------------
-Jison includes a rather rudimentary lexer, though **any module that supports the basic lexer API could be used** in its place. Jison's lexer uses the `lex` key of the JSON grammar spec, where the rules for matching a token are defined along with the action to execute on a match. Usually, the action will return the token which is used by the Jison parser. A custom lexer could be used instead with it's own methods of tokenizing.
-
-*TODO: More on this.*
-
-Parsing algorithms
+More Documentation
------------------
-Like Bison, Jison can recognize languages described by LALR(1) grammars, though it also has modes for LR(0), SLR(1), and LR(1). It also has a special mode for generating LL(1) parse tables (requested by my professor,) and could be extended to generate a recursive descent parser for LL(k) languages in the future. But, for now, Jison is geared toward bottom-up parsing.
-
-**LR(1) mode is currently not practical for use with anything other than toy grammars, but that is entirely a consequence of the algorithm used, and may change in the future.*
+For more information on creating grammars and using the generated parsers, read the [documentation](http://jison.org/docs).
Real world examples
------------------
* [CoffeeScript](http://github.com/jashkenas/coffee-script) uses Jison in its self-compiler.
-* [Orderly.js][3] uses Jison for compilation.
+* [Orderly.js](http://github.com/zaach/orderly.js) uses Jison for compilation.
Contributors
@@ -352,5 +137,4 @@ License
[1]: http://dinosaur.compilertools.net/bison/bison_4.html
- [2]: http://github.com/280north/narwhal
- [3]: http://github.com/zaach/orderly.js
+
View
26 web/content/docs.html
@@ -4,9 +4,7 @@
Documentation
=============
-(I want to do some guides, too – not there yet.)
-
-Basically, Jison takes a context-free grammar as input and outputs a JavaScript file capable of parsing the language described by that grammar. You can then use the generated script to parse inputs and accept, reject, or perform actions based on the input. If you're familiar with Bison or Yacc, or other clones, you're almost ready to roll.
+Jison takes a context-free grammar as input and outputs a JavaScript file capable of parsing the language described by that grammar. You can then use the generated script to parse inputs and accept, reject, or perform actions based on the input. If you're familiar with Bison or Yacc, or other clones, you're almost ready to roll.
* [Installation](#installation)
* [Usage from the command line](#usage-from-the-command-line)
@@ -24,19 +22,27 @@
Installation
------------
-To run Jison from the *command line*, you'll need to have [Narwhal](http://github.com/280north/narwhal) installed and available from your `PATH`. To use it as a module, any CommonJS compatible environment should be fine.
+Jison can be installed for [Narwhal](http://github.com/280north/narwhal) using its bundled `tusk` command or for [Node](http://nodejs.org) using [`npm`](http://github.com/isaacs/npm/)
-Clone the github repository:
+Using npm:
- git clone git://github.com/zaach/jison.git
+ sudo npm install jison
+
+Using tusk:
+
+ tusk install jison
-Usage from the Command Line
+Usage from the command line
-----------------------
-Now, you're ready to generate some parsers:
+Clone the github repository for examples:
- cd jison
- narwhal bin/jison examples/calculator.jison
+ git clone git://github.com/zaach/jison.git
+ cd jison/examples
+
+Now you're ready to generate some parsers:
+
+ jison calculator.jison
This will generate `calculator.js` in your current working directory. This script can be used to parse an input file, like so:
Please sign in to comment.
Something went wrong with that request. Please try again.