= Application Settings Manager

== Summary 

This gem provides an easy and capistrano-friendly way to manage application configuration across 
multiple environments, such as development, QA, staging, production, etc.

Applications typically rely on configuration settings, such as host names, URLs, usernames and many
more. Some change between environemnts, some do not.  This gem assumes that application configuration 
is represented by a Hash of arbitrary depth, and provides convenient and compact syntax to access the 
settings through a singleton instance inside Setting class.

Configuration is stored in one or more YAML files with the top-level data structure being a Hash, 
with keys being the names of individual settings. For example, consider the following sample 
application configuration file:

 tax:
   default: 0.0
   california: 7.5
 states:
   default: 
     - 'CA'
     - 'WA'
     - 'NY'
   ship_to:
     - 'CA'
     - 'NY'
 math_pi: 3.14159526

Setting Gem provides Setting.load(..) method to load configuration from files in a way that allows 
some configuration files to override previously loaded values, and then offers a simple method API 
to access the values, for example Setting.tax(:california) or Setting.tax.  Supporting default values
in 2nd, 3rd, etc.. -level hashes is one of the advantages of using this gem.

By loading configuration from files, Setting is inherently compatible with Capistrano deployment 
methodology, where a certain set of files may become "activated" by simply sym-linking them into 
the appropriate settings folder.

Note: using example above, "1st level" hash is the one with keys "tax", "states" and "math_pi".  
2nd-level hash is, for example, the tax definition one, with keys "default" and "california".  

== Usage in Code

Once configuration is initialized using Setting#load or Setting#reload methods (see below), they can be used in 
code in the following way:

* Setting.key_name is optimized to return default value if available instead of a Hash. 
* Setting.key_name(:sub_key_name) returns a value from the 2nd level hash.
* Setting.key_name(:sub_key_name, :sub_sub_key_name) returns value from the 3rd level hash if available. The algorithm is recursive, so only the maximum method stack depth will limit the number of nested hash values you can access this way.
* Special syntax Setting[:key_name], Setting[:key_name][:sub_key_name], etc also supported. This method, however, does not support default values (see below).

Method notation is recommended over square bracket notation for acessing single values. However, square bracket notation
may be useful when you want to fetch the entire 2nd level hash that includes the default value, instead of the
default value itself.

For example, given the above YAML file, you can access the settings in your code as follows:

  Setting.tax => 0.0
  Setting.tax(:california) => 7.5
  Setting.math_pi => 3.14159526
  Setting[:math_pi] => 3.14159526
  Setting.states => [ 'CA', 'WA', 'NY' ]
  Setting.states['ship_to'] => [ 'CA', 'NY' ]

Method calling notation allows passing an array of keys for nested hashes.  It also supports default values
if provided.

  Setting.tax => 0.0

Square bracket syntax returns the actual 2nd-level hash, without any regard for a default value:

  Setting[:tax] => { 'default' => 0.0, 'california' => 7.5 } 

== Loading Settings

The gem should be initialized in your environment.rb (if using Rails), or in any other
application initialization block.  Setting.load() method is provided for loading settings, and it
can be called only once in application lifecycle, or it will throw an exception.  If you need to reload
settings completely, you can use reload() method with similar arguments.

Consider an example:

  Setting.load(:path  => "#{Rails.root}/config/settings",
               :files => ["default.yml", "environments/#{Rails.env}.yml"],
               :local => true)

The argument is a parameter hash that configures which YML files to load, and in what order, and from where.

* :path specifies the "root" folder where settings files will be loaded from
* :files is an array that lists file names relative to the :path. In the example above, settings folder contains subfolder "environments" where Rails-specific environment files are located (such as "development.yml", "staging.yml", "production.yml", etc)
* :local can be optionally specified as a true value, and if specified Setting gem will load all *.yml files that live under the :path/local folder. 

Below is list of YML files loaded in order specified in the above example, assuming that "development" is
the Rails environment, and "local" folder exists with 3 additional YML files in it:

  config/settings/default.yml
  config/settings/environments/development.yml
  config/settings/local/authorize-net.yml
  config/settings/local/paypal.yml
  config/settings/local/other.yml

Each YML file defines a ruby Hash.  During file loading, the hashes are merged, so that values loaded in early files may
be overwritten by values in subsequent files. This is deliberate and by design: it allows you to create
small "override" files for each environment, or even each machine you want to deploy to. Exactly how you split your
application settings in files is up to you.

== Nested Hashes and Default Values

MC Setting gem provides a convenient way to access nested values, including full support for the default values within
nested hashes (as of 0.1.1).

Consider the following nested hash example:

default.yml:

  services: 
    inventory:
      url: http://ims.mycompany.com:3443/inventory_manager
      name: Inventory Management
    shipping:
      url: http://ship.mycompany.com:3443/shipper
      name: Shipping

  Setting.load(:files => ['default.yml'], :path => ...)

  Setting.tax(:inventory)       => { :url => "http://localhost:3443/inventory_manager" :name => "Inventory Management"}
  Setting.tax(:inventory, :url) => "http://localhost:3443/inventory_manager"

staging.yml is changing URLs for services so they work in the staging environment.  Service URLs have been changed for
staging only:

  services: 
    inventory:
      url: http://localhost:8009/inventory_manager
    shipping:
      url: http://localhost:8008/shipper

  Setting.load(:files => ['default.yml', 'staging.yml'], :path => ...)

  Setting.tax(:inventory)       => { :url => "http://localhost:8009/inventory_manager" :name => "Inventory Management"}
  Setting.tax(:inventory, :url) => "http://localhost:8008/inventory_manager"

== Capistrano Recommendations

TBD.

== Copyright

Copyright 2010 (c) ModCloth Inc.

Authors: 2010 Edwin Cruz & Konstantin Gredeskoul

See LICENSE.txt for further details.