conifer
v1.0.0Conifer
A multi-format, file-based configuration library for Node. It streamlines reading and parsing configurations from JSON or CSON files, with support for adding your own file-type handlers.
This project is simple right now, but there are some fun features planned for a future release.
Basic Usage
You can use Conifer with JavaScript or CoffeeScript:
var conifer = require('conifer');
conifer = require 'conifer'
In the examples below, it's assumed that you've required Conifer as above.
conifer.parse
This function parses a config file asynchronously. It accepts two arguments – a file path and a callback function. The file path must be an unempty string and the callback should accept two arguments itself: the parsed config store, and an error object.
conifer.parse('example.json', function (store, err) {
if (err !== null) {
throw err;
}
// do something with `store`
});
In the callback, store
will be either a
conifer.Store
instance on success or null
.
err
will be null
on success, or an Error object on failure.
conifer.parseSync
This function parses a config file synchronously. It accepts
a single argument – a file path. The file path must be an
unempty string. This function returns a
conifer.Store
instance on success, and
throws if parsing fails.
store = conifer.parseSync('example.json');
conifer.Store
This is the class which is instantiated in parsing, and holds parsed configurations. The constructor for this class accepts a simple object of key/value pairs.
get method
The get method accepts a single argument, the name of the configuration to get, and returns the requested configuration (or undefined if it's not set).
var config = new conifer.Store({foo: 'bar'});
config.get('foo'); // bar
set method
The set method accepts a two arguments, the name of the configuration to set and the value to set it to.
var config = new conifer.Store({});
config.set('foo', 'bar');
config.get('foo'); // bar
Extending With File Handlers
Conifer can be extended to work with almost any configuration format. It's just a case of writing a file handler. The file handler API is extremely simple:
conifer.setFileHandler
This function adds a new file handler. It accepts two arguments – a file extension and a handler function. The handler function should accept a content string and return a successfully parsed object or throw an error.
conifer.setFileHandler('xml', function (fileContent) {
try {
return myMagicXmlLib.parse(fileContent);
} catch (error) {
throw error;
}
});
With the above code, any call to
conifer.parse
or
conifer.parseSync
with a file path that
has a .xml
extension will use the specified handler function
to parse the file content.
conifer.getFileHandler
This function gets a file handler that's been set already. This function accepts a single argument – the file extension to get the handler for, and returns the requested function.
conifer.getFileHandler('json'); // [Function]
conifer.removeFileHandler
This function removes a file handler that's been set already. This function accepts a single argument – the file extension to get the handler for.
conifer.removeFileHandler('json');
conifer.getFileHandler('json'); // undefined
Development
In order to develop Conifer, you'll need to install the following npm modules globally like so:
npm install -g coffee-script
npm install -g jake
And then install development dependencies locally with:
npm install
Once you have these dependencies, you will be able to run the following commands:
jake build
: Build JavaScript from the CoffeeScript source.
jake lint
: Run CoffeeLint on the CoffeeScript source.
jake test
: Run all unit tests.
License
Dual licensed under the MIT or GPL Version 2 licenses.