etc

node-etc
========

Configuration loader for node.js applications.


Idea
----
Your application probably needs to load configuration from multiple sources and
make them available as one object. Etc is here to help!

Etc provides a fairly complete API for loading configuration from a
variety of sources, however, its been engineered to easily load config from
(in order of precedence): argv, environment, files in ./etc, package.json, and
defaults. Etc. also supports a simple plugin system so new file parsers or other
sources of configuration can be handled.

Examples
--------
#### Easy Mode
``js
var conf = require('etc')().all().toJSON();
`

#### Easy Mode done manually
`js
var etc = require('etc')();

etc
.argv()
.env()
.etc()
.pkg();

var conf = etc.toJSON();
`

#### Load configuration from argv, env, a file, and defaults.
`js
var etc = require('etc')();

etc.argv();
etc.env();
etc.file('/path/to/you/file/config.json');
etc.add({
my: 'defaults'
});

var conf = etc.toJSON();
`

#### Load configuration from /etc/myapp/*
`js
var etc = require('etc')();
etc.folder('/etc/myapp');
var conf = etc.toJSON();
`

#### Work with configuration using deliminated keys
`js
var etc = require('etc')();

etc.add({
host: 'localhost',
port: 3000,
meta: {
title: 'Cool title'
}
});

console.log(etc.get('meta:title'));
// Cool title

etc.set('meta:description', 'This is a really cool app');

console.log(etc.get('meta'));
// { title: 'Cool title',
// description: 'This is a really cool app' }
`

API
---


$3


Etc exports a factory function the creates instances of Etc objects. You can
optionally specify the key delimiter to use (defaults to : )

$3

Fetch a value from the configuration stack. Keys can be simple strings or
deliminated strings such as db:host, which will dive into the configuration
to grab a nested value.

$3

Set a new configuration value. Primitives will override exsting values
whereas Objects and Arrays will merge. The key can be a simple string or a
deliminated string. (Chainable)

$3

Set a configuration value, overriding whatever was there. The key can be a
simple string or a deliminated string. (Chainable)

$3

Clear the configuration stored under a given key. The key can be a simple string
or a deliminated string. (Chainable)

$3

Returns all of the configuration, deep-merged into a single object.

$3

Attach an etc plugin. See more below. (Chainable)

$3

Alias for etc.argv().env().etc().pkg() (Chainable)

$3

Parses argv using optimist
and adds it to the configuration. (Chainable)

$3

Adds any environment variables that start with the prefix
(defaults to 'app_') to the configuration. The prefix is stripped from the key.
(Chainable)

$3

Add configuration from an object literal. (Chainable)

$3

Add configuration from a file. A suitable parser must be registered
in etc.parsers ('.json' and '.js' supported by default). If named is true
then the extension will be stripped from the filename and the contents will
be added nested under that name.

For example, if your filename is /path/to/conf/db.json, then the configuration
will be added like:

`
{
"db": { [contents of db.json ] }
}

`
(Chainable)

$3


Loops through the files in dir and adds them to the configuration.
All files will be added with named=true (see etc.file()), except for one
special case when the filename is config.*. (Chainable)

$3

Try to find the local package.json for the consumer of etc and
look for an etc key in it. If it exists then add the contents to the
configuration.

Example:
`
{
"name": "etc-example",
"description": "Etc example",
"main": "example.js",
"dependencies": {
"etc": "*"
},
"etc": {
"db": {
"host": "localhost",
"port": 3000
}
}
}
`
(Chainable)

$3


Look for [app root]/etc (based on location of package.json) and
load it using etc.folder(). (Chainable)

$3

By default, each call to etc that adds more configuration pushes it on the
bottom of the stack. If you wish to unshift conf onto the top of the stack
instead you can call etc.reverse() followed by any other etc commands.
Until you call etc.reverse() again all subsequent etc methods will continue
to unshift.

Plugins
-------
Etc supports a simple plugin system, primarily useful for adding new file
parsers. Plugins should implement an attach method like so:

`js
exports.attach = function(options) {
options = options || {};

// Plugin will be attached with the scope set to an etc instance.
var etc = this;

etc.parsers['xml'] = xmlparser;
}

function xmlparser(filePath) {
// Parse the file and return an object literal.
}
`

$3


Support for YAML configuration files can be added via etc-yaml.
`js
var etc = require('etc'),
path = require('path'),
conf = etc();

conf.use(require('etc-yaml'));

// Load a yaml file.
conf.file(path.join(__dirname, 'config.yaml'));

// Print the config.
console.log(conf.toJSON());
``

$3

Maybe eventually if I need it :) (or make it yourself).

Credits
-------
Inspired by dominictarr/rc and
dominictarr/config-chain, but
with deep-merging and less trolling in the README :)

Developed by Terra Eclipse
--------------------------------------------------------
Terra Eclipse, Inc. is a nationally recognized political technology and
strategy firm located in Aptos, CA and Washington, D.C.

http://www.terraeclipse.com

License: MIT
------------
Copyright (C) 2015 Terra Eclipse, Inc.

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.