constellation 0.0.1

data/README.md

@@ -0,0 +1,113 @@
+## Constellation
+
+Constellation is a powerful configuration system. It's great for
+API client libraries and applications and anywhere else you need to
+let your users set some configuration parameters.
+
+## Usage
+
+### Ruby Parameters
+
+Start by creating a class and calling `acts_as_constellation`
+
+```ruby
+class MyConfiguration
+  acts_as_constellation
+end
+```
+
+With just this, you have a basic Hash configuration. The only way to set
+properties is to pass them in Ruby:
+
+```ruby
+config = MyConfiguration.new(:foo => 'bar')
+...
+config.foo # => "bar"
+```
+
+### `ENV`
+
+To add support for `ENV` hash configuration, set `env_params`:
+
+```ruby
+class MyConfiguration
+  self.env_params = { :foo => 'MY_FOO' }
+end
+
+...
+ENV['MY_FOO'] = 'bar'
+...
+config = MyConfiguration.new
+config.foo # => "bar"
+
+### Configuration Files
+
+To add support for config files, set `config_file` to a path. The Constellation
+will look up a config file in that location relative to two places ("base paths"):
+
+ * the current working directory (`Dir.pwd`)
+ * the user's home directory (`ENV['HOME']`)
+
+```ruby
+class MyConfiguration
+  self.config_file = 'my/config.yml'
+end
+```
+
+If `./my/config.yml` contains the following
+
+```yml
+--- 
+foo: bar
+```
+
+then `MyConfiguration.new.foo` will return `"bar"`.
+
+### From Gems
+
+If you set `config_file` to a path *and* set `load_from_gems` to `true`, then
+Constellation will add all of the loaded gem directories to the list of base paths.
+
+```ruby
+class MyConfiguration
+  self.config_file = 'my/config.yml'
+  self.load_from_gems = true
+end
+```
+
+## Order of Precedence
+
+Constellation will load parameters in the order listed above. Given
+
+```ruby
+class MyConfiguration
+  self.env_params = { :foo => 'MY_FOO' }
+  self.config_file = 'my/config.yml'
+  self.load_from_gems = true
+end
+```
+
+Constellation will first look in a Hash passed in, then in `ENV`, then in
+`./my/config.yml`, then in `~/my/config.yml`, then in `GEM_PATH/my/config.yml` for
+each loaded gem.
+
+## File Parsers
+
+Constellation will do the right thing if `config_file` ends with `.yml`, `.yaml`, or
+`.json`. If it's a different format, you'll have to tell Constellation how to parse it
+by redefining `parse_config_file`:
+
+```ruby
+class MyConfiguration
+  self.config_file = '.myrc'
+
+  def parse_config_file(contents)
+    result = {}
+    contents.split("\n").each do |line|
+      k, v = line.split(/:\s*/)
+      result[k] = v
+    end
+    result
+  end
+end
+```

data/lib/constellation.rb

@@ -0,0 +1,110 @@
+module Constellation
+
+  class ParseError < StandardError
+    def initialize(file)
+      super("Could not parse #{file}. Try overriding #parse_config_file")
+    end
+  end
+
+  module ActsAs
+    def acts_as_constellation
+      extend Constellation::ClassMethods
+      self.env_params = {}
+      include Constellation::InstanceMethods
+    end
+  end
+
+  module ClassMethods
+    attr_accessor :env_params, :config_file, :load_from_gems
+  end
+
+  module InstanceMethods
+
+    def initialize(data = nil)
+      @data = {}
+      reverse_merge(data || {})
+      fall_back_on_env
+      fall_back_on_file(Dir.pwd)
+      fall_back_on_file(ENV['HOME'])
+      fall_back_on_gems
+    end
+
+    def method_missing(name, *arguments, &block)
+      if data.has_key?(name.to_s)
+        data[name.to_s]
+      else
+        super
+      end
+    end
+
+    def respond_to?(name)
+      data.has_key?(name.to_s) || super
+    end
+
+    private
+
+    attr_reader :data
+
+    def fall_back_on_env
+      env_values = self.class.env_params.inject({}) do |sum, (prop, env_prop)|
+        sum[prop] = ENV[env_prop] if ENV.has_key?(env_prop)
+        sum
+      end
+      reverse_merge(env_values)
+    end
+
+    def fall_back_on_file(dir)
+      return if relative_config_file.nil?
+      f = File.expand_path(relative_config_file, dir)
+      cfg = load_config_file(f)
+      return unless cfg.respond_to?(:each) && cfg.respond_to?(:[])
+      reverse_merge(cfg)
+    end
+
+    def fall_back_on_gems
+      return unless self.class.load_from_gems
+      gem_paths.each { |p| fall_back_on_file(p) }
+    end
+
+    def reverse_merge(hash)
+      hash.each do |prop, value|
+        data[prop.to_s] ||= value
+      end
+    end
+
+    def relative_config_file
+      self.class.config_file
+    end
+
+    def load_config_file(full_path)
+      return unless File.exists?(full_path)
+
+      contents = File.read(full_path)
+
+      parsed = parse_config_file(contents)
+      return parsed if parsed
+
+      case full_path
+      when /\.ya?ml$/
+        require 'yaml'
+        YAML.load(contents)
+      when /\.json$/
+        require 'multi_json'
+        MultiJson.decode(File.read(full_path))
+      else
+        raise Constellation::ParseError.new(full_path)
+      end
+    end
+
+    def parse_config_file(contents)
+    end
+
+    def gem_paths
+      Gem.loaded_specs.values.map(&:gem_dir)
+    end
+
+  end
+
+end
+
+Class.send :include, Constellation::ActsAs

data/spec/constellation_spec.rb

@@ -0,0 +1,115 @@
+# encoding: utf-8
+
+require "spec_helper"
+
+describe Constellation do
+
+  let(:load_from_gems) { false }
+  let(:path) { 'config/chomper.yml' }
+  let(:home) { ENV['HOME'] }
+
+  let(:config_class) do
+    Class.new.tap do |c|
+      c.acts_as_constellation
+      c.env_params = { foo: 'MY_FOO', bar: 'MY_BAR' }
+      c.config_file = path
+      c.load_from_gems = load_from_gems
+    end
+  end
+
+  def write(base_dir, content)
+    full_path = File.join(base_dir, path)
+    FileUtils.mkdir_p File.dirname(full_path)
+    File.open(full_path, 'w') { |f| f << content }
+  end
+
+  describe 'configuration sources' do
+    subject    { config_class.new(foo: 'paramfoo') }
+
+    let(:cwd)  { '/somewhere' }
+
+    before do
+      ENV['MY_FOO'] = 'envfoo'
+      ENV['MY_BAR'] = 'envbar'
+
+      write(cwd, YAML.dump({ 'foo' => 'dotfoo', 'bar' => 'dotbar', 'baz' => 'dotbaz' }))
+      write(home, YAML.dump({ 'foo' => 'homefoo', 'bar' => 'homebar', 'baz' => 'homebaz', 'qux' => 'homequx' }))
+    end
+
+    after { ENV.delete('MY_FOO'); ENV.delete('MY_BAR') }
+
+    it('prefers passed parameters') { Dir.chdir(cwd) { subject.foo.should == 'paramfoo' } }
+    it('falls back on ENV')         { Dir.chdir(cwd) { subject.bar.should == 'envbar' } }
+    it('falls back on CWD/path')    { Dir.chdir(cwd) { subject.baz.should == 'dotbaz' } }
+    it('falls back on ~/path')      { Dir.chdir(cwd) { subject.qux.should == 'homequx' } }
+  end
+
+  describe 'load_from_gems' do
+    subject    { config_class.new }
+
+    let(:gem_dir) { '/gems/some_gem' }
+    let(:gems) {
+      { 'some_gem' => stub('Configuration', gem_dir: gem_dir) }
+    }
+
+    before do
+      Gem.stubs(:loaded_specs).returns(gems)
+      write(home, YAML.dump({ 'foo' => 'homefoo' }))
+      write(gem_dir, YAML.dump({ 'foo' => 'gemfoo', 'bar' => 'gembar' }))
+    end
+
+    context('with load_from_gems off') do
+      it("doesn't load from gems") { subject.should_not respond_to(:bar) }
+    end
+
+    context('with load_from_gems on') do
+      let(:load_from_gems) { true }
+      it('prefers ~/path')            { subject.foo.should == 'homefoo' }
+      it("falls back on [gems]/path") { subject.bar.should == 'gembar' }
+    end
+  end
+
+  describe 'file parsing' do
+    subject    { config_class.new }
+
+    context 'with a .yml file' do
+      let(:path) { 'config.yml' }
+      before { write(home, YAML.dump({ 'foo' => 'yamlfoo' })) }
+      it('parses as YAML') { subject.foo.should == 'yamlfoo' }
+    end
+
+    context 'with a .json file' do
+      let(:path) { 'config.json' }
+      before { write(home, MultiJson.encode({ 'foo' => 'jsonfoo' })) }
+      it('parses as JSON') { subject.foo.should == 'jsonfoo' }
+    end
+
+    context 'with an unknown extension' do
+      let(:path) { 'config.xqx' }
+      before { write(home, "foo: xqxfoo") }
+      it('throws an exception') do
+        expect { subject }.to raise_error(Constellation::ParseError)
+      end
+    end
+
+    context 'with a custom parser' do
+      let(:path) { 'config.col' }
+      let(:subject) do
+        config_class.class_eval do
+          define_method :parse_config_file do |contents|
+            contents.split("\n").inject({}) do |sum, line|
+              k, v = line.split(':')
+              sum[k] = v
+              sum
+            end
+          end
+        end
+        config_class.new
+      end
+
+      before { write(home, "foo:colonfoo") }
+
+      it('parses with the given parse method') { subject.foo.should == 'colonfoo' }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+require "constellation"
+require 'mocha'
+require 'multi_json'
+Dir[File.dirname(__FILE__) + "/support/**/*.rb"].each{ |f| require f }

data/spec/support/fakefs.rb

@@ -0,0 +1,6 @@
+require 'fakefs/safe'
+
+RSpec.configure do |c|
+  c.before(:each) { FakeFS.activate! }
+  c.after(:each)  { FakeFS.deactivate! }
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: constellation
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- James A. Rosen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-08 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: &70328840574360 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70328840574360
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70328840573860 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70328840573860
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: &70328840573400 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70328840573400
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: &70328840572920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70328840572920
+description: Load configuration settings from ENV, dotfiles, and gems
+email:
+- james.a.rosen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/constellation.rb
+- README.md
+- spec/constellation_spec.rb
+- spec/spec_helper.rb
+- spec/support/fakefs.rb
+homepage: ''
+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: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Load configuration settings
+test_files:
+- spec/constellation_spec.rb
+- spec/spec_helper.rb
+- spec/support/fakefs.rb