/script-kiddie/002_script_kiddie/script-kiddie/node_modules/config-chain/readme.markdown |
@@ -0,0 +1,237 @@ |
#config-chain |
|
USE THIS MODULE TO LOAD ALL YOUR CONFIGURATIONS |
|
## NOTE: Feature Freeze |
|
[![locked](http://badges.github.io/stability-badges/dist/locked.svg)](http://github.com/badges/stability-badges) |
|
This module is frozen. |
|
In general, I'd recommend using [rc](https://github.com/dominictarr/rc) instead, |
but as [npm](https://github.com/npmjs/npm) depends on this, it cannot be changed. |
|
``` js |
|
//npm install config-chain |
|
var cc = require('config-chain') |
, opts = require('optimist').argv //ALWAYS USE OPTIMIST FOR COMMAND LINE OPTIONS. |
, env = opts.env || process.env.YOUR_APP_ENV || 'dev' //SET YOUR ENV LIKE THIS. |
|
// EACH ARG TO CONFIGURATOR IS LOADED INTO CONFIGURATION CHAIN |
// EARLIER ITEMS OVERIDE LATER ITEMS |
// PUTS COMMAND LINE OPTS FIRST, AND DEFAULTS LAST! |
|
//strings are interpereted as filenames. |
//will be loaded synchronously |
|
var conf = |
cc( |
//OVERRIDE SETTINGS WITH COMMAND LINE OPTS |
opts, |
|
//ENV VARS IF PREFIXED WITH 'myApp_' |
|
cc.env('myApp_'), //myApp_foo = 'like this' |
|
//FILE NAMED BY ENV |
path.join(__dirname, 'config.' + env + '.json'), |
|
//IF `env` is PRODUCTION |
env === 'prod' |
? path.join(__dirname, 'special.json') //load a special file |
: null //NULL IS IGNORED! |
|
//SUBDIR FOR ENV CONFIG |
path.join(__dirname, 'config', env, 'config.json'), |
|
//SEARCH PARENT DIRECTORIES FROM CURRENT DIR FOR FILE |
cc.find('config.json'), |
|
//PUT DEFAULTS LAST |
{ |
host: 'localhost' |
port: 8000 |
}) |
|
var host = conf.get('host') |
|
// or |
|
var host = conf.store.host |
|
``` |
|
FINALLY, EASY FLEXIBLE CONFIGURATIONS! |
|
##see also: [proto-list](https://github.com/isaacs/proto-list/) |
|
WHATS THAT YOU SAY? |
|
YOU WANT A "CLASS" SO THAT YOU CAN DO CRAYCRAY JQUERY CRAPS? |
|
EXTEND WITH YOUR OWN FUNCTIONALTY!? |
|
## CONFIGCHAIN LIVES TO SERVE ONLY YOU! |
|
```javascript |
var cc = require('config-chain') |
|
// all the stuff you did before |
var config = cc({ |
some: 'object' |
}, |
cc.find('config.json'), |
cc.env('myApp_') |
) |
// CONFIGS AS A SERVICE, aka "CaaS", aka EVERY DEVOPS DREAM OMG! |
.addUrl('http://configurator:1234/my-configs') |
// ASYNC FTW! |
.addFile('/path/to/file.json') |
|
// OBJECTS ARE OK TOO, they're SYNC but they still ORDER RIGHT |
// BECAUSE PROMISES ARE USED BUT NO, NOT *THOSE* PROMISES, JUST |
// ACTUAL PROMISES LIKE YOU MAKE TO YOUR MOM, KEPT OUT OF LOVE |
.add({ another: 'object' }) |
|
// DIE A THOUSAND DEATHS IF THIS EVER HAPPENS!! |
.on('error', function (er) { |
// IF ONLY THERE WAS SOMETHIGN HARDER THAN THROW |
// MY SORROW COULD BE ADEQUATELY EXPRESSED. /o\ |
throw er |
}) |
|
// THROW A PARTY IN YOUR FACE WHEN ITS ALL LOADED!! |
.on('load', function (config) { |
console.awesome('HOLY SHIT!') |
}) |
``` |
|
# BORING API DOCS |
|
## cc(...args) |
|
MAKE A CHAIN AND ADD ALL THE ARGS. |
|
If the arg is a STRING, then it shall be a JSON FILENAME. |
|
SYNC I/O! |
|
RETURN THE CHAIN! |
|
## cc.json(...args) |
|
Join the args INTO A JSON FILENAME! |
|
SYNC I/O! |
|
## cc.find(relativePath) |
|
SEEK the RELATIVE PATH by climbing the TREE OF DIRECTORIES. |
|
RETURN THE FOUND PATH! |
|
SYNC I/O! |
|
## cc.parse(content, file, type) |
|
Parse the content string, and guess the type from either the |
specified type or the filename. |
|
RETURN THE RESULTING OBJECT! |
|
NO I/O! |
|
## cc.env(prefix, env=process.env) |
|
Get all the keys on the provided env object (or process.env) which are |
prefixed by the specified prefix, and put the values on a new object. |
|
RETURN THE RESULTING OBJECT! |
|
NO I/O! |
|
## cc.ConfigChain() |
|
The ConfigChain class for CRAY CRAY JQUERY STYLE METHOD CHAINING! |
|
One of these is returned by the main exported function, as well. |
|
It inherits (prototypically) from |
[ProtoList](https://github.com/isaacs/proto-list/), and also inherits |
(parasitically) from |
[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter) |
|
It has all the methods from both, and except where noted, they are |
unchanged. |
|
### LET IT BE KNOWN THAT chain IS AN INSTANCE OF ConfigChain. |
|
## chain.sources |
|
A list of all the places where it got stuff. The keys are the names |
passed to addFile or addUrl etc, and the value is an object with some |
info about the data source. |
|
## chain.addFile(filename, type, [name=filename]) |
|
Filename is the name of the file. Name is an arbitrary string to be |
used later if you desire. Type is either 'ini' or 'json', and will |
try to guess intelligently if omitted. |
|
Loaded files can be saved later. |
|
## chain.addUrl(url, type, [name=url]) |
|
Same as the filename thing, but with a url. |
|
Can't be saved later. |
|
## chain.addEnv(prefix, env, [name='env']) |
|
Add all the keys from the env object that start with the prefix. |
|
## chain.addString(data, file, type, [name]) |
|
Parse the string and add it to the set. (Mainly used internally.) |
|
## chain.add(object, [name]) |
|
Add the object to the set. |
|
## chain.root {Object} |
|
The root from which all the other config objects in the set descend |
prototypically. |
|
Put your defaults here. |
|
## chain.set(key, value, name) |
|
Set the key to the value on the named config object. If name is |
unset, then set it on the first config object in the set. (That is, |
the one with the highest priority, which was added first.) |
|
## chain.get(key, [name]) |
|
Get the key from the named config object explicitly, or from the |
resolved configs if not specified. |
|
## chain.save(name, type) |
|
Write the named config object back to its origin. |
|
Currently only supported for env and file config types. |
|
For files, encode the data according to the type. |
|
## chain.on('save', function () {}) |
|
When one or more files are saved, emits `save` event when they're all |
saved. |
|
## chain.on('load', function (chain) {}) |
|
When the config chain has loaded all the specified files and urls and |
such, the 'load' event fires. |