Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 141 lines (101 sloc) 4.455 kB
54ec656 @zaach Fix emails and add README
zaach authored
1 Jison
2 =====
c7c69b9 @zaach Update README
zaach authored
3 * [issues](http://github.com/zaach/jison/issues)
7bfb8fe @zaach Fix mail link.
zaach authored
4 * [discuss](mailto:jison@librelist.com)
54ec656 @zaach Fix emails and add README
zaach authored
5
1292f10 @zaach Updated REAMDE.
zaach authored
6 An API for creating parsers in JavaScript
7 -----------------------------------------
8
9 Jison generates bottom-up parsers in JavaScript. Its API is similar to Bison's, hence the name. It supports many of Bison's major features, plus some of its own. If you are new to parser generators such as Bison, and Context-free Grammars in general, a [good introduction][1] is found in the Bison manual. If you already know Bison, Jison should be easy to pickup.
10
11 A brief warning before proceeding: **the API is ridiculously unstable** right now. The goal is to mirror Bison where it makes sense, but we're not even there yet. Also, optimization has not been a main focus as of yet.
54ec656 @zaach Fix emails and add README
zaach authored
12
13 Briefly, Jison takes a JSON encoded grammar specification and outputs a JavaScript file capable of parsing the language described by that grammar specification. You can then use the generated script to parse inputs and accept, reject, or perform actions based on the input.
14
1292f10 @zaach Updated REAMDE.
zaach authored
15 Installation
16 ------------
eaa3b63 @zaach Update docs
zaach authored
17 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/)
54ec656 @zaach Fix emails and add README
zaach authored
18
eaa3b63 @zaach Update docs
zaach authored
19 Using npm:
54ec656 @zaach Fix emails and add README
zaach authored
20
eaa3b63 @zaach Update docs
zaach authored
21 sudo npm install jison
22
23 Using tusk:
24
25 tusk install jison
54ec656 @zaach Fix emails and add README
zaach authored
26
1292f10 @zaach Updated REAMDE.
zaach authored
27 Usage from the command line
28 -----------------------
54ec656 @zaach Fix emails and add README
zaach authored
29
eaa3b63 @zaach Update docs
zaach authored
30 Clone the github repository for examples:
31
32 git clone git://github.com/zaach/jison.git
33 cd jison/examples
34
1292f10 @zaach Updated REAMDE.
zaach authored
35 Now you're ready to generate some parsers:
36
eaa3b63 @zaach Update docs
zaach authored
37 jison calculator.jison
1292f10 @zaach Updated REAMDE.
zaach authored
38
eaa3b63 @zaach Update docs
zaach authored
39 This will generate `calculator.js` in your current working directory. This file can be used to parse an input file, like so:
1292f10 @zaach Updated REAMDE.
zaach authored
40
41 echo "2^32 / 1024" > testcalc
eaa3b63 @zaach Update docs
zaach authored
42 node calculator.js testcalc
1292f10 @zaach Updated REAMDE.
zaach authored
43
44 This will print out `4194304`.
45
46 Usage from a CommonJS module
47 --------------------------
48
49 You can generate parsers programatically from JavaScript as well. Assuming Jison is in your commonjs environment's load path:
50
51 // mygenerator.js
52 var Parser = require("jison").Parser;
53
eaa3b63 @zaach Update docs
zaach authored
54 // a grammar in JSON
1292f10 @zaach Updated REAMDE.
zaach authored
55 var grammar = {
54ec656 @zaach Fix emails and add README
zaach authored
56 "lex": {
57 "rules": [
58 ["\\s+", "/* skip whitespace */"],
1292f10 @zaach Updated REAMDE.
zaach authored
59 ["[a-f0-9]+", "return 'HEX';"]
54ec656 @zaach Fix emails and add README
zaach authored
60 ]
61 },
62
63 "bnf": {
1292f10 @zaach Updated REAMDE.
zaach authored
64 "hex_strings" :[ "hex_strings HEX",
65 "HEX" ]
54ec656 @zaach Fix emails and add README
zaach authored
66 }
1292f10 @zaach Updated REAMDE.
zaach authored
67 };
68
69 var parser = new Parser(grammar);
70
71 // generate source, ready to be written to disk
72 var parserSource = parser.generate();
73
74 // you can also use the parser directly from memory
75
76 // returns true
77 parser.parse("adfe34bc e82a");
78
79 // throws lexical error
80 parser.parse("adfe34bc zxg");
81
54ec656 @zaach Fix emails and add README
zaach authored
82
eaa3b63 @zaach Update docs
zaach authored
83 More Documentation
1292f10 @zaach Updated REAMDE.
zaach authored
84 ------------------
eaa3b63 @zaach Update docs
zaach authored
85 For more information on creating grammars and using the generated parsers, read the [documentation](http://jison.org/docs).
1292f10 @zaach Updated REAMDE.
zaach authored
86
c7c69b9 @zaach Update README
zaach authored
87 Real world examples
1292f10 @zaach Updated REAMDE.
zaach authored
88 ------------------
89
c7c69b9 @zaach Update README
zaach authored
90 * [CoffeeScript](http://github.com/jashkenas/coffee-script) uses Jison in its self-compiler.
eaa3b63 @zaach Update docs
zaach authored
91 * [Orderly.js](http://github.com/zaach/orderly.js) uses Jison for compilation.
1292f10 @zaach Updated REAMDE.
zaach authored
92
93
94 Contributors
95 ------------
9705d76 @zaach Tweak readme
zaach authored
96 [Githubbers](http://github.com/zaach/jison/contributors)
97
98 Special thanks to Jarred Ligatti, Manuel E. Bermúdez
1292f10 @zaach Updated REAMDE.
zaach authored
99
100 License
101 -------
102
103 > Copyright (c) 2009 Zachary Carter
104 >
105 > Permission is hereby granted, free of
106 > charge, to any person obtaining a
107 > copy of this software and associated
108 > documentation files (the "Software"),
109 > to deal in the Software without
110 > restriction, including without
111 > limitation the rights to use, copy,
112 > modify, merge, publish, distribute,
113 > sublicense, and/or sell copies of the
114 > Software, and to permit persons to
115 > whom the Software is furnished to do
116 > so, subject to the following
117 > conditions:
118 >
119 > The above copyright notice and this
120 > permission notice shall be included
121 > in all copies or substantial portions
122 > of the Software.
123 >
124 > THE SOFTWARE IS PROVIDED "AS IS",
125 > WITHOUT WARRANTY OF ANY KIND, EXPRESS
126 > OR IMPLIED, INCLUDING BUT NOT LIMITED
127 > TO THE WARRANTIES OF MERCHANTABILITY,
128 > FITNESS FOR A PARTICULAR PURPOSE AND
129 > NONINFRINGEMENT. IN NO EVENT SHALL THE
130 > AUTHORS OR COPYRIGHT HOLDERS BE
131 > LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
132 > LIABILITY, WHETHER IN AN ACTION OF
133 > CONTRACT, TORT OR OTHERWISE, ARISING
134 > FROM, OUT OF OR IN CONNECTION WITH THE
135 > SOFTWARE OR THE USE OR OTHER DEALINGS
136 > IN THE SOFTWARE.
137
138
139 [1]: http://dinosaur.compilertools.net/bison/bison_4.html
eaa3b63 @zaach Update docs
zaach authored
140
Something went wrong with that request. Please try again.