norris-json

NORRIS-JSON toolkit

The NORRIS-JSON toolkit is a JSON toolkit written for the NORRIS project, but it can be used independently since it does not have any dependencies (other than vows if you want to run the test cases).

Current Version:

0.2.0

Installation

npm install norris-json

Usage

load(path, callback(err, data))

Loads a JSON file from a path. NORRIS-JSON supports C-style comments in JSON files, which would be stripped off automatically during loading.

The callback (2nd arg) is called with two parameters: callback(err, data), where the first parameter (err) will be null if the operation is successful, or contains an error object if it failed. The second argument (data) contains the JSON object if the operation is successful.

Example

var njson = require('norris-json').make();	// don't forget to call make()!

njson.load('/path/to/json/file.json', function onRead(err, json) {
	console.log(json); // should show the json object
});

loadSync(path)

Asynchronous version of load().

Example

var njson = require('norris-json').make();	// don't forget to call make()!
var json  = njson.loadSync('/path/to/json/file.json');

attachToGlobal()

Attaches the API in njson into the global JSON object.

Example

var njson = require('norris-json').make(); 	// don't forget to call make()
njson.attachToGlobal();

// You can now use load(), loadSync(), etc with JSON
JSON.load('/path/to/json/file.json', function(err, data) { ... });

value(json, namespace [, default value])

A safe way of getting a nested value from a JSON object. First argument takes a JSON object, second argument takes a namespace strin (dot delimited, e.g. "foo.bar.subar"), and third argument (optional) is the default value if no value is found.

This is useful when you want to grab a deeply nested value in a json object but don't want an exception to be thrown whenever the value is not found (gracefully fail instead).

Example

var njson = require('norris-json').make();	// don't forget to call make()
var json  = njson.loadSync('/path/to/json/file.json');

/*
The json object looks like this:
	{
		foo : {
			bar : 'yeah!'
		}
	}
*/

var value 	= njson.value(json, 'foo.bar');		// returns 'yeah!'
var fail 	= njson.value(json, 'foo.nobar');	// returns null
var error	= json.foo.nobar;					// throws an exception!

Version History

v0.2.0

• Added value(), including test cases (value.test.js)
• Re-written bin/runtests to use step instead, since suite.run() is an async operation

v0.1.0

• Removed the function parse() because it's kind of useless

v0.0.2

• Added attachToGlobal(), including test cases (attach-to-global.test.js)
• Updated test runner

v0.0.1

• Added load(), including test cases (comments.test.js)
• Added loadSync(), including test cases (comments.test.js)
• Added test runner (bin/runtests)

Roadmap for v0.3.0

Improvements

• Add an alternate mixin object (instead of JSON) to attachToGlobal()
• Make load() and loadSync() capable of taking in an array of paths
• Make load() and loadSync() capable of using URIs instead of filepaths

New API

mixin(json1, json2)

Mixes in the properties of json2 into json1.

Example

var njson = require('norris-json').make(); 	// don't forget to call make()!

var json1 = njson.loadSync('/path/to/json/file1.json');
var json2 = njson.loadSync('/path/to/json/file2.json');

var res = njson.mixin(json1, json2);

MIT License

Copyright (C) 2011 by Ruben LZ Tan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.