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

   1 # cosmiconfig
   2
   3 [![Build Status](https://img.shields.io/travis/davidtheclark/cosmiconfig/master.svg?label=unix%20build)](https://travis-ci.org/davidtheclark/cosmiconfig) [![Build status](https://img.shields.io/appveyor/ci/davidtheclark/cosmiconfig/master.svg?label=windows%20build)](https://ci.appveyor.com/project/davidtheclark/cosmiconfig/branch/master)
   4
   5 Find and load a configuration object from
   6 - a `package.json` property (anywhere up the directory tree)
   7 - a JSON or YAML "rc file" (anywhere up the directory tree)
   8 - a `.config.js` CommonJS module (anywhere up the directory tree)
   9
  10 For example, if your module's name is "soursocks," cosmiconfig will search out configuration in the following places:
  11 - a `soursocks` property in `package.json` (anywhere up the directory tree)
  12 - a `.soursocksrc` file in JSON or YAML format (anywhere up the directory tree)
  13 - a `soursocks.config.js` file exporting a JS object (anywhere up the directory tree)
  14
  15 cosmiconfig continues to search in these places all the way up the directory tree until it finds acceptable configuration (or hits the home directory).
  16
  17 Additionally, all of these search locations are configurable: you can customize filenames or turn off any location.
  18
  19 You can also look for rc files with extensions, e.g. `.soursocksrc.json` or `.soursocksrc.yaml`.
  20 You may like extensions on your rc files because you'll get syntax highlighting and linting in text editors.
  21
  22 ## Installation
  23
  24 ```
  25 npm install cosmiconfig
  26 ```
  27
  28 Tested in Node 4+.
  29
  30 ## Usage
  31
  32 ```js
  33 var cosmiconfig = require('cosmiconfig');
  34
  35 var explorer = cosmiconfig(yourModuleName[, options]);
  36
  37 explorer.load(yourSearchPath)
  38   .then((result) => {
  39     // result.config is the parsed configuration object
  40     // result.filepath is the path to the config file that was found
  41   })
  42   .catch((parsingError) => {
  43     // do something constructive
  44   });
  45 ```
  46
  47 The function `cosmiconfig()` searches for a configuration object and returns a Promise,
  48 which resolves with an object containing the information you're looking for.
  49
  50 You can also pass option `sync: true` to load the config synchronously, returning the config itself.
  51
  52 So let's say `var yourModuleName = 'goldengrahams'` — here's how cosmiconfig will work:
  53
  54 - Starting from `process.cwd()` (or some other directory defined by the `searchPath` argument to `load()`), it looks for configuration objects in three places, in this order:
  55   1. A `goldengrahams` property in a `package.json` file (or some other property defined by `options.packageProp`);
  56   2. A `.goldengrahamsrc` file with JSON or YAML syntax (or some other filename defined by `options.rc`);
  57   3. A `goldengrahams.config.js` JS file exporting the object (or some other filename defined by `options.js`).
  58 - If none of those searches reveal a configuration object, it moves up one directory level and tries again. So the search continues in `./`, `../`, `../../`, `../../../`, etc., checking those three locations in each directory.
  59 - It continues searching until it arrives at your home directory (or some other directory defined by `options.stopDir`).
  60 - If at any point a parseable configuration is found, the `cosmiconfig()` Promise resolves with its result object.
  61 - If no configuration object is found, the `cosmiconfig()` Promise resolves with `null`.
  62 - If a configuration object is found *but is malformed* (causing a parsing error), the `cosmiconfig()` Promise rejects and shares that error (so you should `.catch()` it).
  63
  64 All this searching can be short-circuited by passing `options.configPath` to specify a file.
  65 cosmiconfig will read that file and try parsing it as JSON, YAML, or JS.
  66
  67 ## Caching
  68
  69 As of v2, cosmiconfig uses a few caches to reduce the need for repetitious reading of the filesystem. Every new cosmiconfig instance (created with `cosmiconfig()`) has its own caches.
  70
  71 To avoid or work around caching, you can
  72 - create separate instances of cosmiconfig, or
  73 - set `cache: false` in your options.
  74 - use the cache clearing methods documented below.
  75
  76 ## API
  77
  78 ### `var explorer = cosmiconfig(moduleName[, options])`
  79
  80 Creates a cosmiconfig instance (i.e. explorer) configured according to the arguments, and initializes its caches.
  81
  82 #### moduleName
  83
  84 Type: `string`
  85
  86 You module name. This is used to create the default filenames that cosmiconfig will look for.
  87
  88 #### Options
  89
  90 ##### packageProp
  91
  92 Type: `string` or `false`
  93 Default: `'[moduleName]'`
  94
  95 Name of the property in `package.json` to look for.
  96
  97 If `false`, cosmiconfig will not look in `package.json` files.
  98
  99 ##### rc
 100
 101 Type: `string` or `false`
 102 Default: `'.[moduleName]rc'`
 103
 104 Name of the "rc file" to look for, which can be formatted as JSON or YAML.
 105
 106 If `false`, cosmiconfig will not look for an rc file.
 107
 108 If `rcExtensions: true`, the rc file can also have extensions that specify the syntax, e.g. `.[moduleName]rc.json`.
 109 You may like extensions on your rc files because you'll get syntax highlighting and linting in text editors.
 110 Also, with `rcExtensions: true`, you can use JS modules as rc files, e.g. `.[moduleName]rc.js`.
 111
 112 ##### js
 113
 114 Type: `string` or `false`
 115 Default: `'[moduleName].config.js'`
 116
 117 Name of a JS file to look for, which must export the configuration object.
 118
 119 If `false`, cosmiconfig will not look for a JS file.
 120
 121 ##### rcStrictJson
 122
 123 Type: `boolean`
 124 Default: `false`
 125
 126 If `true`, cosmiconfig will expect rc files to be strict JSON. No YAML permitted, and no sloppy JSON.
 127
 128 By default, rc files are parsed with [js-yaml](https://github.com/nodeca/js-yaml), which is
 129 more permissive with punctuation than standard strict JSON.
 130
 131 ##### rcExtensions
 132
 133 Type: `boolean`
 134 Default: `false`
 135
 136 If `true`, cosmiconfig will look for rc files with extensions, in addition to rc files without.
 137
 138 This adds a few steps to the search process.
 139 Instead of *just* looking for `.goldengrahamsrc` (no extension), it will also look for the following, in this order:
 140
 141 - `.goldengrahamsrc.json`
 142 - `.goldengrahamsrc.yaml`
 143 - `.goldengrahamsrc.yml`
 144 - `.goldengrahamsrc.js`
 145
 146 ##### stopDir
 147
 148 Type: `string`
 149 Default: Absolute path to your home directory
 150
 151 Directory where the search will stop.
 152
 153 ##### cache
 154
 155 Type: `boolean`
 156 Default: `true`
 157
 158 If `false`, no caches will be used.
 159
 160 ##### sync
 161
 162 Type: `boolean`
 163 Default: `false`
 164
 165 If `true`, config will be loaded synchronously.
 166
 167 ##### transform
 168
 169 Type: `Function`
 170
 171 A function that transforms the parsed configuration. Receives the result object with `config` and `filepath` properties.
 172
 173 If the option `sync` is `false` (default), the function must return a Promise that resolves with the transformed result.
 174 If the option `sync` is `true`, though, `transform` should be a synchronous function which returns the transformed result.
 175
 176 The reason you might use this option instead of simply applying your transform function some other way is that *the transformed result will be cached*. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is loaded.
 177
 178 ##### configPath
 179
 180 Type: `string`
 181
 182 If provided, cosmiconfig will load and parse a config from this path, and will not perform its usual search.
 183
 184 ##### format
 185
 186 Type: `'json' | 'yaml' | 'js'`
 187
 188 The expected file format for the config loaded from `configPath`.
 189
 190 If not specified, cosmiconfig will try to infer the format using the extension name (if it has one).
 191 In the event that the file does not have an extension or the extension is unrecognized, cosmiconfig will try to parse it as a JSON, YAML, or JS file.
 192
 193 ### Instance methods (on `explorer`)
 194
 195 #### `load([searchPath, configPath])`
 196
 197 Find and load a configuration file. Returns a Promise that resolves with `null`, if nothing is found, or an object with two properties:
 198 - `config`: The loaded and parsed configuration.
 199 - `filepath`: The filepath where this configuration was found.
 200
 201 You should provide *either* `searchPath` *or* `configPath`. Use `configPath` if you know the path of the configuration file you want to load. Otherwise, use `searchPath`.
 202
 203 ```js
 204 explorer.load('start/search/here');
 205 explorer.load('start/search/at/this/file.css');
 206
 207 explorer.load(null, 'load/this/file.json');
 208 ```
 209
 210 If you provide `searchPath`, cosmiconfig will start its search at `searchPath` and continue to search up the directory tree, as documented above.
 211
 212 If you provide `configPath` (i.e. you already know where the configuration is that you want to load), cosmiconfig will try to read and parse that file. Note that the [`format` option](#format) is applicable for this as well.
 213
 214 #### `clearFileCache()`
 215
 216 Clears the cache used when you provide a `configPath` argument to `load`.
 217
 218 #### `clearDirectoryCache()`
 219
 220 Clears the cache used when you provide a `searchPath` argument to `load`.
 221
 222 #### `clearCaches()`
 223
 224 Performs both `clearFileCache()` and `clearDirectoryCache()`.
 225
 226 ## Differences from [rc](https://github.com/dominictarr/rc)
 227
 228 [rc](https://github.com/dominictarr/rc) serves its focused purpose well. cosmiconfig differs in a few key ways — making it more useful for some projects, less useful for others:
 229
 230 - Looks for configuration in some different places: in a `package.json` property, an rc file, a `.config.js` file, and rc files with extensions.
 231 - Built-in support for JSON, YAML, and CommonJS formats.
 232 - Stops at the first configuration found, instead of finding all that can be found up the directory tree and merging them automatically.
 233 - Options.
 234 - Asynchronous by default (though can be run synchronously).
 235
 236 ## Contributing & Development
 237
 238 Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
 239
 240 And please do participate!