h1. Configoro -- Environment-specific configuration data for Rails apps

| *Author* | Tim Morgan |
| *Version* | 1.1 (May 9, 2011) |
| *License* | Released under the MIT license. |

h2. About

Pretty much every Rails app out there needs to store environment-specific
configuration data: API URLs, Memcache settings, AWS keys, etc. The "quick fix"
approach is usually to dump this information in, e.g., @development.rb@ as
constants, like @MAILCHIMP_API_URL@. This creates cluttered and unorganized
environment files.

Configoro creates a configuration object that can be accessed as both a hash and
struct. It stores common configuration data merged with environment-specific
data.

The data is read from YAML files stored alongside the environment files.

h2. Installation

To use this gem, simply add

<pre><code>
gem 'configoro'
</code></pre>

to your Gemfile, then run

<pre><code>
rails generate configoro
</code></pre>

to install some default configuration files. Edit these new files with your
configuration data.

h2. Usage

Assume your application namespace is @MyApp@ (which is what it
would be if you had created your Rails project using @rails new my_app@). You
can find your namespace in your @config/application.rb@ file.

In this case, you would access your configuration using the
@MyApp::Configuration@ object. You can access it as an indifferent hash

<pre><code>
MyApp::Configuration[:mailchimp_api_url]
MyApp::Configuration['mailchimp_api_url']
</code></pre>

or as a struct.

<pre><code>
MyApp::Configuration.mailchimp_api_url
</code></pre>

If you include any hashes in your configuration YAML files, they will also be
accessible as indifferent hashes or structs:

<pre><code>
MyApp::Configuration.memcache.timeout
MyApp::Configuration[:memcache]['timeout']
MyApp::Configuration['memcache'].timeout
</code></pre>

h2. Configuration Files

Configuration is stored within the @config/environments@ directory of your Rails
app. Files ending in ".yml" are loaded from the @common/@ subdirectory and a
subdirectory named after the current environment.

Each file goes into its own hash in the configuration. For example, if you
placed a file called @memcache.yml@ within @config/environments/development@,
you would be able to access your Memcache timeout using
@MyApp::Configuration.memcache.timeout@.

h3. Custom Configuration Locations

If you need to do your own configuration loading, you can do so using the
{Configoro::Hash#<<} method. For example, you could place the following in a
Ruby file under @config/initializers@:

<pre><code>
MyApp::Configuration << "path/to/additional/yaml_file.yml"
MyApp::Configuration << { 'additional' => 'configuration' }

MyApp::Configuration.additional #=> 'configuration'
</code></pre>

Note that if you pass a path to a YAML file, a key will be created to store the
contents of the file, named after the file name. If the key already exists, the
new values will be deep-merged into the existing values.

In the example above, the data in the @yaml_file.yml@ file can be accessed using
@MyApp::Configuration.yaml_file@.