[api test doc] Make options to `Provider.prototype.file` take more flexible options

README.md

@@ -86,10 +86,21 @@ A sane default for this could be:
   nconf.env().argv();
   
   //
-  // 4. Values in `config.json` 
+  // 4. Values in `config.json`
   //
-  nconf.file({ 
-    file: 'config.json', 
+  nconf.file('/path/to/config.json');
+
+  //
+  // Or with a custom name
+  //
+  nconf.file('custom', '/path/to/config.json');
+
+  //
+  // Or searching from a base directory.
+  // Note: `name` is optional.
+  //
+  nconf.file(name, {
+    file: 'config.json',
     dir: 'search/from/here', 
     search: true
   });

lib/nconf/provider.js

@@ -36,28 +36,28 @@ var Provider = exports.Provider = function (options) {
 });
 
 //
-// ### function file (key, path)
+// ### function file (key, options)
 // #### @key {string|Object} Fully qualified options, name of file store, or path.
-// #### @path {string} **Optional** Path to the file for `key`.
+// #### @path {string|Object} **Optional** Full qualified options, or path.
 // Adds a new `File` store to this instance. Accepts the following options
 //
-//    nconf.file({ file: '.jitsuconf', dir: process.env.HOME, search: true })
-//    nconf.file('path/to/config/file')
-//    nconf.file('userconfig', 'path/to/config/file') 
+//    nconf.file({ file: '.jitsuconf', dir: process.env.HOME, search: true });
+//    nconf.file('path/to/config/file');
+//    nconf.file('userconfig', 'path/to/config/file');
+//    nconf.file('userconfig', { file: '.jitsuconf', search: true });
 //
-Provider.prototype.file = function (key, path) {
-  var options; 
-  
+Provider.prototype.file = function (key, options) {
   if (arguments.length == 1) {
-    options = typeof key !== 'object'
-      ? { type: 'file', file: key }
-      : key;
+    options = typeof key === 'string' ? { file: key } : key;
     key = 'file';
   }
   else {
-    options = { type: 'file', file: path };
+    options = typeof options === 'string'
+      ? { file: options }
+      : options;
   }
   
+  options.type = 'file';
   return this.add(key, options);
 };
 

test/provider-test.js

@@ -18,6 +18,13 @@ var fixturesDir = path.join(__dirname, 'fixtures'),
     files = [path.join(mergeFixtures, 'file1.json'), path.join(mergeFixtures, 'file2.json')],
     override = JSON.parse(fs.readFileSync(files[0]), 'utf8');
 
+function assertProvider(test) {
+  return {
+    topic: new nconf.Provider(),
+    "should use the correct File store": test
+  };
+}
+
 vows.describe('nconf/provider').addBatch({
   "When using nconf": {
     "an instance of 'nconf.Provider'": {
@@ -120,4 +127,39 @@ vows.describe('nconf/provider').addBatch({
       }
     }
   }
+}).addBatch({
+  "When using nconf": {
+    "an instance of 'nconf.Provider'": {
+      "the .file() method": {
+        "with a single filepath": assertProvider(function (provider) {
+          provider.file(helpers.fixture('store.json'));
+          assert.isObject(provider.stores.file);
+        }),
+        "with a name and a filepath": assertProvider(function (provider) {
+          provider.file('custom', helpers.fixture('store.json'));
+          assert.isObject(provider.stores.custom);
+        }),
+        "with a single object": assertProvider(function (provider) {
+          provider.file({
+            dir: helpers.fixture('hierarchy'),
+            file: 'store.json',
+            search: true
+          });
+
+          assert.isObject(provider.stores.file);
+          assert.equal(provider.stores.file.file, helpers.fixture('store.json'));
+        }),
+        "with a name and an object": assertProvider(function (provider) {
+          provider.file('custom', {
+            dir: helpers.fixture('hierarchy'),
+            file: 'store.json',
+            search: true
+          });
+
+          assert.isObject(provider.stores.custom);
+          assert.equal(provider.stores.custom.file, helpers.fixture('store.json'));
+        })
+      }
+    }
+  }
 }).export(module);