jaxon/README.md

Jaxon is a sequential access, event-driven JSON parser developed specifically to deal with streams.

# What is Jaxon?

Jaxon is a sequential access, event-driven JSON parser written specifically to deal
with streams.

Sounds pretty techy, right... but what exactly does it mean? 

There was a time, many long years ago, when systems were engineered to exchange
information using an archaic and verbose interchange format known as XML. Lots of
really smart guys with gray beards debated the best way to parse and work with
XML - some thought [DOM](https://en.wikipedia.org/wiki/Document_Object_Model  "DOM") 
was the ultimate answer, while others followed a different, darker path known as 
[SAX](https://en.wikipedia.org/wiki/Simple_API_for_XML "SAX").

DOM became ubiquitous due to adoption by web browsers, but SAX parsers are actually 
a pretty nifty piece of kit. They treat XML as a stream of tokens that can be sequentially 
parsed and evaluated, reporting events to observers as tags are encountered.

So why can't we do the same thing with JSON? Well, now we can!

# But why?

Firstly, because it's bad ass. 

Imagine a world where you don't have to wait for I/O to complete before you can start
working with data.

Imagine a world where you can hook into events generated by the parser as keys are 
encountered and evaluated. 

Secondly, it's really easy. Using Jaxon to parse the contents of a large JSON response
as it's streamed via HTTP can be achieved using code like the following:

```javascript
var jaxon = require('jaxon');
jaxon.factory().parse('http://awesomeservice.com/hello-world', {}, function(err) {
   console.log(err);
});
```

Parsing JSON streams from files on disk is just as easy:

```javascript
var jaxon = require('jaxon');
jaxon.factory().parse('file:///tmp/myfile.json', {}, function(err) {
   console.log(err);
});
```

If you want to subscribe to be notified whenever a key named *foo* is encountered in
the stream just add the following code:

```javascript
jaxon.factory().on('parse', 'foo', function(err, data) {
   // do something awesome
}).parse('file:///tmp/myfile.json');
```

If you're feeling capricious and want to do fuzzy matching on key names you can use
regular expressions: 

```javascript
jaxon.factory().on('match', /^(foo|bar)$/, function(err, data) {
   // mind. blown.
}).parse('file:///tmp/myfile.json');
```

Jaxon is generally pretty tolerant of poorly formed JSON and will keep parsing even if you
feed it garbage. If you want to receive errors generated during parsing (as they occur) 
you can do something like this:

```javascript
jaxon.factory().on('error', function(err) {
   // handle the error... like a boss
}).parse('file:///tmp/myfile.json');
```

Bringing it all together:

```javascript
jaxon.factory()
.on('parse', 'guid', function(o) { process.stdout.write(o + '\n'); })
.parse('http://f0e43e0449ff85b5a83a-8d88610b03123726d01e576fafeaf9d4.r60.cf2.rackcdn.com/test3.json');
```

# Other stuff.

Jaxon is very much a work in progress and I'm likely to introduce breaking changes
between releases as I come up with more weird and wonderful features. Your mileage
may vary.

## License and whatnot

Copyright (c) 2013, Dan Eyles (dan [at] irlgaming [dot] com)
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
   * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
   * Neither the name of IRL Gaming nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
 
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL IRL Gaming BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.