mc-settings 0.0.1 → 0.1.0

data/README.rdoc

@@ -1,53 +1,82 @@
-= Settings
+= Application Settings Manager
 
-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.
 
-== Usage in Rails
-Settings conventions
-    key_name:
-      default: value
-    key_name: value
-    multiples_values:
-      default: default
-      another_value: another_default
+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:
 
-  config/settings/default.yml
-  config/settings/environments/development.yml
-  config/settings/environments/production.yml
-  config/settings/local/custom.yml
-  config/settings/local/verysecret.yml
+ tax:
+   default: 0.0
+   california: 7.5
+ states:
+   default: 
+     - 'CA'
+     - 'WA'
+     - 'NY'
+   ship_to:
+     - 'CA'
+     - 'NY'
+ math_pi: 3.14159526
 
-  Setting.load(:files => ["default.yml", "environments/#{Rails.env}.yml"],
-             :path   => "#{Rails.root}/config/settings",
-             :local => true)
+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.key_name
   Setting.available_settings['key_name']
-  Setting.available_settings['key_name']['another_value']
-  Setting['key_name']
-  Setting[:key_name]
-  Setting['multiples_values']['another_value']
+  Setting.available_settings['key_name']['sub_key_name']
 
+== Settings Loading
 
-This means:
-  * Read default.yml, and load all setings in Setting object
-  * Override specific keys depending on rails environment
-  * Apply all #{path}/local/*.yml files to Settings, overriding common keys
+This gem should be initialized in your environment.rb (if using Rails), or in any other
+application initialization block.
 
+Consider an example:
 
-== Contributing to mc-settings
- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+  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 previous value (if already exist).
+* Load all #{path}/local/*.yml files to Settings, overriding common keys. Files are loaded in order sorted by name.
 
 == Copyright
 
-Copyright (c) 2010 Edwin Cruz. See LICENSE.txt for
-further details.
+Copyright 2010 (c) ModCloth Inc.
+
+Authors: 2010 Edwin Cruz & Konstantin Gredeskoul
+
+See LICENSE.txt for further details.
 

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.0

data/lib/mc-settings.rb

@@ -1 +1 @@
-require 'setting'
+require File.expand_path(File.dirname(__FILE__)) + '/setting'

data/lib/setting.rb

@@ -1,84 +1,159 @@
 require 'singleton'
+require 'yaml'
 class Setting
-  class SettingNotFound < RuntimeError; end
-  class SettingFileError < RuntimeError; end
+  class NotFound < RuntimeError; end
+  class FileError < RuntimeError; end
+  class AlreadyLoaded < RuntimeError; end
 
   include Singleton
 
-  def self.reload params = {}
-    @available_settings = {}
-    self.load params
-  end
+  attr_reader :available_settings
 
-  def self.available_settings
-    self.instance ? @available_settings : {}
+  # This method can be called only once.
+  #
+  # Parameter hash looks like this:
+  #
+  #  {  :files => [ "file1.yml", "file2.yml", ...],
+  #     :path  => "/var/www/apps/my-app/current/config/settings",
+  #     :local => true }
+  #
+  # If :local => true is set, we will load all *.yml files under :path/local directory
+  # after all files in :files have been loaded.  "Local" settings thus take precedence
+  # by design.  See README for more details.
+  #
+  def self.load(args = {})
+    raise AlreadyLoaded.new('Settings already loaded') if self.instance.loaded?
+    self.instance.load(args)
   end
 
-  # get a setting value by [] notation
-  def self.[](name)
-    self.check_value(name.to_s)
-    self.value_for(name.to_s)
+  def self.reload(args = {})
+    self.instance.load(args)
   end
 
+  # In Method invocation syntax we collapse Hash values
+  # and return a single value if 'default' is found among keys
+  # or Hash has only one key/value pair.
+  #
+  # For example, if the YML data is:
+  # tax:
+  #   default: 0.0
+  #   california: 7.5
+  #
+  # Then calling Setting.tax returns "0.0""
+  #
+  # This is the preferred method of using settings class.
+  #
   def self.method_missing(method, *args, &block)
-    # see if this method is defined above us in the hierarchy
-    super(method, *args)
-  rescue
-    name = method.to_s
-    if name[-1, 1] == "?"
-      name.chomp!('?')
-      self[name]['default'].to_i > 0
-    else
-      self[name]
+    self.instance.value_for(method, args) do |v, args|
+      self.instance.collapse_hashes(v, args)
     end
   end
 
+  # In [] invocation syntax, we return settings value 'as is' without
+  # Hash conversions.
+  #
+  # For example, if the YML data is:
+  # tax:
+  #   default: 0.0
+  #   california: 7.5
+  #
+  # Then calling Setting['tax'] returns
+  #   { 'default' => "0.0", 'california' => "7.5"}
+
+  def self.[](value)
+    self.instance.value_for(value)
+  end
+
+  # <b>DEPRECATED:</b> Please use <tt>method accessors</tt> instead.
+  def self.available_settings
+    self.instance.available_settings
+  end
+
+  #=================================================================
+  # Instance Methods
+  #=================================================================
+
   def initialize
     @available_settings ||= {}
   end
 
-  class << self
-    def has_key?(key)
-      @available_settings.has_key?(key)
+  def has_key?(key)
+    @available_settings.has_key?(key) ||
+      (key[-1,1] == '?' && @available_settings.has_key?(key.chop))
+  end
+
+  def value_for(key, args = [])
+    name = key.to_s
+    raise NotFound.new("#{name} was not found") unless has_key?(name)
+    bool = false
+    if name[-1,1] == '?'
+      name.chop!
+      bool = true
+    end
+
+    v = @available_settings[name]
+    if block_given?
+      v = yield(v, args)
+    end
+    
+    if v.is_a?(Fixnum) && bool
+      v.to_i > 0
+    else
+      v
     end
+  end
 
-    def value_for(value)
-      v = @available_settings[value]
-      if v.is_a?(Hash) && v.size > 1
-        v
-      elsif v.is_a?(Hash) && v.has_key?("default")
-        v['default'].nil? ? "" : v['default']
+  # This method performs collapsing of the Hash settings values if the Hash
+  # contains 'default' value, or just 1 element.
+  
+  def collapse_hashes(v, args)
+    if v.is_a?(Hash)
+      if args.empty?
+        if v.has_key?("default")
+          v['default'].nil? ? "" : v['default']
+        elsif v.keys.size == 1
+          v.values.first
+        else
+          v
+        end
       else
-        v
+        v[args[0].to_s]
       end
+    else
+      v
     end
   end
+  
+  def loaded?
+    @loaded
+  end
+
+  def load(params)
+    # reset settings hash
+    @available_settings = {}
+    @loaded = false
 
-  def self.load(params)
     files = []
-    path  = params[:path]
+    path  = params[:path] || Dir.pwd
     params[:files].each do |file|
       files << File.join(path, file)
     end
+
     if params[:local]
       files << Dir.glob(File.join(path, 'local', '*.yml'))
     end
-    @available_settings ||= {}
+
     files.flatten.each do |file|
       begin
         @available_settings.merge!(YAML::load(File.open(file)) || {}) if File.exists?(file)
       rescue Exception => e
-        raise SettingNotFound.new("Error parsing file #{file}, with: #{e.message}")
+        raise FileError.new("Error parsing file #{file}, with: #{e.message}")
       end
     end
+
+    @loaded = true
     @available_settings
   end
 
-  private
-
-  def self.check_value(name)
-    raise RuntimeError.new("settings are not yet initialized") unless self.instance
-    raise SettingNotFound.new("#{name} not found") unless self.has_key?(name)
-  end
 
-end
+end

data/mc-settings.gemspec

@@ -0,0 +1,71 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{mc-settings}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Edwin Cruz", "Colin Shield"]
+  s.date = %q{2010-12-28}
+  s.description = %q{implement custom keys indenendently of environment}
+  s.email = %q{rubydev@modcloth.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/mc-settings.rb",
+    "lib/setting.rb",
+    "mc-settings.gemspec",
+    "spec/fixtures/sample.yml",
+    "spec/mc_settings_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/support/settings_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/modcloth/mc-settings}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Manage settings per environment}
+  s.test_files = [
+    "spec/mc_settings_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/support/settings_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<ruby-debug>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<ruby-debug>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<ruby-debug>, [">= 0"])
+  end
+end
+

data/spec/fixtures/sample.yml

@@ -0,0 +1,16 @@
+tax:
+  default: 0.0
+  california: 7.5
+states:
+  default: 
+   - 'CA'
+   - 'WA'
+   - 'NY'
+  ship_to:
+   - 'CA'
+   - 'NY'
+boolean_true:
+  default: 4
+boolean_false:
+  default: false
+  negated: true

data/spec/mc_settings_spec.rb

@@ -2,7 +2,7 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 describe Setting do
   subject { Setting }
 
-  context "Test environment" do
+  context "Test with stubs" do
     before :each do
       stub_setting_files
       Setting.reload(
@@ -10,6 +10,7 @@ describe Setting do
           :path  => "config/settings",
           :local => true)
     end
+    
     it 'should return test specific values' do
       Setting.available_settings['one'].should == "test"
       Setting.one.should == "test"
@@ -30,9 +31,10 @@ describe Setting do
     it "should support symbols as keys" do
       Setting[:six].should == {"default"=>"default value", "extra"=>"extra"}
     end
+
     it "handles default key" do
       Setting.default_setting.should == 1
-      Setting['seven'].should == "seven from custom"
+      Setting['seven']['default'].should == "seven from custom"
     end
 
     it "should handle empty strings" do
@@ -47,4 +49,39 @@ describe Setting do
       Setting.flag_false.should be(false)
     end
   end
+
+  context "Test from file" do
+    before :each do
+      Setting.reload(
+         :files => ['sample.yml'],
+         :path => File.join(File.dirname(__FILE__)) + '/fixtures'
+      )
+    end
+
+    it 'should support [] syntax' do
+      Setting['tax']['default'].should == 0.0
+      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.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
+      Setting.boolean_true?.should be(true)
+      Setting.boolean_true.should == 4
+      Setting.boolean_false?.should be(false)
+      Setting.boolean_false?(:default).should be(false)
+      Setting.boolean_false?(:negated).should be(true)
+    end
+
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mc-settings
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: false
   segments: 
   - 0
-  - 0
   - 1
-  version: 0.0.1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Edwin Cruz
@@ -16,13 +16,14 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-17 00:00:00 -08:00
+date: 2010-12-28 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  type: :development
+  name: rspec
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -31,12 +32,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
-  version_requirements: *id001
+  requirement: *id001
 - !ruby/object:Gem::Dependency 
-  name: bundler
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  type: :development
+  name: bundler
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -47,12 +48,12 @@ dependencies:
         - 0
         - 0
         version: 1.0.0
-  type: :development
-  version_requirements: *id002
+  requirement: *id002
 - !ruby/object:Gem::Dependency 
-  name: jeweler
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  type: :development
+  name: jeweler
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -63,12 +64,12 @@ dependencies:
         - 5
         - 1
         version: 1.5.1
-  type: :development
-  version_requirements: *id003
+  requirement: *id003
 - !ruby/object:Gem::Dependency 
-  name: rcov
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  type: :development
+  name: rcov
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -77,12 +78,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
-  version_requirements: *id004
+  requirement: *id004
 - !ruby/object:Gem::Dependency 
-  name: ruby-debug
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  type: :development
+  name: ruby-debug
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -91,8 +92,7 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
-  version_requirements: *id005
+  requirement: *id005
 description: implement custom keys indenendently of environment
 email: rubydev@modcloth.com
 executables: []
@@ -112,6 +112,8 @@ files:
 - VERSION
 - lib/mc-settings.rb
 - lib/setting.rb
+- mc-settings.gemspec
+- spec/fixtures/sample.yml
 - spec/mc_settings_spec.rb
 - spec/spec_helper.rb
 - spec/support/settings_helper.rb