Implements #23, report which config files were loaded

[achingbrain]

I've also run a situation similar to #23 where it would be useful to report which configuration files were actually loaded by rc, so have added support for a _rcfiles property to be added to the returned configuration object which contains the list of files, along with tests and a section documenting it in the readme.

It works by passing an array into the json util method - when it parses a json/ini file, it adds the name of the file to the list. The list is then added to the configuration object as a non-enumerable property.

I hope this is helpful, please let me know if you have any comments.

[dominictarr]

can you describe your situation? what did you need the file locations for?
I just ask because it helps a lot to understand how people use rc.

[achingbrain]

Two reasons really - the first is it's a nice sanity check to tell people where their config is coming from on application startup (for example if over the course of trying out an application, they drop config files all over the place then get confused as to why their latest change doesn't appear to be picked up), and also because the app I'm writing lets people update their config file programatically - for that it's helpful to know where the config files are loaded from.

[dominictarr]

interesting! this is a good point actually!

okay I think there is enough need to justify this feature, but what is the best way to implement it?

so should the config files be a list? maybe they should be named?

rc can only load config from 5 places, named file (--config or ${appname}_config), local file (./.{appname}rc, ../.{appname}rc, etc) user file (/.{appname}rc), system file (/etc/{appname}rc)
so maybe it should return a object of the sorts of files and their paths. on the other hand, when updating configuration, it should probably be done from the top most file.

it feels a little ugly to expose _rcFiles with a _ in front, is there another way we could do this? also asking @mikermcneil since he has contributed a lot to rc.

[achingbrain]

My gut feeling is that exposing the fact that location one missed, locations two, three and four hit and location five missed is exposing too much of the internals. As a consumer of the module, I just want to know where the config file(s) were loaded from but I'd rather leave anything else up to rc and not have to worry about it.

A list also retains the order of precedence with very little effort.

The _ was really just to indicate that it was something introduced by rc and an attempt to ensure it wouldn't be mistaken for an actual configuration option. I guess the _ character is a bit overloaded as 'private' so I can see why it would raise eyebrows.

Whatever it's called, it should definitely not be an enumerable property, in case it the config object gets JSONified at any point (served to a web browser or whatever).

[mikermcneil]

Good point. Hmm...

What if there was another method with the same function signature that returned an array of "source metadata" in order of preference? Eg

[
  {
    type: 'envVariable',
    config: { foo: 'the value' }
  },
  {
    type: 'file',
    path: '/Users/mikermcneil/.sailsrc',
    config: {
      generators: {
        'new': 'sails-generate-new',
        model: 'sails-generate-model',
        directive: './my-custom-gens/directive/index.js'
      },
      port: 1492
    }
  }
]

[mikermcneil]

Err "preference" should be "precedence" (sorry, on my phone)

[mikermcneil]

so it'd be something like require('rc').getBySource()

[dominictarr]

@mikermcneil attaching the function to rc's exports is good, because then it can't collide with the retried options. I would prefer a horse name, instead of a bactrian name... what about files() or matches()?

[mikermcneil]

I like horses :p

[legodude17]

Isn't this already covered by result.configs?