From 9488291ac058a8ceef8a0268be3440ba55ef7d47 Mon Sep 17 00:00:00 2001 From: David Majda Date: Fri, 9 Apr 2010 18:29:43 +0200 Subject: [PATCH] Converted README to GitHub Flavored Markdown. Also added ".txt" extension to VERSION and LICENSE for more consistency. --- LICENSE => LICENSE.txt | 0 README | 86 ------------------------------------------ README.md | 64 +++++++++++++++++++++++++++++++ VERSION => VERSION.txt | 0 4 files changed, 64 insertions(+), 86 deletions(-) rename LICENSE => LICENSE.txt (100%) delete mode 100644 README create mode 100644 README.md rename VERSION => VERSION.txt (100%) diff --git a/LICENSE b/LICENSE.txt similarity index 100% rename from LICENSE rename to LICENSE.txt diff --git a/README b/README deleted file mode 100644 index 3319830..0000000 --- a/README +++ /dev/null @@ -1,86 +0,0 @@ -PEG.js: Parser Generator for JavaScript -======================================= -http://pegjs.majda.cz/ - -PEG.js is a parser generator for JavaScript based on the parsing expression -grammar [1] formalism. It is designed to be used either from your browser or -from the command line (using Rhino [2] JavaScript interpreter). - -Requirements ------------- -Both the parser generator and generated parsers should run well in IE8 and -recent versions of Firefox, Chrome, Safari and Opera, as well as Rhino -JavaScript engine. IE6 and IE7 are not supported. - - Note: IE7 might be supported sometime in the future, IE6 probably not. - -Usage ------ -To use PEG.js, you need to generate a parser from your grammar and then use the -generated parser in your project. - -Generating a Parser -~~~~~~~~~~~~~~~~~~~ -A parser can be generated either online [3] in your browser or using the command -line. Let's look at the second option. You need to follow these steps: - - 1. Install Java. This is necessary to run Rhino [2] (which is bundled with - PEG.js). - - 2. Generate the parser using bin/pegjs script on Unix or bin/pegjs.bat batch - file on Windows. - -For example, to generate a parser from an example grammar in the -examples/arithmetics.pegjs file on Unix, run: - - $ bin/pegjs arithmeticsParser examples/arithmetics.pegjs - -This command will create the parser in the examples/arithmetics.js file and will -make it available in the "arithmeticsParser" global variable. - -The bin/pegjs command has several options that influence the generator--to learn -more about them, use the --help option. - - Note: In the future, I will probably use Narwhal for the command-line version. - -Using the Generated Parser -~~~~~~~~~~~~~~~~~~~~~~~~~~ -Let's assume that you want to use the parser in a web page. To do this, you need -to: - - 1. Download the minified parser runtime [4] and include it into your page: - - - - 2. Include the generated parser into your page: - - - - - This creates a variable with the parser object in the global scope (you can - choose name of the variable when generating the parser). - - 3. Use the parser, i.e. call the parse method on the parser variable: - - - - The "parse" method of the generated parser will return either the result of - the parsing (dependent on the actions you specified in the grammar) or - throw PEG.Parser.SyntaxError exception if the input contains a syntax - error. The exception has properties "message", "line" and "column", which - contain details about the error. - -Grammar -------- -For detailed description of the grammar see the online documentation [5]. - -References ----------- -[1] http://en.wikipedia.org/wiki/Parsing_expression_grammar -[2] http://www.mozilla.org/rhino/ -[3] http://pegjs.majda.cz/online -[4] http://pegjs.majda.cz/download#minified-parser-runtime -[5] http://pegjs.majda.cz/documentation#grammar diff --git a/README.md b/README.md new file mode 100644 index 0000000..b40ddce --- /dev/null +++ b/README.md @@ -0,0 +1,64 @@ +PEG.js: Parser Generator for JavaScript +======================================= + + + +PEG.js is a parser generator for JavaScript based on the [parsing expression grammar](http://en.wikipedia.org/wiki/Parsing_expression_grammar) formalism. It is designed to be used either from your browser or from the command line (using [Rhino](http://www.mozilla.org/rhino/) JavaScript interpreter). + +Requirements +------------ + +Both the parser generator and generated parsers should run well in IE8 and recent versions of Firefox, Chrome, Safari and Opera, as well as Rhino JavaScript engine. IE6 and IE7 are not supported. + +**Note:** IE7 might be supported sometime in the future, IE6 probably not. + +Usage +----- + +To use PEG.js, you need to generate a parser from your grammar and then use the generated parser in your project. + +### Generating a Parser + +A parser can be generated either [online](http://pegjs.majda.cz/online) in your browser or using the command line. Let's look at the second option. You need to follow these steps: + + 1. Install Java. This is necessary to run [Rhino](http://www.mozilla.org/rhino/) (which is bundled with PEG.js). + + 2. Generate the parser using `bin/pegjs` script on Unix or `bin/pegjs.bat` batch file on Windows. + +For example, to generate a parser from an example grammar in the `examples/arithmetics.pegjs` file on Unix, run: + + $ bin/pegjs arithmeticsParser examples/arithmetics.pegjs + +This command will create the parser in the `examples/arithmetics.js` file and will make it available in the `arithmeticsParser` global variable. + +The `bin/pegjs` command has several options that influence the generator—to learn more about them, use the `--help` option. + +**Note:** In the future, I will probably use [Narwhal](http://narwhaljs.org/) for the command-line version. + +### Using the Generated Parser + +Let's assume that you want to use the parser in a web page. To do this, you need to: + + 1. Download the [minified parser runtime](http://pegjs.majda.cz/download#minified-parser-runtime) and include it into your page: + + + + 2. Include the generated parser into your page: + + + + + This creates a variable with the parser object in the global scope (you can choose name of the variable when generating the parser). + + 3. Use the parser, i.e. call the `parse` method on the parser variable: + + + + The `parse` method of the generated parser will return either the result of the parsing (dependent on the actions you specified in the grammar) or throw `PEG.Parser.SyntaxError` exception if the input contains a syntax error. The exception has properties `message`, `line` and `column`, which contain details about the error. + +Grammar +------- +For detailed description of the grammar see the [online documentation](http://pegjs.majda.cz/documentation#grammar). diff --git a/VERSION b/VERSION.txt similarity index 100% rename from VERSION rename to VERSION.txt