dacs 0.1.0 → 0.2.0

data/History.txt

@@ -0,0 +1,10 @@
+== 0.2.0 2010-01-13
+   * Major enhancements
+     * Added new mini-DSL for defining known configuration keys
+     * AppConfig now knows where each configured value came from
+       (default, file, or environment)
+     * Init will generate a starter config file if one doesn't exist
+     
+  * Minor enhancements
+    * Warns when unknown keys are encountered
+    * Checks config file for sanity

data/Rakefile

@@ -10,8 +10,10 @@ begin
     gem.email = "devs@devver.net"
     gem.homepage = "http://github.com/avdi/dacs"
     gem.authors = ["Devver, Inc."]
+    gem.add_dependency "ruport", "~> 1.6"
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "yard", ">= 0"
+    gem.add_development_dependency "devver-construct", "~> 1.1"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/example/example.rb

@@ -1,20 +1,33 @@
 #!/usr/bin/env ruby
+require 'rubygems'
 require File.expand_path('../lib/dacs', File.dirname(__FILE__))
 ENV['EXAMPLE_BAR'] = 'env_bar'
 Dacs::AppConfig.init!('example', 
-  :defaults => { 
-    'foo' => 'default_foo', 
-    'bar' => 'default_bar', 
-    'baz' => 'default_baz' },
   :config_path => File.expand_path('example.yml', File.dirname(__FILE__)),
   :environment => 'development',
-  :logger      => Logger.new($stdout))
+  :logger      => Logger.new($stdout)) do |config|
+  
+  config.key 'foo', :default => 'default_foo'
+  config.key 'bar', :default => 'default_bar'
+  config.key 'baz', :default => 'default_baz'
+end
 
+puts "Running in #{Dacs::AppConfig.environment} mode"
 puts "foo: #{Dacs::AppConfig['foo']}"
 puts "bar: #{Dacs::AppConfig['bar']}"
 puts "baz: #{Dacs::AppConfig['baz']}"
+puts Dacs::AppConfig.dump             # => nil
 
-# >> I, [2010-01-27T18:59:15.223408 #23940]  INFO -- : Found config file /devver-repos/dacs/example/example.yml.
+# >> I, [2010-02-13T02:34:46.344705 #25573]  INFO -- : Found config file /devver-repos/dacs/example/example.yml.
+# >> W, [2010-02-13T02:34:46.345300 #25573]  WARN -- : Unknown configuration key 'fuz' in file example.yml
+# >> Running in development mode
 # >> foo: file_foo
 # >> bar: env_bar
 # >> baz: default_baz
+# >> +--------------------------------------+
+# >> | Key |    Value    |      Source      |
+# >> +--------------------------------------+
+# >> | baz | default_baz | defaults         |
+# >> | foo | file_foo    | file example.yml |
+# >> | bar | env_bar     | environment      |
+# >> +--------------------------------------+

data/example/example.yml

@@ -1,3 +1,4 @@
 development:
   foo: file_foo
   bar: file_bar
+  fuz: file_fuz

data/lib/dacs/app_config.rb

@@ -3,6 +3,7 @@ require 'singleton'
 require 'logger'
 require 'pathname'
 require 'yaml'
+require 'ruport'
 
 module Dacs
   # This configuration system is for deployment-specific values, such as AWS keys
@@ -34,23 +35,55 @@ module Dacs
   #    variables.  For instance, to set key 'foo' = 'bar', set APPNAME_FOO='bar'
   #    in the process environment.
   class AppConfig < Hash
-    include Singleton
 
     class << self
       extend Forwardable
 
       # Delegate a subset of Hash methods to the singleton instance
-      def_delegators :instance, :[], :fetch, :key?, :merge, :merge!, :app_name
+      def_delegators :instance, :[], :fetch, :key?, :merge, :merge!, :app_name,
+                                :source, :dump
+
+      def_delegators :schema, :required?, :optional?, :keys, :default_value
     end
 
+    # Usage:
+    #
+    #     Dacs::AppConfig.init!('example', 
+    #       :environment => 'development',
+    #       :logger      => Logger.new($stdout)) do |config|
+    #    
+    #       config.key 'foo', :default => 'default_foo'
+    #       config.key 'bar', :default => 'default_bar'
+    #       config.key 'baz', :default => 'default_baz'
+    #     end
     def self.init!(app_name, options={})
-      @__instance__ = nil
+      @instance = nil
       @@options = options.merge(:app_name => app_name)
       @@options[:app_root]     ||= Pathname(Dir.pwd)
       @@options[:config_path]  ||= @@options[:app_root] + 'config' + "#{app_name}.yml"
       @@options[:logger]       ||= ::Logger.new($stderr)
       @@options[:environment]  ||= :development
       @@options[:defaults]     ||= {}
+      if block_given?
+        schema = Schema.new
+        yield(schema)
+        @@schema = schema
+      else
+        @@schema = PermissiveSchema.new(@@options[:defaults])
+      end
+      self.instance
+    end
+
+    def self.instance
+      @instance ||= new
+    end
+
+    def self.schema
+      @@schema
+    end
+
+    def self.environment
+      @@options[:environment]
     end
     
     attr_reader :app_name
@@ -60,28 +93,94 @@ module Dacs
 
     def initialize
       raise "You must initialize with Dacs::AppConfig.init!()" unless @@options
-      @app_name    = @@options[:app_name]
-      @config_path = @@options[:config_path]
-      @logger      = @@options[:logger]
-      @environment = @@options[:environment]
-      @defaults    = @@options[:defaults]
-      @local_config = if Pathname(config_path).exist?
-                        logger.info "Found config file #{config_path}."
-                        YAML.load_file(config_path.to_s).fetch(environment.to_s) {{}}
-                      else
-                        logger.info "#{config_path} does not exist;" +
-                          " config will be from environment."
-                        {}
-                      end
-
-      replace(@defaults)
-
-      # Local config takes priority over defaults
-      merge!(@local_config)
-
-      # Environment takes priority over local config
-      ENV.keys.grep(/^#{app_name.upcase}_(.*)$/) do |key|
-        self[$1.downcase] = ENV[key]
+      @app_name     = @@options[:app_name]
+      @config_path  = @@options[:config_path]
+      @logger       = @@options[:logger]
+      @environment  = @@options[:environment]
+      @defaults     = self.class.schema.defaults 
+      find_or_create_config_file!
+
+      defaults_source = DefaultSource.new(@defaults)
+      file_source     = FileSource.new(config_path, @environment)
+      env_source      = EnvironmentSource.new(@app_name)
+
+      load_values!(self.class.schema, env_source, file_source, defaults_source)
+    end
+
+    def source(key)
+      configured_value = Hash.instance_method(:fetch).bind(self).call(key.to_s) do
+        raise ConfigurationError, "No such key '#{key}'"
+      end
+      configured_value.source.to_s
+    end
+
+    def [](key)
+      super(key).value
+    end
+
+    def fetch(key, &block)
+      case result = super(key, &block)
+      when ConfiguredValue then result.value
+      else result
+      end
+    end
+
+    def dump
+      table = Table(%w[Key Value Source])
+      each_pair do |key, configured_value|
+        table << [key, configured_value.value, configured_value.source.to_s]
+      end
+      table.as(:text)
+    end
+
+    private
+
+    def find_or_create_config_file!
+      if Pathname(config_path).exist?
+        logger.info "Found config file #{config_path}."
+      else
+        logger.info "#{config_path} does not exist"
+        create_starter_config_file!
+      end
+    end
+
+    def create_starter_config_file!
+      path = Pathname(config_path)
+      path.dirname.mkpath
+      path.open('w+') do |f|
+        f << starter_config_content
+      end
+      logger.info "Starter config file created at #{config_path}. " +
+        "Please customize it to your needs."
+    end
+
+    def starter_config_content
+      <<END
+# This is an auto-generated starter configuration file. Feel free to customize
+# it to your needs.
+
+development:
+  example_key: example_value
+
+test:
+  example_key: example_value
+
+production:
+  example_key: example_value
+
+END
+    end
+
+    def load_values!(schema, *sources)
+      sources.reverse_each do |source|
+        source.each do |configured_value|
+          if schema.defined?(configured_value.key)
+            self[configured_value.key] = configured_value
+          else
+            key = configured_value.key
+            logger.warn "Unknown configuration key '#{key}' in #{source}"
+          end
+        end
       end
     end
     

data/lib/dacs/configured_value.rb

@@ -0,0 +1,5 @@
+module Dacs
+  ConfiguredValue = Struct.new(:source, :key, :value) do
+    # ...
+  end
+end

data/lib/dacs/default_source.rb

@@ -0,0 +1,17 @@
+module Dacs
+  class DefaultSource
+    def initialize(defaults)
+      @defaults = defaults
+    end
+
+    def to_s
+      "defaults"
+    end
+
+    def each
+      @defaults.each do |key, value|
+        yield ConfiguredValue.new(self, key.to_s, value)
+      end
+    end
+  end
+end

data/lib/dacs/environment_source.rb

@@ -0,0 +1,20 @@
+module Dacs
+  class EnvironmentSource
+    def initialize(app_name, environment=ENV)
+      @app_name    = app_name.to_s.downcase
+      @environment = environment
+    end
+    
+    def to_s
+      "environment"
+    end
+
+    def each
+      @environment.each_pair do |key, value|
+        if match = /^#{@app_name}_(.*)$/.match(key.downcase)
+          yield ConfiguredValue.new(self, match[1], value)
+        end
+      end
+    end
+  end
+end

data/lib/dacs/errors.rb

@@ -0,0 +1,3 @@
+module Dacs
+  ConfigurationError = Class.new(Exception)
+end

data/lib/dacs/file_source.rb

@@ -0,0 +1,28 @@
+require 'pathname'
+require 'yaml'
+
+module Dacs
+  class FileSource
+    def initialize(config_path, environment)
+      @path        = Pathname(config_path)
+      @environment = environment.to_s
+    end
+
+    def to_s
+      "file #{@path.relative_path_from(Pathname.pwd).to_s}"
+    end
+
+    def each
+      @path.open('r') do |f|
+        environments = YAML.load(f)
+        environment = environments.fetch(@environment) do
+        raise ConfigurationError, 
+          "File #{@path} contains no #{environment} section"
+        end
+        environment.each_pair do |key, value|
+          yield ConfiguredValue.new(self, key.to_s, value)
+        end
+      end
+    end
+  end
+end

data/lib/dacs/permissive_schema.rb

@@ -0,0 +1,34 @@
+module Dacs
+  class PermissiveSchema
+    def initialize(defaults={})
+      @defaults = defaults.inject({}) { |h, (k,v)|
+        h[k.to_s] = v
+        h
+      }
+    end
+
+    def keys
+      @defaults.keys
+    end
+
+    def optional?(key)
+      true
+    end
+
+    def required?(key)
+      false
+    end
+
+    def defined?(key)
+      true
+    end
+
+    def default_value(key)
+      @defaults[key.to_s]
+    end
+
+    def defaults
+      @defaults
+    end
+  end
+end

data/lib/dacs/schema.rb

@@ -0,0 +1,53 @@
+module Dacs
+  class Schema
+
+    # Add a key definition
+    def key(name, options={})
+      key_defs << { :name => name.to_s }.merge(options)
+    end
+
+    def keys
+      key_defs.map{|d| d[:name]}
+    end
+
+    def required?(key)
+      assert_key_defined!(key)
+      kd = key_def(key.to_s)
+      kd && !kd.key?(:default)
+    end
+
+    def optional?(key)
+      !required?(key.to_s)
+    end
+
+    def defined?(key)
+      !!key_def(key)
+    end
+
+    def default_value(key)
+      assert_key_defined!(key)
+      key_def(key.to_s)[:default]
+    end
+
+    def defaults
+      key_defs.inject({}) { |h, key_def|
+        h[key_def[:name]] = key_def[:default]
+        h
+      }
+    end
+
+    private
+
+    def assert_key_defined!(key)
+      !!key_def(key) or raise ConfigurationError, "No configuration key '#{key}' is defined"
+    end
+
+    def key_defs
+      @key_defs ||= []
+    end
+
+    def key_def(key)
+      key_defs.detect{|kd| kd[:name] == key.to_s}
+    end
+  end
+end

data/lib/dacs.rb

@@ -1,2 +1,10 @@
 $:.unshift(File.dirname(__FILE__))
+require 'dacs/errors'
+require 'dacs/schema'
+require 'dacs/permissive_schema'
+require 'dacs/configured_value'
+require 'dacs/environment_source'
+require 'dacs/file_source'
+require 'dacs/default_source'
+require 'dacs/environment_source'
 require 'dacs/app_config'

data/spec/dacs/app_config_spec.rb

@@ -0,0 +1,166 @@
+require File.expand_path('../spec_helper', File.dirname(__FILE__))
+
+module Dacs
+  describe AppConfig do
+    include Construct::Helpers
+    before :each do
+      @construct = create_construct
+      @start_dir = Dir.pwd
+      Dir.chdir(@construct)
+      @app_name  = "foo_app"
+      @logger    = stub("logger").as_null_object
+    end
+
+    after(:each) do
+      Dir.chdir(@start_dir)
+      @construct.destroy!
+    end
+
+    context "when first initialized" do
+      it "should write an example config file" do
+        AppConfig.init!(@app_name, :logger => @logger)
+        AppConfig.instance
+        (@construct+'config'+'foo_app.yml').should exist
+      end
+
+      it "should know its environment" do
+        AppConfig.environment.should be == :development
+      end
+    end
+
+    context "given a config file lacking the expected environment key" do
+      append_before :each do
+        @construct.file("config/foo_app.yml") do |f|
+          YAML.dump({'production'=>{}}, f)
+        end
+      end
+
+      it "should raise an error on init" do
+        lambda do 
+          AppConfig.init!(@app_name, 
+            :environment => :development,
+            :logger      => @logger)
+        end.should raise_error(ConfigurationError)
+      end
+    end
+
+    context "given a config file with an unknown key" do
+      before :each do
+        @construct.file("config/foo_app.yml") do |f|
+          YAML.dump({'development'=>{'undefined' => 'xyz'}}, f)
+        end
+      end
+
+      it "should warn the user" do
+        @logger.should_receive(:warn).with("Unknown configuration key 'undefined' in file config/foo_app.yml")
+        AppConfig.init!(@app_name, :logger => @logger) do |config|
+          config.key "foo", :default => 42
+        end
+      end
+    end
+
+    context "without explicit key definitions" do
+      before :each do
+        AppConfig.init!(@app_name, 
+          :logger   => @logger, 
+          :defaults => {
+            'foo' => 24,
+            'bar' => false,
+            'baz' => 3.14
+          }
+          )
+      end
+
+      it "should derive key list from defaults option" do
+        AppConfig.keys.sort.should be == ['foo', 'bar', 'baz'].sort
+      end
+
+      it "should use defaults provided in options" do
+        AppConfig.default_value('foo').should be == 24
+        AppConfig.default_value('bar').should be == false
+        AppConfig.default_value('baz').should be == 3.14
+      end
+
+      it "should consider all keys to be optional" do
+        AppConfig.optional?('foo').should be_true
+        AppConfig.required?(:foo).should be_false
+        AppConfig.optional?('faz').should be_true
+      end
+
+    end
+
+    context "with explicit key definitions" do
+      before :each do
+        AppConfig.init!(@app_name, :logger => @logger) do |config|
+          config.key :foo, :default => 42
+          config.key 'bar'
+        end
+      end
+
+      it "should be able to list known keys" do
+        AppConfig.keys.should == ['foo', 'bar']
+      end
+
+      it "should remember defaults provided in definition" do
+        AppConfig.default_value('foo').should be == 42
+      end
+
+      it "should consider keys with no default to be required" do
+        AppConfig.required?('bar').should be_true
+        AppConfig.optional?(:bar).should be_false
+      end
+
+      it "should consider keys with no default to be optional" do
+        AppConfig.required?('foo').should be_false
+        AppConfig.optional?(:foo).should be_true
+      end
+
+    end
+
+    context "with a mix of default, file, and environment settings" do
+      before :each do
+        @construct.file("config/foo_app.yml") do |f|
+          YAML.dump({
+              'development'=>{
+                'bar' => 'file_bar',
+                'baz' => 'file_buz'
+              }
+            }, 
+            f)
+        end
+        ENV['FOO_APP_BUZ'] = 'env_buz'
+        AppConfig.init!(@app_name, :logger => @logger) do |config|
+          config.key :foo,  :default => 42
+          config.key 'bar', :default => "baz"
+          config.key 'buz', :default => "ribbit"
+        end
+      end
+
+      it "should have the correct values for each" do
+        AppConfig['foo'].should be == 42
+        AppConfig['bar'].should be == 'file_bar'
+        AppConfig['buz'].should be == 'env_buz'
+      end
+
+      it "should be able to tell where each came from" do
+        AppConfig.source('foo').should match(/defaults/)
+        AppConfig.source('bar').should match(
+          /file config\/foo_app.yml/)
+        AppConfig.source('buz').should be == 'environment'
+      end
+
+      it "should be able to show a table of values" do
+        AppConfig.dump.should == <<END
++------------------------------------------+
+| Key |  Value   |         Source          |
++------------------------------------------+
+| foo |       42 | defaults                |
+| buz | env_buz  | environment             |
+| bar | file_bar | file config/foo_app.yml |
++------------------------------------------+
+END
+      end
+      
+    end
+  end
+end

data/spec/dacs_spec.rb

@@ -1,7 +1,3 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
-describe "Dacs" do
-  it "fails" do
-    fail "hey buddy, you should probably rename this file and start specing for real"
-  end
-end
+

data/spec/spec_helper.rb

@@ -3,7 +3,7 @@ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'dacs'
 require 'spec'
 require 'spec/autorun'
+require 'construct'
 
 Spec::Runner.configure do |config|
-  
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dacs
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Devver, Inc.
@@ -9,9 +9,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-27 00:00:00 -05:00
+date: 2010-02-13 00:00:00 -05:00
 default_executable: 
 dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ruport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.6"
+    version: 
 - !ruby/object:Gem::Dependency 
   name: rspec
   type: :development
@@ -32,6 +42,16 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
+- !ruby/object:Gem::Dependency 
+  name: devver-construct
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.1"
+    version: 
 description: Devver Application Configuration System
 email: devs@devver.net
 executables: []
@@ -44,6 +64,7 @@ extra_rdoc_files:
 files: 
 - .document
 - .gitignore
+- History.txt
 - LICENSE
 - README.rdoc
 - Rakefile
@@ -52,6 +73,14 @@ files:
 - example/example.yml
 - lib/dacs.rb
 - lib/dacs/app_config.rb
+- lib/dacs/configured_value.rb
+- lib/dacs/default_source.rb
+- lib/dacs/environment_source.rb
+- lib/dacs/errors.rb
+- lib/dacs/file_source.rb
+- lib/dacs/permissive_schema.rb
+- lib/dacs/schema.rb
+- spec/dacs/app_config_spec.rb
 - spec/dacs_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -85,4 +114,5 @@ specification_version: 3
 summary: Devver Application Configuration System
 test_files: 
 - spec/spec_helper.rb
+- spec/dacs/app_config_spec.rb
 - spec/dacs_spec.rb