README

WebIDLParser.js is, shockingly enough, a Javascript parser for WebIDL (http://dev.w3.org/2006/webapi/WebIDL/).

All the content of this repository is distributed under the MIT License.

In order to use it in a Web context, simply include web/WebIDLParser.js. Note that this file has not been
minified and is quite large. I tested reducing its size here, and easily got it down to 44K minified and
6.4K gzipped (being generated, it is rather repetitive code). A "WebIDLParser" object will become available.

Using it from Node.js or a CommonJS environment is equally simple: just put node/WebIDLParser.js in your
library path and require it. It exports a "Parser" object.

The interface is simple: the only method you need to worry about is parse(str, [start]). It takes a string containing
WebIDL, and returns an AST expressed as a simple JS structure (utilities to traverse it more easily are
forthcoming). Optionally a second argument can specify which rule of the grammar to start with. This is useful
when parsing a small WebIDL fragment that may be incomplete. The names of the rules can be found in lib/grammar.peg.
Just so that you don't have to look, the most common start parameters are:

	- definitions (the default)
	- interface
	- Operation
	- Attribute
	- type
	- implements
	- typedef
	- exception

The grammar isn't exactly the one in the WebIDL draft. In some places it is slightly more permissive (not
by that much though), and its handling of extended attributes is simpler. It also adds support for WebIDL
arrays, even though they are not described in the current draft's grammar.

The parser code is created with the pegjs parser generator from the
grammar in lib/grammar.peg. To modify the grammar:

        - read up on PEG.js at http://pegjs.majda.cz/
        - install node and npm
        - install pegjs with npm install -g pegjs
        - run 'make parsers' in the top-level directory. (This assumes
          that you're in a Unix-like environment with make and sed installed.)