Rewrite README.md based on recent changes.

Refs #26
Refs #27

Author: nwronski

Gruntfile.js

@@ -360,13 +360,13 @@ module.exports = function(grunt) {
   grunt.registerTask('default', [
     'dist'
   ]);
-  // Create new build in .tmp/ folder
+  // Create new build of the parser in .tmp/ folder
   grunt.registerTask('build', [
     'clean:build',
     'shell:build',
     'babel:build'
   ]);
-  // Create new lib folder
+  // Create new lib/ folder containing the release version of the parser
   grunt.registerTask('dist', [
     'demobuild',
     'clean:release',
@@ -404,7 +404,7 @@ module.exports = function(grunt) {
   ]);
   // Build the parser to .tmp/ and run tests, but take the output from the
   // parser use it to overwrite the existing test JSON files in test/json/
-  grunt.registerTask('rewrite-json', [
+  grunt.registerTask('rewritejson', [
     'build', 'shell:rewrite'
   ]);
   // Rebuild the interactive demo site to .tmp/

README.md

@@ -5,9 +5,12 @@
 [![devDependencies Status Image](https://img.shields.io/david/dev/codeschool/sqlite-parser.svg)](https://github.com/codeschool/sqlite-parser/)
 [![License Type Image](https://img.shields.io/github/license/codeschool/sqlite-parser.svg)](https://github.com/codeschool/sqlite-parser/blob/master/LICENSE)
 
-This library parses SQLite queries, using JavaScript, and generates
-_abstract syntax tree_ (AST) representations of the input strings. A
-syntax error is produced if an AST cannot be generated.
+This JavaScript library parses SQLite queries to generate
+_abstract syntax tree_ (AST) representations of the parsed statements.
+
+Try out the
+[interactive demo]((http://codeschool.github.io/sqlite-parser/demo/))
+to see it in action.
 
 **This parser is written against the [SQLite 3 spec](https://www.sqlite.org/lang.html).**
 
@@ -17,25 +20,22 @@ syntax error is produced if an AST cannot be generated.
 npm install sqlite-parser
 ```
 
-### Beta Version Available
+### Install as a global module
 
-If you want the latest and greatest, install the _beta_ version of the parser (currently [v1.0.0-beta](https://github.com/codeschool/sqlite-parser/releases/tag/v1.0.0-beta)) with loads of new features and fixes.
+Use the command-line interface of the parser by installing it as a global module.
+The `sqlite-parser` command is then available to use to parse input SQL files and
+write the results to stdout or a JSON file. Additional usage
+instructions and options available through `sqlite-parser --help`.
 
 ```
-npm install sqlite-parser@beta
+npm i -g sqlite-parser
 ```
 
-## Demo
-
-There is an interactive demo of the parser hosted
-[at this location](http://codeschool.github.io/sqlite-parser/demo/). You
-can run a copy of the demo on your local machine by cloning this repository
-and then using the command `grunt live`.
-
-## Usage
+## Basic Usage
 
-The library exposes a function that accepts two arguments: a string
-containing SQL to parse and a callback function.
+The library exposes a function that accepts two arguments: a string containing
+SQL to parse and a callback function. If an AST cannot be generated from the
+input string then a descriptive error is generated.
 
 If invoked without a callback function the parser will runs synchronously and
 return the resulting AST or throw an error if one occurs.
@@ -50,14 +50,14 @@ console.log(ast);
 // async
 sqliteParser(query, function (err, ast) {
   if (err) {
-    console.log(err);
+    console.error(err);
     return;
   }
   console.log(ast);
 });
 ```
 
-### Use parser on Node streams *experimental*
+## Use parser on Node streams *(experimental)*
 
 This library also includes *experimental* support as a
 [stream transform](https://nodejs.org/api/stream.html) that can accept a
@@ -76,7 +76,7 @@ readStream.pipe(parserTransform);
 parserTransform.pipe(process.stdout);
 
 parserTransform.on('error', function (err) {
-  console.log(err);
+  console.error(err);
   process.exit(1);
 });
 
@@ -85,9 +85,9 @@ parserTransform.on('finish', function () {
 });
 ```
 
-_Note:_ To pipe the output into a file that contains a single valid JSON
-structure, the output of the parser steam transform needs to be wrapped in
-statement list node where every statement is separated by a comma.
+To pipe the output into a file that contains a single valid JSON structure, the
+output of the parser steam transform needs to be wrapped in statement list node
+where every statement is separated by a comma.
 
 ``` javascript
 var fs = require('fs');
@@ -102,7 +102,7 @@ parserTransform.pipe(singleNodeTransform);
 singleNodeTransform.pipe(writeStream);
 
 parserTransform.on('error', function (err) {
-  console.log(err);
+  console.error(err);
   process.exit(1);
 });
 
@@ -111,28 +111,22 @@ writeStream.on('finish', function () {
 });
 ```
 
-## Syntax Errors
-
-This parser will try to create _smart_ error messages when it cannot parse
-some input SQL. In addition to an approximate location for the syntax error,
-the parser will attempt to describe the area of concern
-(e.g.: `Syntax error found near Column Identifier (WHERE Clause)`).
-
 ## AST
 
-**NOTE: The SQLite AST is a work-in-progress and subject to change.**
+The AST is stable as of release `1.0.0`. However, if changes need to be made to
+improve consistency between node types, they will be explicitly listed in the
+[CHANGELOG](https://github.com/codeschool/sqlite-parser/blob/master/CHANGELOG.md).
 
 ### Example
 
 You can provide one or more SQL statements at a time. The resulting AST object
-has, at the highest level, a `statement` key that consists of an array containing
-the parsed statements.
+has, at the highest level, a statement list node that contains an array of
+statements.
 
 #### Input SQL
 
 ``` sql
 SELECT
- MIN(honey) AS "Min Honey",
  MAX(honey) AS "Max Honey"
 FROM
  BeeHive
@@ -149,26 +143,6 @@ FROM
       "type": "statement",
       "variant": "select",
       "result": [
-        {
-          "type": "function",
-          "name": {
-            "type": "identifier",
-            "variant": "function",
-            "name": "min"
-          },
-          "args": {
-            "type": "expression",
-            "variant": "list",
-            "expression": [
-              {
-                "type": "identifier",
-                "variant": "column",
-                "name": "honey"
-              }
-            ]
-          },
-          "alias": "Min Honey"
-        },
         {
           "type": "function",
           "name": {
@@ -200,82 +174,14 @@ FROM
 }
 ```
 
-## Contributing
-
-Once the dependencies are installed, start development with the following command:
-
-```
-grunt test-watch
-```
+## Syntax Errors
 
-which will automatically compile the parser and run the tests in
-`test/core/**/*-spec.js` each time a change is made to the tests and/or
-the source code.
-
-Optionally, run `grunt debug` to get AST output from each test in addition to
-live reloading.
-
-Finally, you should run `grunt release` before creating any PR. **Do not** change
-the version number in `package.json` inside of the pull request.
-
-### Writing tests
-
-Each test refers to a SQL input file in `test/sql/` and an expected output
-JSON AST file.
-
-For example a `describe()` block with the title `parent block` that contains an
-`it()` block named `super test 2` will look for the SQL input at
-`test/sql/parent-block/super-test-2.sql` and the JSON AST at
-`test/json/parent-block/super-test-2.json`.
-
-There are three options for the test helpers exposed by `tree`:
-- Assert that the test file successfully generates _any_ valid AST
-  ``` javascript
-  tree.ok(this, done);
-  ```
-
-- Assert that the test file generates an AST that exactly matches the expected output JSON file
-  ``` javascript
-  tree.equals(this, done);
-  ```
-
-- `tree.error()` to assert that a test throws an error
-  - Assert a specific error `message` for the thrown error
-    ``` javascript
-    tree.error('My error message.', this, done);
-    ```
-  - Assert an object of properties that all exist in the thrown error object
-    ``` javascript
-    tree.error({
-      message: 'You forgot to add a boop to the beep.',
-      location: {
-        start: { offset: 0, line: 1, column: 1 },
-        end: { offset: 0, line: 1, column: 1 }
-      }
-    }, this, done)
-    ```
+This parser will try to create *descriptive* error messages when it cannot parse
+some input SQL. In addition to an approximate location for the syntax error,
+the parser will attempt to describe the area of concern
+(e.g.: `Syntax error found near Column Identifier (WHERE Clause)`).
 
-``` javascript
-/* All the helper functions in `/test/helpers.js` are already available
- * and do not need to be explicitly imported.
- */
-describe('select', function () {
-  /* Test SQL: test/sql/select/basic-select.sql
-   * Expected JSON AST: test/json/select/basic-select.json
-   */
-  it('basic select', function (done) {
-    tree.equals(this, done);
-  });
-});
+## Contributing
 
-describe('parse errors', function (done) {
-  /* Test SQL: test/sql/parse-errors/parse-error-1.sql
-   * Expected JSON AST: test/json/parse-errors/parse-error-1.json
-   */
-  it('parse error 1', function(done) {
-    tree.error({
-      'message': 'Syntax error found near Column Identifier (WHERE Clause)'
-    }, this, done);
-  });
-});
-```
+Contributions are welcome! You can get started by checking out the
+[contributing guidelines](https://github.com/codeschool/sqlite-parser/blob/master/CHANGELOG.md).