.config/coc/extensions/node_modules/coc-prettier/node_modules/rc/README.md

   1 # rc
   2
   3 The non-configurable configuration loader for lazy people.
   4
   5 ## Usage
   6
   7 The only option is to pass rc the name of your app, and your default configuration.
   8
   9 ```javascript
  10 var conf = require('rc')(appname, {
  11   //defaults go here.
  12   port: 2468,
  13
  14   //defaults which are objects will be merged, not replaced
  15   views: {
  16     engine: 'jade'
  17   }
  18 });
  19 ```
  20
  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:
  23
  24 ```javascript
  25 var conf = {};
  26 require('rc')(appname, conf);
  27 ```
  28
  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 ```
  38
  39 ## Standards
  40
  41 Given your application name (`appname`), rc will look in all the obvious places for configuration.
  42
  43   * command line arguments, parsed by minimist _(e.g. `--foo baz`, also nested: `--foo.bar=baz`)_
  44   * environment variables prefixed with `${appname}_`
  45     * or use "\_\_" to indicate nested properties <br/> _(e.g. `appname_foo__bar__baz` => `foo.bar.baz`)_
  46   * if you passed an option `--config file` then from that file
  47   * a local `.${appname}rc` or the first found looking in `./ ../ ../../ ../../../` etc.
  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`
  54   * the defaults object you passed in.
  55
  56 All configuration sources that were found will be flattened into one object,
  57 so that sources **earlier** in this list override later ones.
  58
  59
  60 ## Configuration File Formats
  61
  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. **No** file extension (`.json` or `.ini`) should be used. The example configurations below are equivalent:
  63
  64
  65 #### Formatted as `ini`
  66
  67 ```
  68 ; You can include comments in `ini` format if you want.
  69
  70 dependsOn=0.10.0
  71
  72
  73 ; `rc` has built-in support for ini sections, see?
  74
  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
  89 ```
  90
  91 #### Formatted as `json`
  92
  93 ```javascript
  94 {
  95   // You can even comment your JSON, if you want
  96   "dependsOn": "0.10.0",
  97   "commands": {
  98     "www": "./commands/www",
  99     "console": "./commands/repl"
 100   },
 101   "generators": {
 102     "options": {
 103       "engine": "ejs"
 104     },
 105     "modules": {
 106       "new": "generate-new",
 107       "backend": "generate-backend"
 108     }
 109   }
 110 }
 111 ```
 112
 113 Comments are stripped from JSON config via [strip-json-comments](https://github.com/sindresorhus/strip-json-comments).
 114
 115 > Since ini, and env variables do not have a standard for types, your application needs be prepared for strings.
 116
 117 To ensure that string representations of booleans and numbers are always converted into their proper types (especially useful if you intend to do strict `===` comparisons), consider using a module such as [parse-strings-in-object](https://github.com/anselanza/parse-strings-in-object) to wrap the config object returned from rc.
 118
 119
 120 ## Simple example demonstrating precedence
 121 Assume you have an application like this (notice the hard-coded defaults passed to rc):
 122 ```
 123 const conf = require('rc')('myapp', {
 124     port: 12345,
 125     mode: 'test'
 126 });
 127
 128 console.log(JSON.stringify(conf, null, 2));
 129 ```
 130 You also have a file `config.json`, with these contents:
 131 ```
 132 {
 133   "port": 9000,
 134   "foo": "from config json",
 135   "something": "else"
 136 }
 137 ```
 138 And a file `.myapprc` in the same folder, with these contents:
 139 ```
 140 {
 141   "port": "3001",
 142   "foo": "bar"
 143 }
 144 ```
 145 Here is the expected output from various commands:
 146
 147 `node .`
 148 ```
 149 {
 150   "port": "3001",
 151   "mode": "test",
 152   "foo": "bar",
 153   "_": [],
 154   "configs": [
 155     "/Users/stephen/repos/conftest/.myapprc"
 156   ],
 157   "config": "/Users/stephen/repos/conftest/.myapprc"
 158 }
 159 ```
 160 *Default `mode` from hard-coded object is retained, but port is overridden by `.myapprc` file (automatically found based on appname match), and `foo` is added.*
 161
 162
 163 `node . --foo baz`
 164 ```
 165 {
 166   "port": "3001",
 167   "mode": "test",
 168   "foo": "baz",
 169   "_": [],
 170   "configs": [
 171     "/Users/stephen/repos/conftest/.myapprc"
 172   ],
 173   "config": "/Users/stephen/repos/conftest/.myapprc"
 174 }
 175 ```
 176 *Same result as above but `foo` is overridden because command-line arguments take precedence over `.myapprc` file.*
 177
 178 `node . --foo barbar --config config.json`
 179 ```
 180 {
 181   "port": 9000,
 182   "mode": "test",
 183   "foo": "barbar",
 184   "something": "else",
 185   "_": [],
 186   "config": "config.json",
 187   "configs": [
 188     "/Users/stephen/repos/conftest/.myapprc",
 189     "config.json"
 190   ]
 191 }
 192 ```
 193 *Now the `port` comes from the `config.json` file specified (overriding the value from `.myapprc`), and `foo` value is overriden by command-line despite also being specified in the `config.json` file.*
 194
 195
 196
 197 ## Advanced Usage
 198
 199 #### Pass in your own `argv`
 200
 201 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).
 202
 203 ```javascript
 204 require('rc')(appname, defaults, customArgvParser);
 205 ```
 206
 207 ## Pass in your own parser
 208
 209 If you have a special need to use a non-standard parser,
 210 you can do so by passing in the parser as the 4th argument.
 211 (leave the 3rd as null to get the default args parser)
 212
 213 ```javascript
 214 require('rc')(appname, defaults, null, parser);
 215 ```
 216
 217 This may also be used to force a more strict format,
 218 such as strict, valid JSON only.
 219
 220 ## Note on Performance
 221
 222 `rc` is running `fs.statSync`-- so make sure you don't use it in a hot code path (e.g. a request handler)
 223
 224
 225 ## License
 226
 227 Multi-licensed under the two-clause BSD License, MIT License, or Apache License, version 2.0