Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 150 lines (102 sloc) 3.758 kb
20a048e @dominictarr initial
authored
1 # rc
2
deba2c4 @sam-github Clarify docs, and fix spelling errors
sam-github authored
3 The non-configurable configuration loader for lazy people.
20a048e @dominictarr initial
authored
4
6ace4f3 @mikermcneil Smaller headings, ocd
mikermcneil authored
5 ## Usage
20a048e @dominictarr initial
authored
6
deba2c4 @sam-github Clarify docs, and fix spelling errors
sam-github authored
7 The only option is to pass rc the name of your app, and your default configuration.
20a048e @dominictarr initial
authored
8
2e9acea @mikermcneil Added some more documentation to README.md
mikermcneil authored
9 ```javascript
4950c7f @mikermcneil Added warning about passed-in defaults being mutated and a note on perfo...
mikermcneil authored
10 var conf = require('rc')(appname, {
deba2c4 @sam-github Clarify docs, and fix spelling errors
sam-github authored
11 //defaults go here.
a9665bb @mikermcneil Added note about options being merged instead of replaced, and clarifica...
mikermcneil authored
12 port: 2468,
13
14 //defaults which are objects will be merged, not replaced
15 views: {
16 engine: 'jade'
17 }
4950c7f @mikermcneil Added warning about passed-in defaults being mutated and a note on perfo...
mikermcneil authored
18 });
19 ```
2e9acea @mikermcneil Added some more documentation to README.md
mikermcneil authored
20
4950c7f @mikermcneil Added warning about passed-in defaults being mutated and a note on perfo...
mikermcneil authored
21 `rc` will return your configuration options merged with the defaults you specify.
22 If you pass in a predefined defaults object, it will be mutated:
2e9acea @mikermcneil Added some more documentation to README.md
mikermcneil authored
23
4950c7f @mikermcneil Added warning about passed-in defaults being mutated and a note on perfo...
mikermcneil authored
24 ```javascript
25 var conf = {};
d25b320 @mikermcneil Fixed typos.
mikermcneil authored
26 require('rc')(appname, conf);
20a048e @dominictarr initial
authored
27 ```
28
0971fc3 Changes `config` key to point to latest parsed config file instead of on...
Dan Kaplun authored
29 If `rc` finds any config files for your app, the returned config object will have
30 a `configs` array containing their paths:
31
32 ```javascript
33 var appCfg = require('rc')(appname, conf);
34 appCfg.configs[0] // /etc/appnamerc
35 appCfg.configs[1] // /home/dominictarr/.config/appname
36 appCfg.config // same as appCfg.configs[appCfg.configs.length - 1]
37 ```
4950c7f @mikermcneil Added warning about passed-in defaults being mutated and a note on perfo...
mikermcneil authored
38
6ace4f3 @mikermcneil Smaller headings, ocd
mikermcneil authored
39 ## Standards
20a048e @dominictarr initial
authored
40
deba2c4 @sam-github Clarify docs, and fix spelling errors
sam-github authored
41 Given your application name (`appname`), rc will look in all the obvious places for configuration.
20a048e @dominictarr initial
authored
42
334ec12 @springmeyer switch to minimist
springmeyer authored
43 * command line arguments (parsed by minimist)
deba2c4 @sam-github Clarify docs, and fix spelling errors
sam-github authored
44 * environment variables prefixed with `${appname}_`
02c01f7 @mikermcneil Update README.md
mikermcneil authored
45 * or use "\_\_" to indicate nested properties <br/> _(e.g. `appname_foo__bar__baz` => `foo.bar.baz`)_
20a048e @dominictarr initial
authored
46 * if you passed an option `--config file` then from that file
a9665bb @mikermcneil Added note about options being merged instead of replaced, and clarifica...
mikermcneil authored
47 * a local `.${appname}rc` or the first found looking in `./ ../ ../../ ../../../` etc.
deba2c4 @sam-github Clarify docs, and fix spelling errors
sam-github authored
48 * `$HOME/.${appname}rc`
49 * `$HOME/.${appname}/config`
50 * `$HOME/.config/${appname}`
51 * `$HOME/.config/${appname}/config`
52 * `/etc/${appname}rc`
53 * `/etc/${appname}/config`
20a048e @dominictarr initial
authored
54 * the defaults object you passed in.
55
deba2c4 @sam-github Clarify docs, and fix spelling errors
sam-github authored
56 All configuration sources that were found will be flattened into one object,
a9665bb @mikermcneil Added note about options being merged instead of replaced, and clarifica...
mikermcneil authored
57 so that sources **earlier** in this list override later ones.
20a048e @dominictarr initial
authored
58
59
c889425 @mikermcneil Added 'ini' and 'json' configuration file examples to show support for c...
mikermcneil authored
60 ## Configuration File Formats
61
0e1f649 @jeremyruppel Remove misleading bit about extensions. Fixes #28
jeremyruppel authored
62 Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. The example configurations below are equivalent:
c889425 @mikermcneil Added 'ini' and 'json' configuration file examples to show support for c...
mikermcneil authored
63
64
a9665bb @mikermcneil Added note about options being merged instead of replaced, and clarifica...
mikermcneil authored
65 #### Formatted as `ini`
0002ccc @mikermcneil Added caveat about ini sections being supported only one level deep
mikermcneil authored
66
c102bbb @mikermcneil Update README.md
mikermcneil authored
67 ```
2eb4683 @mikermcneil cleared up my previous confusion about nested objects in .ini config fil...
mikermcneil authored
68 ; You can include comments in `ini` format if you want.
69
70 dependsOn=0.10.0
c889425 @mikermcneil Added 'ini' and 'json' configuration file examples to show support for c...
mikermcneil authored
71
72
73 ; `rc` has built-in support for ini sections, see?
0002ccc @mikermcneil Added caveat about ini sections being supported only one level deep
mikermcneil authored
74
2eb4683 @mikermcneil cleared up my previous confusion about nested objects in .ini config fil...
mikermcneil authored
75 [commands]
76 www = ./commands/www
77 console = ./commands/repl
78
79
80 ; You can even do nested sections
81
82 [generators.options]
83 engine = ejs
84
85 [generators.modules]
86 new = generate-new
87 engine = generate-backend
88
c889425 @mikermcneil Added 'ini' and 'json' configuration file examples to show support for c...
mikermcneil authored
89 ```
90
0002ccc @mikermcneil Added caveat about ini sections being supported only one level deep
mikermcneil authored
91 #### Formatted as `json`
92
93 ```json
94 {
23a858a @evocateur Use `strip-json-comments` to allow comments in JSON config files.
evocateur authored
95 // You can even comment your JSON, if you want
2eb4683 @mikermcneil cleared up my previous confusion about nested objects in .ini config fil...
mikermcneil authored
96 "dependsOn": "0.10.0",
97 "commands": {
98 "www": "./commands/www",
99 "console": "./commands/repl"
0002ccc @mikermcneil Added caveat about ini sections being supported only one level deep
mikermcneil authored
100 },
2eb4683 @mikermcneil cleared up my previous confusion about nested objects in .ini config fil...
mikermcneil authored
101 "generators": {
102 "options": {
103 "engine": "ejs"
104 },
105 "modules": {
106 "new": "generate-new",
107 "backend": "generate-backend"
108 }
109 }
0002ccc @mikermcneil Added caveat about ini sections being supported only one level deep
mikermcneil authored
110 }
111 ```
112
23a858a @evocateur Use `strip-json-comments` to allow comments in JSON config files.
evocateur authored
113 Comments are stripped from JSON config via [strip-json-comments](https://github.com/sindresorhus/strip-json-comments).
0002ccc @mikermcneil Added caveat about ini sections being supported only one level deep
mikermcneil authored
114
c889425 @mikermcneil Added 'ini' and 'json' configuration file examples to show support for c...
mikermcneil authored
115 > Since ini, and env variables do not have a standard for types, your application needs be prepared for strings.
20a048e @dominictarr initial
authored
116
2e9acea @mikermcneil Added some more documentation to README.md
mikermcneil authored
117
118
6ace4f3 @mikermcneil Smaller headings, ocd
mikermcneil authored
119 ## Advanced Usage
120
2e9acea @mikermcneil Added some more documentation to README.md
mikermcneil authored
121 #### Pass in your own `argv`
122
5d215ae @mikermcneil explained that the third argument is for custom opts parser
mikermcneil authored
123 You may pass in your own `argv` as the third argument to `rc`. This is in case you want to [use your own command-line opts parser](https://github.com/dominictarr/rc/pull/12).
2e9acea @mikermcneil Added some more documentation to README.md
mikermcneil authored
124
125 ```javascript
5d215ae @mikermcneil explained that the third argument is for custom opts parser
mikermcneil authored
126 require('rc')(appname, defaults, customArgvParser);
2e9acea @mikermcneil Added some more documentation to README.md
mikermcneil authored
127 ```
128
8177f95 @dominictarr document injectable parsers
authored
129 ## Pass in your own parser
130
131 If you have a special need to use a non-standard parser,
132 you can do so by passing in the parser as the 4th argument.
133 (leave the 3rd as null to get the default args parser)
134
135 ```javascript
136 require('rc')(appname, defaults, null, parser);
137 ```
138
139 This may also be used to force a more strict format,
140 such as strict, valid JSON only.
2e9acea @mikermcneil Added some more documentation to README.md
mikermcneil authored
141
4950c7f @mikermcneil Added warning about passed-in defaults being mutated and a note on perfo...
mikermcneil authored
142 ## Note on Performance
143
144 `rc` is running `fs.statSync`-- so make sure you don't use it in a hot code path (e.g. a request handler)
145
146
6ace4f3 @mikermcneil Smaller headings, ocd
mikermcneil authored
147 ## License
20a048e @dominictarr initial
authored
148
250d16e @dominictarr licenses in readme
authored
149 BSD / MIT / Apache2
Something went wrong with that request. Please try again.