= Application Settings Manager

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 makes managing this hierarchy of
settings values easy and provides convenient and compact syntax to access the settings.

Configuration is stored in YAML files, in the following format, with it's top level structure being a hash with keys being the names of individual settings. For example:

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

etc.

== Usage 

Once settings are initialized (see below), they can be used in code in the following way:

* Setting.key_name is optimized to return default value if available.
* Setting.key_name(:sub_key_name) returns value from the 2nd level hash if available.
* Setting[:key_name] & Setting['key_name'] return entire 2nd-level hash without any regard for whether default value exists.

For example, given the above YAML file:

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

The following usage is supported for backwards compatibility, but is deprecated and should
not be used for new projects:

  Setting.available_settings['key_name']
  Setting.available_settings['key_name']['sub_key_name']

== Settings Loading

This gem should be initialized in your environment.rb (if using Rails), or in any other
application initialization block.

Consider an example:

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

This parameter hash tells Setting to load settings hashes, in order, from the following
files under "development" (assuming you have two files "custom.yml" and "secret.yml" under your
RAILS_ROOT/config/settings/local folder):

  config/settings/default.yml
  config/settings/environments/development.yml
  config/settings/local/custom.yml
  config/settings/local/secret.yml

The following is the sequence of loading explained:

* Read all files in :files list in order, and load their settings.
* Last file loaded overrides recursively previous value (if already exist).
* Load all #{path}/local/*.yml files to Settings, overriding recursively common keys. Files are loaded in order sorted by name.

== Copyright

Copyright 2010 (c) ModCloth Inc.

Authors: 2010 Edwin Cruz & Konstantin Gredeskoul

See LICENSE.txt for further details.