yacht 0.1.0

data/Gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gemspec
+
+gem 'rake'

data/README.rdoc

@@ -0,0 +1,73 @@
+= Yacht
+
+Yacht is an application configuration gem that lets you define settings for multiple environments in YAML files. It is similar to AppConfig[https://github.com/cjbottaro/app_config] with additional features like:
+* use of ClassyStruct for improved performance over OpenStruct
+* protection of sensitive settings by specifying a whitelist in a YAML file
+* easy override of nested keys (not pretty with YAML references)
+
+== Installation
+
+* <b>Rails</b>:
+  Add this to your Gemfile and run the +bundle+ command.
+
+    gem "yacht"
+
+* Outside of rails, just require the gem as usual:
+
+    require 'rubygems'
+    require 'yacht'
+
+== Getting Started
+
+=== Step 1: YAML files
+
+First create two (or more) YAML files in the same directory to define your settings:
+
+    # config/yacht/base.yml (required)
+    production:
+      cdn_host: 1.2.3.4
+      super_secret_info:
+        aws_key: foofoo
+        twitter_key: barbar
+    test:
+      cdn_host: localhost
+      super_secret_info:
+        # you can safely overwrite a single value in a nested key
+        # YAML references (& and *) don't let you do this
+        #   see https://gist.github.com/979804 for an explanation
+        aws_key: bazbaz
+
+    # config/yacht/whitelist.yml (required)
+    # any keys specified here can be used as a whitelist filter:
+    #   YachtLoader.to_hash(:apply_whitelist? => true)
+    #   (by default the whitelist is ignored)
+    - super_secret_info
+
+    # config/yacht/local.yml (optional)
+    # any values set in local.yml will override values set in base.yml
+    # useful for development and testing
+    production:
+      cdn_host: localhost
+
+=== Step 2: Define a constant
+
+* <b>Rails</b>:
+    # config/initializers/01_yacht.rb
+    # Define a constant that will store all settings
+    # looks for the following YAML files:
+    #   * config/yacht/base.yml
+    #   * config/yacht/local.yml
+    #   * config/yacht/whitelist.yml
+    Yacht = YachtLoader.to_classy_struct
+    # now you can access any key set in your YAML files with:
+    #   Yacht.my_key
+
+* Outside of rails, you need to tell +YachtLoader+ where your YAML files are stored, and what environment you want to use.
+    YachtLoader.dir          = '/path/to/YAML/dir'
+    YachtLoader.environment  = 'my_environment'
+    Yacht                    = YachtLoader.to_classy_struct
+
+
+== How it works
+
+Currently, the +Yacht+ gem defines a class called +YachtLoader+ that will read your YAML files and output them as a regular +Hash+ or a +ClassyStruct+ . Then you use <tt>YachtLoader#to_classy_struct</tt> (or <tt>YachtLoader#to_hash</tt>) to define a constant. You can name the constant whatever you like, but you should use +Yacht+. This is because a planned feature is to have +Yacht+ defined when the gem is required and have everything namespaced under a single +Yacht+ class.

data/Rakefile

@@ -0,0 +1,9 @@
+# encoding: utf-8
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+Bundler::GemHelper.install_tasks
+
+Dir['gem_tasks/**/*.rake'].each { |rake| load rake }
+
+task :default => [:spec]

data/lib/monkeypatches/hash.rb

@@ -0,0 +1,24 @@
+if !Hash.instance_methods.include?(:deep_merge)
+  class Hash
+    # copied from ActiveSupport::CoreExtensions::Hash::DeepMerge 2.3.8
+    def deep_merge(other_hash)
+      self.merge(other_hash) do |key, oldval, newval|
+        oldval = oldval.to_hash if oldval.respond_to?(:to_hash)
+        newval = newval.to_hash if newval.respond_to?(:to_hash)
+        oldval.class.to_s == 'Hash' && newval.class.to_s == 'Hash' ? oldval.deep_merge(newval) : newval
+      end
+    end
+  end
+end
+
+if !Hash.instance_methods.include?(:slice)
+  class Hash
+    # copied from http://as.rubyonrails.org/classes/ActiveSupport/CoreExtensions/Hash/Slice.html
+    def slice(*keys)
+      allowed = Set.new(respond_to?(:convert_key) ? keys.map { |key| convert_key(key) } : keys)
+      hash = {}
+      allowed.each { |k| hash[k] = self[k] if has_key?(k) }
+      hash
+    end
+  end
+end

data/lib/yacht.rb

@@ -0,0 +1,12 @@
+# This file is named yacht.rb 
+# so that Bundler will automatically load YachtLoader
+#
+# In the future, once we figure out how to integrate ClassyStruct,
+# YachtLoader will be renamed to Yacht
+
+require "yacht_loader/base"
+require "yacht_loader/classy_struct"
+require "yacht_loader/version"
+
+require "yacht_loader/rails" if Object.const_defined?(:Rails)
+require 'monkeypatches/hash'

data/lib/yacht_loader/base.rb

@@ -0,0 +1,112 @@
+# TODO: Rename YachtLoader to Yacht and somehow incorporate ClassyStruct
+
+class YachtLoader
+  class LoadError < StandardError
+  end
+
+  class << self
+    def environment
+      @environment ||= 'default'
+    end
+    attr_writer :environment
+
+    def dir
+      @dir ||= File.join( File.dirname(__FILE__), 'yacht')
+    end
+    attr_writer :dir
+
+    def full_file_path_for_config(config_type)
+      File.join( self.dir, "#{config_type}.yml" )
+    end
+
+    def config_file_for(config_type)
+      raise LoadError.new "#{config_type} is not a valid config type" unless valid_config_types.include?(config_type.to_s)
+
+      full_file_path_for_config(config_type)
+    end
+
+    def valid_config_types
+      %w( base local whitelist )
+    end
+
+    def all
+      chain_configs(base_config, self.environment).deep_merge(local_config)
+    end
+
+    def to_hash(opts={})
+     opts[:apply_whitelist?] = false unless opts.has_key?(:apply_whitelist?)
+     self.environment = opts[:env] if opts.has_key?(:env)
+
+     if opts[:apply_whitelist?]
+       all.slice(*whitelist)
+     else
+       all
+     end
+   end
+
+    def whitelist
+      load_config_file(:whitelist, :expect_to_load => Array) || begin
+        raise LoadError.new("Couldn't load whitelist")
+      end
+    end
+
+    def base_config
+      load_config_file(:base) || begin
+        raise LoadError.new("Couldn't load base config")
+      end
+    end
+
+    def local_config
+      load_config_file(:local, :require_presence? => false) || {}
+    end
+
+  protected
+    def load_config_file(file_type, opts={})
+      # by default, expect a Hash to be loaded
+      expected_class    = opts[:expect_to_load] || Hash
+
+      # by default, raise error if file missing or empty
+      presence_required = if opts.has_key?(:require_presence?)
+                            opts[:require_presence?]
+                          else
+                            true
+                          end
+
+      file_name = self.config_file_for(file_type)
+
+      loaded =  if File.exists?(file_name)
+                  YAML.load( File.read(file_name) )
+                else
+                  nil
+                end
+
+      # an empty YAML file will be converted to boolean false
+      raise LoadError.new "#{file_name} cannot be empty" if presence_required && loaded === false
+
+      # YAML contained the wrong type
+      raise LoadError.new "#{file_name} must contain #{expected_class} (got #{loaded.class})" if loaded && !loaded.is_a?(expected_class)
+
+      loaded
+    rescue => e
+      # don't do anything to our own custom errors
+      if e.is_a? YachtLoader::LoadError
+        raise e
+      else
+        # convert other errors to YachtLoader::LoadError
+        raise LoadError.new "ERROR: loading config file: '#{file_type}': #{e}"
+      end
+    end
+
+    def chain_configs(config, env)
+      raise LoadError.new "environment '#{env}' does not exist" unless config.has_key?(env)
+
+      parent = if config[env]['_parent']
+                 chain_configs(config, config[env]['_parent'])
+               else
+                 config['default'] || {}
+               end
+
+      parent.deep_merge(config[env])
+    end
+  end
+end

data/lib/yacht_loader/classy_struct.rb

@@ -0,0 +1,15 @@
+require 'classy_struct'
+
+class YachtLoader
+  class << self
+    def classy_struct_instance
+      @classy_struct_instance ||= ClassyStruct.new
+    end
+
+    def to_classy_struct(opts={})
+      classy_struct_instance.new( self.to_hash(opts) )
+    rescue StandardError => e
+      raise LoadError.new("Error creating ClassyStruct: #{e.message}")
+    end
+  end
+end

data/lib/yacht_loader/rails.rb

@@ -0,0 +1,16 @@
+class YachtLoader
+  class << self
+    # use the current rails environment by default
+    def environment
+      @environment ||= Rails.env
+    end
+
+    def dir
+      @dir ||= Rails.root.join('config', 'yacht')
+    end
+
+    def full_file_path_for_config(config_type)
+      dir.join("#{config_type}.yml")
+    end
+  end
+end

data/lib/yacht_loader/version.rb

@@ -0,0 +1,3 @@
+class YachtLoader
+  VERSION = "0.1.0"
+end

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--color
+--format nested

data/spec/spec_helper.rb

@@ -0,0 +1,115 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+$:.unshift(File.dirname(__FILE__))
+
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+
+# ==============
+# = SimpleCov! =
+# ==============
+require 'simplecov'
+SimpleCov.start
+
+require 'yacht'
+
+Spec::Runner.configure do |config|
+  config.after :each do
+    YachtLoader.environment = nil
+    YachtLoader.dir         = nil
+    YachtLoader.instance_variable_set(:@config_file_names, nil)
+  end
+end
+
+BASE_CONFIG_FILE = <<EOF
+default:
+  name: default
+  defaultkey: defaultvalue
+  dog: schnauzer
+  hashkey:
+    foo: bar
+    baz: wurble
+    xyzzy: thud
+an_environment:
+  name: an_environment
+  hashkey:
+    baz: yay
+  dog: terrier
+a_child_environment:
+  _parent: an_environment
+  name: a_child_environment
+  hashkey:
+    foo: kung
+test:
+  baloney: delicious
+EOF
+
+WHITELIST_CONFIG_FILE = <<EOF
+- defaultkey
+- hashkey
+EOF
+
+EMPTY_WHITELIST_CONFIG_FILE = <<EOF
+EOF
+
+INVALID_WHITELIST_CONFIG_FILE = <<EOF
+somenonsenseorother
+EOF
+
+LOCAL_CONFIG_FILE = <<EOF
+localkey: localvalue
+EOF
+
+EMPTY_LOCAL_CONFIG_FILE = <<EOF
+EOF
+
+INVALID_LOCAL_CONFIG_FILE = <<EOF
+someinvalidstufforother
+EOF
+
+
+# ===================================
+# = Helpers to mock file operations =
+# ===================================
+def banish_config_file_from_prefix(prefix)
+  file_name = YachtLoader.config_file_for(prefix)
+  banish_file(file_name)
+end
+
+# shortcut to mock config file
+def conjure_config_file_from_prefix(prefix, file_contents=nil)
+  file_name     = YachtLoader.config_file_for(prefix)
+  file_contents ||= "#{prefix.upcase}_CONFIG_FILE".constantize
+
+  conjure_file(file_name, file_contents)
+end
+
+def conjure_bad_config_file_from_prefix(prefix)
+  file_name     = "#{prefix}_config_file"
+  file_contents = file_name.upcase.constantize
+
+  conjure_file(file_name, file_contents)
+end
+
+# mock file existence & contents
+def conjure_file(file_name, file_contents)
+  File.stub!(:exists?).with(file_name).and_return true
+  File.stub!(:read).with(file_name).and_return file_contents
+end
+
+# mock file non-existence
+def banish_file(file_name)
+  File.stub!(:exists?).with(file_name).and_return(false)
+  File.stub!(:read).with(file_name).and_raise Errno::ENOENT.new("No such file or directory - #{file_name}")
+end
+
+# ================================================
+# = Railsy helper to turn strings into constants =
+# ================================================
+if !String.instance_methods.include?(:constantize)
+  class String
+    def constantize   # NOT as awesome as ActiveSupport::Inflector#constantize
+      Object.const_get(self)
+    end
+  end
+end

data/spec/yacht_loader/base_spec.rb

@@ -0,0 +1,179 @@
+require 'spec_helper'
+
+describe YachtLoader do
+  before(:each) do
+    # mock existence and content of files to avoid file system in specs
+    %w(base whitelist local).each do |prefix|
+      conjure_config_file_from_prefix(prefix)
+    end
+
+    # stub bad config files to check error handling
+    %w(empty_whitelist invalid_whitelist empty_local invalid_local).each do |baddie|
+      conjure_bad_config_file_from_prefix(baddie)
+    end
+  end
+
+  it "raises an error if base config file is missing" do
+    banish_config_file_from_prefix('base')
+
+    expect {
+      YachtLoader.to_hash
+    }.to raise_error( YachtLoader::LoadError, /Couldn't load base config/)
+  end
+
+  context "whitelist" do
+    it "loads keys into an Array" do
+      YachtLoader.whitelist.should == ["defaultkey", "hashkey"]
+    end
+
+    it "returns all keys by default, ignoring whitelist" do
+      YachtLoader.environment = 'default'
+      YachtLoader.to_hash.keys.should include("defaultkey", "hashkey")
+    end
+
+    it "only returns keys included in whitelist when :apply_whitelist? option is true" do
+      YachtLoader.environment = 'default'
+      YachtLoader.to_hash(:apply_whitelist? => true).keys.should  == ["defaultkey", "hashkey"]
+    end
+
+    context "config file" do
+      it "raises an error if missing and whitelist is applied" do
+        banish_config_file_from_prefix('whitelist')
+
+        expect {
+          YachtLoader.to_hash(:apply_whitelist? => true)
+        }.to raise_error( YachtLoader::LoadError, /Couldn't load whitelist/)
+      end
+
+      it "raises an error if empty and whitelist is applied" do
+        conjure_config_file_from_prefix( :whitelist, File.read('empty_whitelist_config_file') )
+
+        expect {
+          YachtLoader.to_hash(:apply_whitelist? => true)
+        }.to raise_error( YachtLoader::LoadError, /whitelist.+ cannot be empty/)
+      end
+
+      it "raises an error if invalid and whitelist is applied" do
+        conjure_config_file_from_prefix( :whitelist, File.read('invalid_whitelist_config_file') )
+
+        expect {
+          YachtLoader.to_hash(:apply_whitelist? => true)
+        }.to raise_error( YachtLoader::LoadError, /whitelist.+ must contain Array/)
+      end
+    end
+  end
+
+  context "checks environment and sets sensible defaults" do
+    it "sets the environment to 'default'" do
+      YachtLoader.environment.should == "default"
+    end
+
+    it "allows setting the environment by passing an option to `to_hash`" do
+      YachtLoader.to_hash(:env => 'a_child_environment')
+      YachtLoader.environment.should == 'a_child_environment'
+    end
+
+
+    it "raises an error if an environment is requested that doesn't exist" do
+      expect {
+        YachtLoader.environment = 'nonexistent'
+        YachtLoader.to_hash
+      }.to raise_error( YachtLoader::LoadError, /does not exist/)
+    end
+
+    it "merges configuration for named environment onto defaults" do
+      YachtLoader.environment = 'an_environment'
+      YachtLoader.to_hash['defaultkey'].should == 'defaultvalue'
+      YachtLoader.to_hash['name'].should == 'an_environment'
+    end
+  end
+
+  context "handles child environment" do
+    before do
+      YachtLoader.environment = 'a_child_environment'
+    end
+
+    it "merges child onto the parent it names" do
+      YachtLoader.to_hash['dog'].should == 'terrier'
+    end
+
+    it "merges the hashes recursively" do
+      child = YachtLoader.to_hash['hashkey']
+
+      child['foo'].should == 'kung'
+      child['baz'].should == 'yay'
+      child['xyzzy'].should == 'thud'
+    end
+  end
+
+  context "handling of local config file" do
+    before do
+      YachtLoader.environment = 'an_environment'
+    end
+
+    it "merges values onto named environment and defaults" do
+      YachtLoader.to_hash['defaultkey'].should == 'defaultvalue'
+      YachtLoader.to_hash['name'].should == 'an_environment'
+      YachtLoader.to_hash['localkey'].should == 'localvalue'
+    end
+
+    it "uses base config if missing" do
+      banish_config_file_from_prefix('local')
+
+      File.should_not_receive(:read).with('local_config_file')
+
+      YachtLoader.send(:local_config).should == {}
+      YachtLoader.to_hash['defaultkey'].should == 'defaultvalue'
+      YachtLoader.to_hash['name'].should == 'an_environment'
+    end
+
+    it "uses base config if empty" do
+      conjure_config_file_from_prefix(:local, File.read('empty_local_config_file'))
+
+      File.should_not_receive(:read).with('local_config_file')
+
+      YachtLoader.send(:local_config).should == {}
+      YachtLoader.to_hash['defaultkey'].should == 'defaultvalue'
+      YachtLoader.to_hash['name'].should == 'an_environment'
+    end
+
+    it "raises an error if invalid" do
+      conjure_config_file_from_prefix( :local, File.read('invalid_local_config_file') )
+      expect {
+        YachtLoader.to_hash
+      }.to raise_error( YachtLoader::LoadError, %r{local.yml must contain Hash})
+    end
+  end
+
+  describe :config_file_for do
+    it "returns the full file path for the following config files: base, local & whitelist" do
+      %w(base local whitelist).each do |config_file|
+        YachtLoader.should_receive(:full_file_path_for_config).with(config_file)
+
+        YachtLoader.config_file_for(config_file)
+      end
+    end
+
+    it "raises an error if the config file is not found" do
+      expect {
+        YachtLoader.config_file_for(:foo)
+      }.to raise_error( YachtLoader::LoadError, "foo is not a valid config type")
+    end
+  end
+
+  describe :load_config_file do
+    it "loads the specified file" do
+      conjure_config_file_from_prefix("base", "some contents")
+
+      YachtLoader.send(:load_config_file, "base", :expect_to_load => String).should == "some contents"
+    end
+
+    it "raises an error if opening the file leads to an exception" do
+      YachtLoader.stub(:config_file_for).and_raise(StandardError.new("my_unique_error_message"))
+
+      expect {
+        YachtLoader.send(:load_config_file, "some file")
+      }.to raise_error( YachtLoader::LoadError, %r{ERROR: loading.+my_unique_error_message} )
+    end
+  end
+end

data/spec/yacht_loader/classy_struct_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe "to_classy_struct" do
+  before do
+    conjure_config_file_from_prefix("base")
+    conjure_config_file_from_prefix("local")
+    conjure_config_file_from_prefix("whitelist")
+
+    YachtLoader.environment = 'an_environment'
+  end
+
+  it "creates a ClassyStruct based on to_hash" do
+    Yacht = YachtLoader.to_classy_struct
+    Yacht.dog.should == "terrier"
+  end
+
+  # ClassyStruct improves performance by adding accessors to the instance object
+  # If the instance is not reused, there is no advantage to ClassyStruct over OpenStruct
+  it "reuses the instance of ClassyStruct on subsequent calls" do
+    first_obj = YachtLoader.classy_struct_instance
+    second_obj = YachtLoader.classy_struct_instance
+
+    first_obj.object_id.should == second_obj.object_id.should
+  end
+
+  it "passes options to to_hash" do
+    YachtLoader.should_receive(:to_hash).with({:my => :awesome_option})
+
+    Yacht = YachtLoader.to_classy_struct({:my => :awesome_option})
+  end
+
+  it "raises a custom error if ClassyStruct cannot be created" do
+    YachtLoader.stub!(:to_hash).and_raise("some funky error")
+
+    expect {
+      Yacht = YachtLoader.to_classy_struct
+    }.to raise_error(YachtLoader::LoadError, /some funky error/)
+  end
+end

data/spec/yacht_loader/rails_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe "Rails support" do
+  before do
+    require "yacht_loader/rails"
+    @yacht_dir = "/path/to/rails/config/yacht"
+  end
+
+  describe :environment do
+    before do
+      Rails = stub("Rails")
+    end
+    it "uses the current rails environment by default" do
+      Rails.should_receive(:env)
+
+      YachtLoader.environment
+    end
+  end
+
+  describe :dir do
+    it "uses config/yacht by default" do
+      Rails.stub_chain(:root, :join).and_return(@yacht_dir)
+
+      YachtLoader.dir.should == @yacht_dir
+    end
+  end
+
+  describe :full_file_path_for_config do
+    it "calls dir.join" do
+      fake_dir = stub("dir stub")
+      YachtLoader.stub(:dir).and_return(fake_dir)
+      fake_dir.should_receive(:join).with("some.yml")
+
+      YachtLoader.full_file_path_for_config("some")
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification 
+name: yacht
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Mani Tadayon
+- Rico Rodriquez Collins
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-18 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: classy_struct
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.3.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 1.3.1
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: simplecov
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 0.4.2
+  type: :development
+  version_requirements: *id003
+description: 
+email: 
+- mtadayon@atti.com
+- rcollins@atti.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/monkeypatches/hash.rb
+- lib/yacht.rb
+- lib/yacht_loader/base.rb
+- lib/yacht_loader/classy_struct.rb
+- lib/yacht_loader/rails.rb
+- lib/yacht_loader/version.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/yacht_loader/base_spec.rb
+- spec/yacht_loader/classy_struct_spec.rb
+- spec/yacht_loader/rails_spec.rb
+- Gemfile
+- Rakefile
+- README.rdoc
+homepage: https://github.com/attinteractive/yacht
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.3.7
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: Use YAML files to manage application configuration.
+test_files: []
+