Oboe.js

Oboe.js aims to be fluid like a SAX parser but with the convenience of a DOM parser.

Choosing a parser

DOM pros:

• It is very simple. Everybody knows how to use it.
• The parsing is fast and native using JSON.parse

DOM cons:

• You can’t do anything until you have the whole document.
• If the connection drops while transferring you lose everything.
• Perpetual documents are not possible.

SAX pros:

• It has lean memory requirements. It can handle documents larger than the available RAM.

SAX cons:

• The API is very low level. Simple tasks need quite a lot of programming.

Oboe.js pros:

• Finding nodes is pattern-based. Unlike SAX, you don’t have to maintain state on what you have already seen in order to drill down into a JSON document.
• Oboe’s parser provides actual JS objects which can then be used much as you would with a DOM parser. In comparison, with SAX you must programmatically infer objects from many callbacks.
• Can be used to search the JSON while streaming is flowing.

Oboe.js cons:

• Since it builds up the parsed result as actual JSON objects parsing a document takes about the same memory as a DOM parser.

Code comparison: SAX

We have JSON containing an array of people objects and we wish to extract the name of the first person. Using SAX this is quite involved:

function extractNameOfFirstPerson(){
 var parser = clarinet.parser(),
 // With a SAX parser it is the developer's responsibility 
 // to track where in the document the cursor currently is.
 // Several variables are required to maintain this state. 
 inPeopleArray = false, 
 inPersonObject = false,
 inNameAttribute = false,
 found = false;
 parser.onopenarray = function(){
 // For brevity we'll cheat by assuming there is only one
 // array in the document. In practice this would be overly
 // brittle. 
 inPeopleArray = true; 
 };
 parser.onclosearray = function(){
 inPeopleArray = false;
 }; 
 parser.onopenobject = function(){
 inPersonObject = inPeopleArray; 
 };
 parser.oncloseobject = function(){
 inPersonObject = false;
 }; 
 parser.onkey = function(key){
 inNameAttribute = (inPeopleObject && key == 'name');
 };
 parser.onvalue = function(value){
 if( !found && inNameAttribute ) {
 // finally!
 console.log('the name is', value); 
 found = true;
 }
 }; 
 // return the parser to be hooked up to a stream
 return parser; 
}

Code comparison: Oboe.js

Oboe makes extracting the name very much easier, but reacts equally quickly to the streamed input as the SAX example above:

oboe('people.json')
 .node('[0].name', function(name){
 console.log('the name is', name);
 });

Improve this page

Is this page clear enough? Typo-free? Could you improve it?

Please fork the Oboe.js website repo and make a pull request. The markdown source is here.