corrade-nucleus-nucleons – Blame information for rev 20

Subversion Repositories:
Rev:
Rev Author Line No. Line
20 office 1 #config-chain
2  
3 USE THIS MODULE TO LOAD ALL YOUR CONFIGURATIONS
4  
5 ## NOTE: Feature Freeze
6  
7 [![locked](http://badges.github.io/stability-badges/dist/locked.svg)](http://github.com/badges/stability-badges)
8  
9 This module is frozen.
10  
11 In general, I'd recommend using [rc](https://github.com/dominictarr/rc) instead,
12 but as [npm](https://github.com/npmjs/npm) depends on this, it cannot be changed.
13  
14 ``` js
15  
16 //npm install config-chain
17  
18 var cc = require('config-chain')
19 , opts = require('optimist').argv //ALWAYS USE OPTIMIST FOR COMMAND LINE OPTIONS.
20 , env = opts.env || process.env.YOUR_APP_ENV || 'dev' //SET YOUR ENV LIKE THIS.
21  
22 // EACH ARG TO CONFIGURATOR IS LOADED INTO CONFIGURATION CHAIN
23 // EARLIER ITEMS OVERIDE LATER ITEMS
24 // PUTS COMMAND LINE OPTS FIRST, AND DEFAULTS LAST!
25  
26 //strings are interpereted as filenames.
27 //will be loaded synchronously
28  
29 var conf =
30 cc(
31 //OVERRIDE SETTINGS WITH COMMAND LINE OPTS
32 opts,
33  
34 //ENV VARS IF PREFIXED WITH 'myApp_'
35  
36 cc.env('myApp_'), //myApp_foo = 'like this'
37  
38 //FILE NAMED BY ENV
39 path.join(__dirname, 'config.' + env + '.json'),
40  
41 //IF `env` is PRODUCTION
42 env === 'prod'
43 ? path.join(__dirname, 'special.json') //load a special file
44 : null //NULL IS IGNORED!
45  
46 //SUBDIR FOR ENV CONFIG
47 path.join(__dirname, 'config', env, 'config.json'),
48  
49 //SEARCH PARENT DIRECTORIES FROM CURRENT DIR FOR FILE
50 cc.find('config.json'),
51  
52 //PUT DEFAULTS LAST
53 {
54 host: 'localhost'
55 port: 8000
56 })
57  
58 var host = conf.get('host')
59  
60 // or
61  
62 var host = conf.store.host
63  
64 ```
65  
66 FINALLY, EASY FLEXIBLE CONFIGURATIONS!
67  
68 ##see also: [proto-list](https://github.com/isaacs/proto-list/)
69  
70 WHATS THAT YOU SAY?
71  
72 YOU WANT A "CLASS" SO THAT YOU CAN DO CRAYCRAY JQUERY CRAPS?
73  
74 EXTEND WITH YOUR OWN FUNCTIONALTY!?
75  
76 ## CONFIGCHAIN LIVES TO SERVE ONLY YOU!
77  
78 ```javascript
79 var cc = require('config-chain')
80  
81 // all the stuff you did before
82 var config = cc({
83 some: 'object'
84 },
85 cc.find('config.json'),
86 cc.env('myApp_')
87 )
88 // CONFIGS AS A SERVICE, aka "CaaS", aka EVERY DEVOPS DREAM OMG!
89 .addUrl('http://configurator:1234/my-configs')
90 // ASYNC FTW!
91 .addFile('/path/to/file.json')
92  
93 // OBJECTS ARE OK TOO, they're SYNC but they still ORDER RIGHT
94 // BECAUSE PROMISES ARE USED BUT NO, NOT *THOSE* PROMISES, JUST
95 // ACTUAL PROMISES LIKE YOU MAKE TO YOUR MOM, KEPT OUT OF LOVE
96 .add({ another: 'object' })
97  
98 // DIE A THOUSAND DEATHS IF THIS EVER HAPPENS!!
99 .on('error', function (er) {
100 // IF ONLY THERE WAS SOMETHIGN HARDER THAN THROW
101 // MY SORROW COULD BE ADEQUATELY EXPRESSED. /o\
102 throw er
103 })
104  
105 // THROW A PARTY IN YOUR FACE WHEN ITS ALL LOADED!!
106 .on('load', function (config) {
107 console.awesome('HOLY SHIT!')
108 })
109 ```
110  
111 # BORING API DOCS
112  
113 ## cc(...args)
114  
115 MAKE A CHAIN AND ADD ALL THE ARGS.
116  
117 If the arg is a STRING, then it shall be a JSON FILENAME.
118  
119 SYNC I/O!
120  
121 RETURN THE CHAIN!
122  
123 ## cc.json(...args)
124  
125 Join the args INTO A JSON FILENAME!
126  
127 SYNC I/O!
128  
129 ## cc.find(relativePath)
130  
131 SEEK the RELATIVE PATH by climbing the TREE OF DIRECTORIES.
132  
133 RETURN THE FOUND PATH!
134  
135 SYNC I/O!
136  
137 ## cc.parse(content, file, type)
138  
139 Parse the content string, and guess the type from either the
140 specified type or the filename.
141  
142 RETURN THE RESULTING OBJECT!
143  
144 NO I/O!
145  
146 ## cc.env(prefix, env=process.env)
147  
148 Get all the keys on the provided env object (or process.env) which are
149 prefixed by the specified prefix, and put the values on a new object.
150  
151 RETURN THE RESULTING OBJECT!
152  
153 NO I/O!
154  
155 ## cc.ConfigChain()
156  
157 The ConfigChain class for CRAY CRAY JQUERY STYLE METHOD CHAINING!
158  
159 One of these is returned by the main exported function, as well.
160  
161 It inherits (prototypically) from
162 [ProtoList](https://github.com/isaacs/proto-list/), and also inherits
163 (parasitically) from
164 [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter)
165  
166 It has all the methods from both, and except where noted, they are
167 unchanged.
168  
169 ### LET IT BE KNOWN THAT chain IS AN INSTANCE OF ConfigChain.
170  
171 ## chain.sources
172  
173 A list of all the places where it got stuff. The keys are the names
174 passed to addFile or addUrl etc, and the value is an object with some
175 info about the data source.
176  
177 ## chain.addFile(filename, type, [name=filename])
178  
179 Filename is the name of the file. Name is an arbitrary string to be
180 used later if you desire. Type is either 'ini' or 'json', and will
181 try to guess intelligently if omitted.
182  
183 Loaded files can be saved later.
184  
185 ## chain.addUrl(url, type, [name=url])
186  
187 Same as the filename thing, but with a url.
188  
189 Can't be saved later.
190  
191 ## chain.addEnv(prefix, env, [name='env'])
192  
193 Add all the keys from the env object that start with the prefix.
194  
195 ## chain.addString(data, file, type, [name])
196  
197 Parse the string and add it to the set. (Mainly used internally.)
198  
199 ## chain.add(object, [name])
200  
201 Add the object to the set.
202  
203 ## chain.root {Object}
204  
205 The root from which all the other config objects in the set descend
206 prototypically.
207  
208 Put your defaults here.
209  
210 ## chain.set(key, value, name)
211  
212 Set the key to the value on the named config object. If name is
213 unset, then set it on the first config object in the set. (That is,
214 the one with the highest priority, which was added first.)
215  
216 ## chain.get(key, [name])
217  
218 Get the key from the named config object explicitly, or from the
219 resolved configs if not specified.
220  
221 ## chain.save(name, type)
222  
223 Write the named config object back to its origin.
224  
225 Currently only supported for env and file config types.
226  
227 For files, encode the data according to the type.
228  
229 ## chain.on('save', function () {})
230  
231 When one or more files are saved, emits `save` event when they're all
232 saved.
233  
234 ## chain.on('load', function (chain) {})
235  
236 When the config chain has loaded all the specified files and urls and
237 such, the 'load' event fires.