From 2e9acea2051ec50edf300620d645c2d661fd35b2 Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Thu, 26 Dec 2013 15:19:18 -0600 Subject: [PATCH 01/11] Added some more documentation to README.md --- README.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6dba8ef..b4d5875 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,14 @@ The non-configurable configuration loader for lazy people. The only option is to pass rc the name of your app, and your default configuration. -``` +```javascript var rc = require('rc')(appname, { //defaults go here. port: 2468 }) + +// Your configuration options => the `rc` object. + ``` # Standards @@ -38,6 +41,18 @@ Configuration files may be in either `json` or `ini` format. Since ini, and env variables do not have a standard for types, your application needs be prepared for strings. +# Advanced Usage + + +#### Pass in your own `argv` + +You may pass in your own `argv` as the third argument to `rc`. This may be useful for writing tests. + +```javascript +require('rc', appname, { /* defaults */}, argvFixture); +``` + + # License BSD / MIT / Apache2 From 6ace4f31acaeba843fffc236dbf48629e8f9d43e Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Thu, 26 Dec 2013 15:21:13 -0600 Subject: [PATCH 02/11] Smaller headings, ocd --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b4d5875..99930c8 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The non-configurable configuration loader for lazy people. -# Usage +## Usage The only option is to pass rc the name of your app, and your default configuration. @@ -16,7 +16,7 @@ var rc = require('rc')(appname, { ``` -# Standards +## Standards Given your application name (`appname`), rc will look in all the obvious places for configuration. @@ -35,15 +35,16 @@ Given your application name (`appname`), rc will look in all the obvious places All configuration sources that were found will be flattened into one object, so that sources earlier in this list override later ones. -# Formats +## Formats Configuration files may be in either `json` or `ini` format. Since ini, and env variables do not have a standard for types, your application needs be prepared for strings. -# Advanced Usage +## Advanced Usage + #### Pass in your own `argv` You may pass in your own `argv` as the third argument to `rc`. This may be useful for writing tests. @@ -53,6 +54,6 @@ require('rc', appname, { /* defaults */}, argvFixture); ``` -# License +## License BSD / MIT / Apache2 From c8894259362c9a04186d061e9a6f1de99718158f Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Thu, 26 Dec 2013 15:36:34 -0600 Subject: [PATCH 03/11] Added 'ini' and 'json' configuration file examples to show support for comments and nested objects. --- README.md | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 99930c8..d9a4d6e 100644 --- a/README.md +++ b/README.md @@ -35,11 +35,34 @@ Given your application name (`appname`), rc will look in all the obvious places All configuration sources that were found will be flattened into one object, so that sources earlier in this list override later ones. -## Formats -Configuration files may be in either `json` or `ini` format. -Since ini, and env variables do not have a standard for types, -your application needs be prepared for strings. +## Configuration File Formats + +Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. + +#### Example `.appnamerc` in `json` format + +```json +{ + "views": { + "engine": "jade", + }, + "port": 3000 +} +``` + +#### Example `.appnamerc` in `ini` format +```ini +; You can include comments if you want. + +port=3000 + +; `rc` has built-in support for ini sections, see? +[views] + engine=jade +``` + +> Since ini, and env variables do not have a standard for types, your application needs be prepared for strings. From a9665bb51b83768fca9fc4c361e7dd1011632268 Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Thu, 26 Dec 2013 15:44:31 -0600 Subject: [PATCH 04/11] Added note about options being merged instead of replaced, and clarification about file extensions not mattering for ini vs. json config files. --- README.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d9a4d6e..37c54f8 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,12 @@ The only option is to pass rc the name of your app, and your default configurati ```javascript var rc = require('rc')(appname, { //defaults go here. - port: 2468 + port: 2468, + + //defaults which are objects will be merged, not replaced + views: { + engine: 'jade' + } }) // Your configuration options => the `rc` object. @@ -23,7 +28,7 @@ Given your application name (`appname`), rc will look in all the obvious places * command line arguments (parsed by optimist) * environment variables prefixed with `${appname}_` * if you passed an option `--config file` then from that file - * a local `.${appname}rc` or the first found looking in `./ ../ ../../ ../../../` etc. + * a local `.${appname}rc` or the first found looking in `./ ../ ../../ ../../../` etc. * `$HOME/.${appname}rc` * `$HOME/.${appname}/config` * `$HOME/.config/${appname}` @@ -33,14 +38,14 @@ Given your application name (`appname`), rc will look in all the obvious places * the defaults object you passed in. All configuration sources that were found will be flattened into one object, -so that sources earlier in this list override later ones. +so that sources **earlier** in this list override later ones. ## Configuration File Formats -Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. +Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. rc ignores file extensions of configuration files. -#### Example `.appnamerc` in `json` format +#### Formatted as `json` ```json { @@ -51,7 +56,7 @@ Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/ } ``` -#### Example `.appnamerc` in `ini` format +#### Formatted as `ini` ```ini ; You can include comments if you want. From dceb777e80adffd248e7c9ab2a76ea18f9a53167 Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Thu, 26 Dec 2013 15:45:38 -0600 Subject: [PATCH 05/11] Fixed the JSON example (remove trailing comma) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 37c54f8..849bf83 100644 --- a/README.md +++ b/README.md @@ -43,14 +43,14 @@ so that sources **earlier** in this list override later ones. ## Configuration File Formats -Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. rc ignores file extensions of configuration files. +Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. rc ignores file extensions of configuration files. The example configurations below are equivalent: #### Formatted as `json` ```json { "views": { - "engine": "jade", + "engine": "jade" }, "port": 3000 } From 0002ccc1d82da3fd519538bc7930e2051fb4a8de Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Thu, 26 Dec 2013 15:52:36 -0600 Subject: [PATCH 06/11] Added caveat about ini sections being supported only one level deep --- README.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 849bf83..89faa9d 100644 --- a/README.md +++ b/README.md @@ -45,18 +45,9 @@ so that sources **earlier** in this list override later ones. Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. rc ignores file extensions of configuration files. The example configurations below are equivalent: -#### Formatted as `json` - -```json -{ - "views": { - "engine": "jade" - }, - "port": 3000 -} -``` #### Formatted as `ini` + ```ini ; You can include comments if you want. @@ -65,8 +56,23 @@ port=3000 ; `rc` has built-in support for ini sections, see? [views] engine=jade + +; But only one-level deep. So in this example, you can't do a sub-object inside of 'views'. +; (More deeply nested objects ARE supported using the JSON format.) ``` +#### Formatted as `json` + +```json +{ + "views": { + "engine": "jade" + }, + "port": 3000 +} +``` + + > Since ini, and env variables do not have a standard for types, your application needs be prepared for strings. From 4950c7fd6970d5cd129dd5494dea7fbe779e3d1d Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Thu, 26 Dec 2013 16:26:17 -0600 Subject: [PATCH 07/11] Added warning about passed-in defaults being mutated and a note on performance. --- README.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 89faa9d..dc49dac 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ The non-configurable configuration loader for lazy people. The only option is to pass rc the name of your app, and your default configuration. ```javascript -var rc = require('rc')(appname, { +var conf = require('rc')(appname, { //defaults go here. port: 2468, @@ -15,12 +15,18 @@ var rc = require('rc')(appname, { views: { engine: 'jade' } -}) +}); +``` -// Your configuration options => the `rc` object. +`rc` will return your configuration options merged with the defaults you specify. +If you pass in a predefined defaults object, it will be mutated: +```javascript +var conf = {}; +require('rc', appname, conf); ``` + ## Standards Given your application name (`appname`), rc will look in all the obvious places for configuration. @@ -88,6 +94,11 @@ require('rc', appname, { /* defaults */}, argvFixture); ``` +## Note on Performance + +`rc` is running `fs.statSync`-- so make sure you don't use it in a hot code path (e.g. a request handler) + + ## License BSD / MIT / Apache2 From d25b32030fc0e22ad6eb234b66f5db0e31ca9045 Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Thu, 26 Dec 2013 16:36:12 -0600 Subject: [PATCH 08/11] Fixed typos. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dc49dac..5298253 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ If you pass in a predefined defaults object, it will be mutated: ```javascript var conf = {}; -require('rc', appname, conf); +require('rc')(appname, conf); ``` @@ -90,7 +90,7 @@ port=3000 You may pass in your own `argv` as the third argument to `rc`. This may be useful for writing tests. ```javascript -require('rc', appname, { /* defaults */}, argvFixture); +require('rc')(appname, defaults, argvFixture); ``` From 5d215aed6cbb923561fc510792a05c1802c2a8c9 Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Sun, 12 Jan 2014 21:00:48 -0600 Subject: [PATCH 09/11] explained that the third argument is for custom opts parser --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5298253..5422739 100644 --- a/README.md +++ b/README.md @@ -87,10 +87,10 @@ port=3000 #### Pass in your own `argv` -You may pass in your own `argv` as the third argument to `rc`. This may be useful for writing tests. +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). ```javascript -require('rc')(appname, defaults, argvFixture); +require('rc')(appname, defaults, customArgvParser); ``` From 2eb46835e00c182385bad30d0a73f02caa3ddf51 Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Sun, 12 Jan 2014 21:08:12 -0600 Subject: [PATCH 10/11] cleared up my previous confusion about nested objects in .ini config files --- README.md | 39 ++++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 5422739..b9f5fd3 100644 --- a/README.md +++ b/README.md @@ -55,26 +55,47 @@ Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/ #### Formatted as `ini` ```ini -; You can include comments if you want. +; You can include comments in `ini` format if you want. + +dependsOn=0.10.0 -port=3000 ; `rc` has built-in support for ini sections, see? -[views] - engine=jade -; But only one-level deep. So in this example, you can't do a sub-object inside of 'views'. -; (More deeply nested objects ARE supported using the JSON format.) +[commands] + www = ./commands/www + console = ./commands/repl + + +; You can even do nested sections + +[generators.options] + engine = ejs + +[generators.modules] + new = generate-new + engine = generate-backend + ``` #### Formatted as `json` ```json { - "views": { - "engine": "jade" + "dependsOn": "0.10.0", + "commands": { + "www": "./commands/www", + "console": "./commands/repl" }, - "port": 3000 + "generators": { + "options": { + "engine": "ejs" + }, + "modules": { + "new": "generate-new", + "backend": "generate-backend" + } + } } ``` From c102bbb28a9764a7876cfa8114a6250ba29a9a85 Mon Sep 17 00:00:00 2001 From: Mike McNeil Date: Sun, 12 Jan 2014 21:15:53 -0600 Subject: [PATCH 11/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b9f5fd3..7040945 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/ #### Formatted as `ini` -```ini +``` ; You can include comments in `ini` format if you want. dependsOn=0.10.0