Figson
Simple configuration storage.
Note: This project is in early development, and versioning is a little different. Read this for more details.
Why should you care?
This project is in very early development, but already makes working with JSON, CSON and YAML configuration files a lot easier.
Installation
$ npm install figson --save
Usage
Async Example
var figson = ;var path = ; figson;
Sync Example
var figson = ;var path = ; try var config = figson; config; config; catch error throw error;
You can swap out config.json
for config.cson
, config.yaml
or config.yml
.
Everything will still work, and uses the exact same API as described below.
Figson API
Figson itself exposes one method:
figson.parse(config_file, [callback]);
Asynchronously reads a configuration file (if there is a callback function), parses it,
and exposes an error
and a config
object to the callback (function(error, config) {}
).
config_file
is the path to the file. Omit the callback for a synchronous operation.
Config API
The config
object is basically just a tiny wrapper around the data inside
the configuration file. It exposes a few properties and methods. All of config
's methods
are chainable, and accessing a property with a config
method uses a tiny
DSL string similar to how you would access that property using JavaScript's dot
notation.
config.data
An object representing the configuration file.
config.val()
Returns the value of the last key/property in the config
chain.
config.get([key])
Retrieves the value of the given key
. If no key is provided, it retrieves
the value of the last known key in the chain.
key
is a string containing the object property who's value you want to retrieve.
Example:
// { some: { property: 'value1' }}config // => value1// orconfig // => value1
config.set([key], value)
Sets the key
to the value
. If no key
is given, uses the most recent key
in the chain. The value
can be a string, number, object, array or null.
Example:
// { an: { array: { property: [] }}}config // { an: { array: { property: ['the value'] }}}// orconfig // { an: { array: { property: ['a different value'] }}}
config.update([key], value)
First, attempts a get()
to determine the existence of the given key
property. If it
exists, it will then call set()
with the new value
. Otherwise, throws an error.
Useful if you need to safely set a value. If no key
is given, updates the
key
from the last call in the chain.
Example:
configconfig
config.destroy([key])
"deletes" the given key
property by setting it's value to undefined
. If no
key is given, it will "delete" the key from the last method in the chain.
Example:
config;config
config.find(partial_key)
This method is useful for accessing properties that are very deeply nested. Suppose you have an object:
a: very: deeply: nested: property: 'value'
You want to update a.very.deeply.nested.property
to have the value foobar
,
but you don't want to have to type out the whole property name. Just use .find()
!
As long as the property ends with the key you pass to find()
, it'll work:
config // done!
config.save([callback])
This saves the current state of config.data
to the configuration file. This is a synchronous
operation, but passing in an optional callback (function(error) {}
) will make it
perform asynchronously.
Example:
config; // synchronous // asynchronousconfig;
Adding your own configuration file types
Figson exposes a small interface for you to add your own configuration file handlers, if you wish to use a separate data format. Figson uses this interface internally to add support for JSON, CSON and YAML files.
All you have to do is call figson.addHandler(name, object)
, where name
is
the name of your handler (e.g. "CSON" for CSON files) and where object
is
a JavaScript object that lists file extensions as well as synchronous and
asynchronous parse and stringify operations. For example, if you wanted to
register JSON, you would do this:
figson;
Figson will automatically register the file extension to the correct data format. You can look in lib/handlers for other examples.
Contributing:
Please read the contribution guidelines.