clonkrefiniparser

JavaScript INI Parser
=============

This library allows you to parse any valid INI file.
However, its main goal is to be able to parse any game reference
of the game Clonk (R) (see http://www.clonk.de), including the
main masterserver's output. Since the used format hasn't really
changed since Clonk Planet was released, it should be compatible
with any network-capable version of Clonk, including OpenClonk
and Clonk Rage.

It is implemented in pure JavaScript and bundled as a CommonJS-module,
but it can also be used in non-moduled environments like modern
ES5-browsers.

Example Usage
------------------

Parse an INI file in node.js and output the generated JSON to the console:

var refparse = require('clonkrefiniparser'),
fs = require('fs'),
fh = fs.createReadStream("input.ini", "r");

refparse.parseReferenceStream(fh, function(err, root){
// Root element contains the top-level sections
if(err){
console.warn("Error: " + err);
} else {
console.log("Data read: " + JSON.stringify(root));
}
});

Request an INI file in node.js over HTTP, parse it and output the generated JSON to the console:

var refparse = require('clonkrefiniparser'),
http = require('http');

// Request game information from the OpenClonk masterserver
http.get("http://boom.openclonk.org/server/", function(fh){
refparse.parseReferenceStream(fh, function(err, root){
// Root element contains the top-level sections
if(err){
console.warn("Error: " + err);
} else {
console.log("Data read: " + JSON.stringify(root));
}
});
});

Parse an INI file in the browser (assuming ref.js was previously loaded in a script-tag)
and output it using an alert-window:

var root = parseReferenceString("[OpenClonk]\nMOTD=OpenClonk released!");
alert(JSON.stringify(root));

Usage information
------------------

parseReferenceStream is the preferred method in a node.js-environment and can be used asynchronously. It uses
the data read from a provided ReadableStream, which is read line by line. This allows it to
process rather big files. The given callback is executed when the underlying stream casts the 'end'-event.

In case your parsed file is built up like a tree (used by Clonk), by default 2 spaces mean one level.
Note that the parser accepts multiple sections with the same names on one level. Because of this, the following
reference produces this output:

[Reference]
GameId=382
Title="Foo"

[Info]
Comment="Hello world"

[Reference]
GameId=394
Title="Bar"

Turns into:

{"Reference":
[
{ "GameId": 382,
"Title": "foo"
"Info": { "Comment": "Hello world" }
},
{ "GameId": 394,
"Title": "Bar"
}
]
}

Consult the node.js-documentation on its Stream-API for further information on the usage of parseReferenceStream.