mc-settings 0.1.1 → 0.1.2

data/README.rdoc

@@ -1,13 +1,18 @@
 = 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 makes managing this hierarchy of
-settings values easy and provides convenient and compact syntax to access the settings.
+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 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:
+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
@@ -22,55 +27,122 @@ Configuration is stored in YAML files, in the following format, with it's top le
      - 'NY'
  math_pi: 3.14159526
 
-etc.
+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 
+== Usage in Code
 
-Once settings are initialized (see below), they can be used in code in the following way:
+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.
-* 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.
+* 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).
 
-For example, given the above YAML file:
+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[:tax] => { 'default' => 0.0, 'california' => 7.5 } 
+  Setting.math_pi => 3.14159526
+  Setting[:math_pi] => 3.14159526
   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:
+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.available_settings['key_name']
-  Setting.available_settings['key_name']['sub_key_name']
+  Setting[:tax] => { 'default' => 0.0, 'california' => 7.5 } 
 
-== Settings Loading
+== Loading Settings
 
-This gem should be initialized in your environment.rb (if using Rails), or in any other
-application initialization block.
+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(:files => ["default.yml", "environments/#{Rails.env}.yml"],
-               :path  => "#{Rails.root}/config/settings",
+  Setting.load(:path  => "#{Rails.root}/config/settings",
+               :files => ["default.yml", "environments/#{Rails.env}.yml"],
                :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):
+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/custom.yml
-  config/settings/local/secret.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"
 
-The following is the sequence of loading explained:
+== Capistrano Recommendations
 
-* 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.
+TBD.
 
 == Copyright
 

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

data/lib/setting.rb

@@ -111,7 +111,7 @@ class Setting
     if block_given?
       v = yield(v, args)
     end
-    
+
     if v.is_a?(Fixnum) && bool
       v.to_i > 0
     else
@@ -123,7 +123,7 @@ class Setting
   # contains 'default' value, or just 1 element.
   
   def collapse_hashes(v, args)
-    if v.is_a?(Hash)
+    out = if v.is_a?(Hash)
       if args.empty?
         if v.has_key?("default")
           v['default'].nil? ? "" : v['default']
@@ -133,11 +133,17 @@ class Setting
           v
         end
       else
-        v[args[0].to_s]
+        v[args.shift.to_s]
       end
     else
       v
     end
+
+    if out.is_a?(Hash)
+      collapse_hashes(out, args)
+    else
+      out
+    end
   end
   
   def loaded?

data/mc-settings.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{mc-settings}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Edwin Cruz", "Colin Shield"]
-  s.date = %q{2011-01-14}
+  s.date = %q{2011-01-18}
   s.description = %q{implement custom keys indenendently of environment}
   s.email = %q{rubydev@modcloth.com}
   s.extra_rdoc_files = [
@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
     "lib/mc-settings.rb",
     "lib/setting.rb",
     "mc-settings.gemspec",
+    "spec/fixtures/joes-colors.yml",
     "spec/fixtures/sample.yml",
     "spec/mc_settings_spec.rb",
     "spec/spec_helper.rb",

data/spec/fixtures/joes-colors.yml

@@ -0,0 +1,9 @@
+color:
+  pants:
+    favorite:
+      :orange
+  shorts:
+    favorite:
+      :white
+    default:
+      :stripes

data/spec/fixtures/sample.yml

@@ -14,3 +14,22 @@ boolean_true:
 boolean_false:
   default: false
   negated: true
+color:
+  default:
+    :grey
+  pants:
+    default:
+      :purple
+    favorite:
+      :red
+    school:
+      :blue
+  shorts:
+    default:
+      :plaid
+    favorite:
+      :yellow
+    school:
+      :black
+     
+

data/spec/mc_settings_spec.rb

@@ -6,8 +6,8 @@ describe Setting do
     before :each do
       stub_setting_files
       Setting.reload(
-          :files => ["default.yml", "environments/test.yml"],
           :path  => "config/settings",
+          :files => ["default.yml", "environments/test.yml"],
           :local => true)
     end
 
@@ -22,15 +22,11 @@ describe Setting do
     end
 
     it "handles multiple values" do
-      Setting['six'].should == {"default"=>"default value", "extra"=>"recursively overriden", "deep_level"=>{"value"=>"even deeper level"}}
+      Setting[:six].should == {"default"=>"default value", "extra"=>"recursively overriden", "deep_level"=>{"value"=>"even deeper level"}}
       Setting.available_settings['six']['default'].should == "default value"
       Setting.seven.should == "seven from custom"
     end
 
-    it "should support symbols as keys" do
-      Setting[:six].should == {"default"=>"default value", "extra"=>"recursively overriden"}
-    end
-
     it "handles default key" do
       Setting.default_setting.should == 1
       Setting['seven']['default'].should == "seven from custom"
@@ -50,7 +46,7 @@ describe Setting do
 
     it "should merge keys recursivelly" do
       Setting.six(:extra).should == "recursively overriden"
-      Setting.six(:deep_level)[:value] = "even deeper level"
+      Setting.six(:deep_level, :value).should == "even deeper level"
     end
 
     it "should create keys if it does not exist" do
@@ -62,45 +58,35 @@ describe Setting do
     it "should keep its values" do
       3.times do |time|
         Thread.new {
-          Proc.new{
-            Setting.available_settings.shoud_not be_empty
-          }
+          Setting.available_settings.shoud_not be_empty
         }
       end
     end
   end
 
-  context "When running inside a proc" do
-    it "should keep its values" do
-      Proc.new{
-        Setting.available_settings.shoud_not be_empty
-      }
-    end
-  end
-
   context "Test from file" do
     before :each do
       Setting.reload(
-          :files => ['sample.yml'],
-          :path  => File.join(File.dirname(__FILE__)) + '/fixtures'
+         :path  => File.join(File.dirname(__FILE__)) + '/fixtures',
+         :files => ['sample.yml']
       )
     end
 
     it 'should support [] syntax' do
       Setting['tax']['default'].should == 0.0
-      Setting['tax'].should == {'default' => 0.0, 'california' => 7.5}
+      Setting['tax'].should == { 'default' => 0.0, 'california' => 7.5 }
     end
 
     it 'should support method invocation syntax' do
       Setting.tax.should == 0.0
 
-      Setting.tax(:default).should == Setting.tax
-      Setting.tax('default').should == Setting.tax
-      Setting.tax(:california).should == 7.5
+      Setting.tax(:default).should     == Setting.tax
+      Setting.tax('default').should    == Setting.tax
+      Setting.tax(:california).should  == 7.5
 
-      Setting.states.should == ['CA', 'WA', 'NY']
-      Setting.states(:default).should == Setting.states
-      Setting.states(:ship_to).should == ['CA', 'NY']
+      Setting.states.should            == ['CA', 'WA', 'NY']
+      Setting.states(:default).should  == Setting.states
+      Setting.states(:ship_to).should  == ['CA', 'NY']
     end
 
     it 'should correctly process Boolean values' do
@@ -110,6 +96,28 @@ describe Setting do
       Setting.boolean_false?(:default).should be(false)
       Setting.boolean_false?(:negated).should be(true)
     end
+  end
+
+  context "Test recursive overrides and nested hashes" do
+    before :each do
+      Setting.reload(
+         :path  => File.join(File.dirname(__FILE__)) + '/fixtures',
+         :files => ['sample.yml', 'joes-colors.yml']
+      )
+    end
+
+    it 'should override colors with Joes and support nested hashes' do
+      Setting.color.should == :grey # default
+      Setting.color(:pants).should == :purple # default
+
+      Setting.color(:pants, :school).should == :blue # in sample
+      Setting.color(:pants, :favorite).should == :orange # joes override
+
+      Setting.color(:shorts, :school).should == :black # in sample
+      Setting.color(:shorts, :favorite).should == :white # joe's override
+
+      Setting.color(:shorts).should == :stripes # joe's override of default
+    end
 
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mc-settings
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: false
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Edwin Cruz
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-14 00:00:00 -08:00
+date: 2011-01-18 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -113,6 +113,7 @@ files:
 - lib/mc-settings.rb
 - lib/setting.rb
 - mc-settings.gemspec
+- spec/fixtures/joes-colors.yml
 - spec/fixtures/sample.yml
 - spec/mc_settings_spec.rb
 - spec/spec_helper.rb