configure 0.1.0 → 0.2.0

data/README.rdoc

@@ -10,37 +10,162 @@ The most simple way <tt>configure</tt> can be used is to pass a block to the <tt
 receive back a hash with the configuration values.
 
   laser = Configure.process do
-    title "red laser"
+    label "red laser"
     wave_length 700
   end
 
   laser == {
-    :title => "red laser",
+    :label => "red laser",
     :wave_length => 700
   } # => true
 
+=== Nested configurations
+
 It is also possible to pass blocks to configuration keys and combine multiple values to an array.
 
   laser = Configure.process do
-    title "red and violet pulse laser"
-    pulses do
+    label "red and violet pulse laser"
+    pulse do
       wave_length 700
       duration 20
     end
-    pulses do
+    pulse do
       wave_length 400
       duration 20
     end
   end
 
   laser == {
-    :title => "red and violet pulse laser",
-    :pulses => [
+    :label => "red and violet pulse laser",
+    :pulse => [
       { :wave_length => 700, :duration => 20 },
       { :wave_length => 400, :duration => 20 }
     ]
   } # => true
 
+If arguments and a block is passed to a configuration key, the arguments are stored at the <tt>:arguments</tt> key
+inside the nested configuration.
+
+  laser = Configure.process do
+    label "red pulse laser"
+    pulse "test" do
+      wave_length 700
+      duration 20
+    end
+  end
+
+  laser = {
+    :label => "red pulse laser",
+    :pulse => {
+      :wave_length => 700,
+      :duration => 20,
+      :arguments => [ "test" ]
+    }
+
+  } # => true
+
+== Schema
+
+In order receive a more structured configuration, a schema can be passed to the <tt>Configure.process</tt> method. This
+schema is a simple hash, that can be created - off course - using the configure syntax ;-)
+
+=== Defaults
+
+  schema = Configure::Schema.build do
+    defaults do
+      wave_length 700
+      duration 20
+    end
+  end
+
+  laser = Configure.process schema do
+    label "violet pulse laser"
+    wave_length 400
+  end
+
+  laser = {
+    :label => "violet pulse laser",
+    :wave_length => 400,
+    :duration => 20
+  } # => true
+
+=== Nested schemas
+
+Nested schema have to go to the <tt>nested</tt> section.
+
+  schema = Configure::Schema.build do
+    nested do
+      pulse do
+        defaults do
+          wave_length 700
+          duration 20
+        end
+      end
+    end
+  end
+
+If a nested schema provides the key <tt>argument_keys</tt>, the arguments that have been passed along with the nested
+configuration, are stored to these keys. The rest will be assigned to the <tt>:arguments</tt> key as before.
+
+  schema = Configure::Schema.build do
+    nested do
+      pulse do
+        argument_keys :wave_length, :duration
+      end
+    end
+  end
+
+  laser = Configure.process schema do
+    pulse 700, 20, :extra do
+      label "red pulse"
+    end
+  end
+
+  laser == {
+    :pulse => {
+      :wave_length => 700,
+      :duration => 20,
+      :arguments => [ :extra ]
+      :label => "red pulse"
+    }
+  } # => true
+
+=== Configuration class
+
+Sometimes, a hash may not be the best data structure to store the configuration. If a more strict structure is needed,
+the attribute <tt>:configuration_class</tt> can be set the schema. When the configuration is processed, the class is
+instantiated and the values are set via <tt>key=</tt> or the <tt>[]=</tt> methods. If both is not possible, an exception
+is raised.
+
+  class Laser
+
+    attr_accessor :label
+    attr_accessor :wave_length
+    attr_accessor :duration
+
+  end
+
+  schema = Configure::Schema.build do
+    configuration_class Laser
+    defaults do
+      duration 20
+    end
+  end
+
+  laser = Configure.process schema do
+    label "red laser"
+    wave_length 700
+  end
+
+  laser.is_a? Laser          # => true
+  laser.label == "red laser" # => true
+  laser.wave_length == 700   # => true
+  laser.duration == 20       # => true
+
+  Configure.process schema do
+    invalid_key "value"
+  end # => raises Configure::Injector::Error
+
 == Development
 
 Development has been done test-driven and the code follows at most the Clean Code paradigms. Code smells has been

data/lib/configure/injector.rb

@@ -2,21 +2,78 @@
 # Creates a configuration from the passed class and provides methods to inject values.
 class Configure::Injector
 
-  attr_reader :configuration
+  # The error will be raised if the configuration value can't be set or get.
+  class Error < StandardError; end
 
-  def initialize(configuration_class)
-    @configuration_class = configuration_class
-    @configuration = @configuration_class.new
+  attr_reader :schema
+
+  def initialize(schema)
+    @schema = schema
+    @configuration = self.configuration_class.new
+  end
+
+  def configuration_class
+    @schema[:configuration_class] || Hash
+  end
+
+  def defaults
+    @schema[:defaults] || { }
   end
 
-  def put_block(key, &block)
+  def put_block(key, arguments, &block)
+    nested_schema = (self.schema[:nested] || { })[key] || { }
+    nested_configuration = Configure.process_configuration nested_schema, &block
+    Arguments.new(nested_schema, nested_configuration, arguments).put
     value = Value.new @configuration, key
-    value.put Configure.process_configuration(@configuration_class, &block)
+    value.put_or_combine nested_configuration
   end
 
   def put_arguments(key, arguments)
     value = Value.new @configuration, key
-    value.put arguments.size == 1 ? arguments.first : arguments
+    value.put_single_or_multiple arguments
+  end
+
+  def configuration
+    apply_defaults
+    @configuration
+  end
+
+  private
+
+  def apply_defaults
+    self.defaults.each do |key, default_value|
+      value = Value.new @configuration, key
+      value.put_if_nil default_value
+    end
+  end
+
+  # Injector for the arguments in a nested configuration.
+  class Arguments
+
+    def initialize(schema, configuration, arguments)
+      @schema, @configuration, @arguments = schema, configuration, arguments.dup
+    end
+
+    def put
+      put_to_specified_keys
+      put_to_argument_key
+    end
+
+    def put_to_specified_keys
+      return if @arguments.empty?
+      argument_keys = [ @schema[:argument_keys] ].flatten.compact
+      argument_keys.each do |argument_key|
+        arguments_value = Value.new @configuration, argument_key
+        arguments_value.put @arguments.shift
+      end
+    end
+
+    def put_to_argument_key
+      return if @arguments.empty?
+      arguments_value = Value.new @configuration, :arguments
+      arguments_value.put @arguments
+    end
+
   end
 
   # Injector for a single configuration value.
@@ -26,16 +83,42 @@ class Configure::Injector
       @configuration, @key = configuration, key
     end
 
-    def get
-      @configuration[@key]
+    def put_single_or_multiple(values)
+      self.put_or_combine values.size == 1 ? values.first : values
+    end
+
+    def put_or_combine(value)
+      self.put exists? ? [ get, value ].flatten : value
+    end
+
+    def put_if_nil(value)
+      self.put value if get.nil?
     end
 
     def put(value)
-      @configuration[@key] = exists? ? [ get, value ].flatten : value
+      method_name = :"#{@key}="
+      if @configuration.respond_to?(method_name)
+        @configuration.send method_name, value
+      elsif @configuration.respond_to?(:[]=)
+        @configuration[@key] = value
+      else
+        raise Error, "couldn't set configuration value for key #{@key}!"
+      end
+    end
+
+    def get
+      method_name = :"#{@key}"
+      if @configuration.respond_to?(method_name)
+        @configuration.send method_name
+      elsif @configuration.respond_to?(:[])
+        @configuration[@key]
+      else
+        raise Error, "couldn't get configuration value for key #{@key}!"
+      end
     end
 
     def exists?
-      @configuration.has_key? @key
+      !!self.get
     end
 
   end

data/lib/configure/sandbox.rb

@@ -8,7 +8,7 @@ class Configure::Sandbox
 
    def method_missing(method_name, *arguments, &block)
      if block_given?
-       @injector.put_block method_name, &block
+       @injector.put_block method_name, arguments, &block
      else
        @injector.put_arguments method_name, arguments
      end

data/lib/configure/schema.rb

@@ -0,0 +1,12 @@
+
+module Configure::Schema
+
+  SCHEMA = {
+
+  }.freeze
+
+  def self.build(&block)
+    Configure.process SCHEMA, &block
+  end
+
+end

data/lib/configure.rb

@@ -3,13 +3,14 @@ module Configure
 
   autoload :Injector, File.join(File.dirname(__FILE__), "configure", "injector")
   autoload :Sandbox, File.join(File.dirname(__FILE__), "configure", "sandbox")
+  autoload :Schema, File.join(File.dirname(__FILE__), "configure", "schema")
 
-  def self.process(&block)
-    process_configuration Hash, &block
+  def self.process(schema = { }, &block)
+    process_configuration schema, &block
   end
 
-  def self.process_configuration(configuration_class, &block)
-    injector = Injector.new configuration_class
+  def self.process_configuration(schema = { }, &block)
+    injector = Injector.new schema
     sandbox = Sandbox.new injector
     sandbox.instance_eval &block
     injector.configuration

data/spec/acceptance/configure_with_schema_spec.rb

@@ -0,0 +1,96 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "spec_helper"))
+
+describe Configure do
+
+  describe "process with schema" do
+
+    before :each do
+      @configuration_class = Class.new
+      @configuration_class.send :attr_accessor, :test_key_one
+      @configuration_class.send :attr_accessor, :test_key_two
+
+      configuration_class = @configuration_class
+      @schema = described_class::Schema.build do
+        configuration_class configuration_class
+        defaults do
+          test_key_one "default value"
+        end
+        nested do
+          test_key_two do
+            argument_keys :test_key_three, :test_key_four
+            defaults do
+              test_key_five "default value"
+            end
+          end
+        end
+      end
+    end
+
+    it "should use the specified configuration class to create a configuration instance" do
+      configuration = described_class.process @schema do
+
+      end
+
+      configuration.should be_instance_of(@configuration_class)
+    end
+
+    it "should inject the given values" do
+      configuration = described_class.process @schema do
+        test_key_one "one"
+      end
+
+      configuration.test_key_one.should == "one"
+    end
+
+    it "should use the specified default values" do
+      configuration = described_class.process @schema do
+
+      end
+
+      configuration.test_key_one.should == "default value"
+    end
+
+    it "should evaluate the default values in nested schemas" do
+      configuration = described_class.process @schema do
+        test_key_two do
+
+        end
+      end
+
+      configuration.test_key_two.should == {
+        :test_key_five => "default value"
+      }
+    end
+
+    it "should transfer the arguments to a nested configuration to the specified argument_keys" do
+      configuration = described_class.process @schema do
+        test_key_two "three", "four" do
+          test_key_five "five"
+        end
+      end
+
+      configuration.test_key_two.should == {
+        :test_key_three => "three",
+        :test_key_four => "four",
+        :test_key_five => "five"
+      }
+    end
+
+    it "should transfer the argument-rest to a nested :arguments key" do
+      configuration = described_class.process @schema do
+        test_key_two "three", "four", "extra" do
+          test_key_five "five"
+        end
+      end
+
+      configuration.test_key_two.should == {
+        :test_key_three => "three",
+        :test_key_four => "four",
+        :test_key_five => "five",
+        :arguments => [ "extra" ]
+      }
+    end
+
+  end
+
+end

data/spec/acceptance/{configure_spec.rb → configure_without_schema_spec.rb}

@@ -2,7 +2,7 @@ require File.expand_path(File.join(File.dirname(__FILE__), "..", "spec_helper"))
 
 describe Configure do
 
-  describe "process" do
+  describe "process without schema" do
 
     it "should turn method call into hash values" do
       configuration = described_class.process do
@@ -65,6 +65,18 @@ describe Configure do
       }
     end
 
+    it "should set the :arguments key in nested configurations with the passed arguments" do
+      configuration = described_class.process do
+        test_key "one", "two" do
+          nested_test_key "three"
+        end
+      end
+
+      configuration.should == {
+        :test_key => { :arguments => [ "one", "two" ], :nested_test_key => "three" }
+      }
+    end
+
   end
 
 end

data/spec/lib/configure/injector_spec.rb

@@ -3,13 +3,33 @@ require File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "spec_hel
 describe Configure::Injector do
 
   before :each do
-    @injector = described_class.new Hash
+    @configuration_class = Class.new
+    @configuration_class.send :attr_accessor, :test_key
+    @configuration_class.send :attr_accessor, :another_test_key
+
+    @nested_schema = { }
+    @schema = {
+      :configuration_class => @configuration_class,
+      :nested => {
+        :test_key => @nested_schema
+      },
+      :defaults => {
+        :another_test_key => "default value"
+      }
+    }
+    @injector = described_class.new @schema
   end
 
   describe "initialize" do
 
     it "should create a configuration" do
-      @injector.configuration.should be_instance_of(Hash)
+      configuration = @injector.configuration
+      configuration.should be_instance_of(@schema[:configuration_class])
+    end
+
+    it "should set the default values" do
+      configuration = @injector.configuration
+      configuration.another_test_key.should == "default value"
     end
 
   end
@@ -18,23 +38,41 @@ describe Configure::Injector do
 
     before :each do
       @block = Proc.new { }
-      Configure.stub(:process_configuration => :nested_configuration)
+      @arguments = [ "one" ]
+      @nested_configuration = { }
+      Configure.stub(:process_configuration => @nested_configuration)
     end
 
-    it "should process a newly created configuration" do
-      Configure.should_receive(:process_configuration).with(Hash, &@block)
-      @injector.put_block :test_key, &@block
+    it "should process a new (nested) configuration" do
+      Configure.should_receive(:process_configuration).with(@nested_schema, &@block).and_return(@nested_configuration)
+      @injector.put_block :test_key, @arguments, &@block
     end
 
     it "should nest the configuration" do
-      @injector.put_block :test_key, &@block
-      @injector.configuration[:test_key].should == :nested_configuration
+      @injector.put_block :test_key, @arguments, &@block
+      @injector.configuration.test_key.should == @nested_configuration
+    end
+
+    it "should set the :arguments key in the nested configuration" do
+      @injector.put_block :test_key, @arguments, &@block
+      @injector.configuration.test_key[:arguments].should == @arguments
+    end
+
+    it "should not set the :arguments key in the nested configuration if no arguments are given" do
+      @injector.put_block :test_key, [ ], &@block
+      @injector.configuration.test_key.should_not have_key(:arguments)
+    end
+
+    it "should set the :argument_keys with the argument values if specified" do
+      @injector.schema[:nested][:test_key][:argument_keys] = :another_test_key
+      @injector.put_block :test_key, @arguments, &@block
+      @injector.configuration.test_key[:another_test_key].should == "one"
     end
 
     it "should combine nested configurations to an array" do
-      @injector.put_block :test_key, &@block
-      @injector.put_block :test_key, &@block
-      @injector.configuration[:test_key].should == [ :nested_configuration, :nested_configuration ]
+      @injector.put_block :test_key, @arguments, &@block
+      @injector.put_block :test_key, @arguments, &@block
+      @injector.configuration.test_key.should == [ @nested_configuration, @nested_configuration ]
     end
 
   end
@@ -43,18 +81,42 @@ describe Configure::Injector do
 
     it "should assign a value" do
       @injector.put_arguments :test_key, [ "one" ]
-      @injector.configuration[:test_key].should == "one"
+      @injector.configuration.test_key.should == "one"
+    end
+
+    it "should override a value" do
+      @injector.put_arguments :another_test_key, [ "one" ]
+      @injector.configuration.another_test_key.should == "one"
     end
 
     it "should assign an array of values" do
       @injector.put_arguments :test_key, [ "one", "two" ]
-      @injector.configuration[:test_key].should == [ "one", "two" ]
+      @injector.configuration.test_key.should == [ "one", "two" ]
     end
 
     it "should combine existing with new values" do
       @injector.put_arguments :test_key, [ "one" ]
       @injector.put_arguments :test_key, [ "two" ]
-      @injector.configuration[:test_key].should == [ "one", "two" ]
+      @injector.configuration.test_key.should == [ "one", "two" ]
+    end
+
+    it "should raise a #{described_class::Error} if key can't be set" do
+      lambda do
+        @injector.put_arguments :invalid_key, [ "one" ]
+      end.should raise_error(described_class::Error)
+    end
+
+  end
+
+  describe "configuration" do
+
+    before :each do
+      @injector.put_arguments :test_key, [ "one" ]
+    end
+
+    it "should return an instance of :configuration_class" do
+      configuration = @injector.configuration
+      configuration.should be_instance_of(@schema[:configuration_class])
     end
 
   end

data/spec/lib/configure/sandbox_spec.rb

@@ -14,8 +14,8 @@ describe Configure::Sandbox do
 
   it "should pass method calls with a block to the injector's :put_block" do
     block = Proc.new { }
-    @injector.should_receive(:put_block).with(:test_key, &block)
-    @sandbox.test_key &block
+    @injector.should_receive(:put_block).with(:test_key, [ "one" ], &block)
+    @sandbox.test_key "one", &block
   end
 
 end

data/spec/lib/configure/schema_spec.rb

@@ -0,0 +1,19 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "spec_helper"))
+
+describe Configure::Schema do
+
+  describe "#self.build" do
+
+    before :each do
+      @block = Proc.new { }
+      Configure.stub(:process)
+    end
+
+    it "should use configure to build the schema hash" do
+      Configure.should_receive(:process).with(described_class::SCHEMA, &@block)
+      described_class.build &@block
+    end
+
+  end
+
+end

data/spec/lib/configure_spec.rb

@@ -13,8 +13,8 @@ describe Configure do
     end
 
     it "should call :process_configuration" do
-      described_class.should_receive(:process_configuration).with(Hash, &@block)
-      described_class.process &@block
+      described_class.should_receive(:process_configuration).with(:schema, &@block)
+      described_class.process :schema, &@block
     end
 
   end
@@ -30,22 +30,22 @@ describe Configure do
     end
 
     it "should initialize the injector" do
-      described_class::Injector.should_receive(:new).with(Hash).and_return(@injector)
-      described_class.process_configuration Hash, &@block
+      described_class::Injector.should_receive(:new).with(:schema).and_return(@injector)
+      described_class.process_configuration :schema, &@block
     end
 
     it "should initialize the sandbox" do
       described_class::Sandbox.should_receive(:new).with(@injector).and_return(@sandbox)
-      described_class.process_configuration Hash, &@block
+      described_class.process_configuration :schema, &@block
     end
 
     it "should evaluate the block in the sandbox" do
       @sandbox.should_receive(:instance_eval).with(&@block)
-      described_class.process_configuration Hash, &@block
+      described_class.process_configuration :schema, &@block
     end
 
     it "should return the configuration" do
-      configuration = described_class.process_configuration Hash, &@block
+      configuration = described_class.process_configuration :schema, &@block
       configuration.should == :configuration
     end
 

metadata

@@ -2,7 +2,7 @@
 name: configure
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - "Philipp Br\xC3\xBCll"
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-14 00:00:00 +01:00
+date: 2011-03-15 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -50,11 +50,14 @@ files:
 - lib/configure.rb
 - lib/configure/injector.rb
 - lib/configure/sandbox.rb
+- lib/configure/schema.rb
 - spec/lib/configure_spec.rb
 - spec/lib/configure/injector_spec.rb
+- spec/lib/configure/schema_spec.rb
 - spec/lib/configure/sandbox_spec.rb
 - spec/spec_helper.rb
-- spec/acceptance/configure_spec.rb
+- spec/acceptance/configure_without_schema_spec.rb
+- spec/acceptance/configure_with_schema_spec.rb
 has_rdoc: true
 homepage: http://github.com/phifty/configure
 licenses: []
@@ -86,5 +89,7 @@ summary: Configure offers an easy way for configure your application using a DSL
 test_files: 
 - spec/lib/configure_spec.rb
 - spec/lib/configure/injector_spec.rb
+- spec/lib/configure/schema_spec.rb
 - spec/lib/configure/sandbox_spec.rb
-- spec/acceptance/configure_spec.rb
+- spec/acceptance/configure_without_schema_spec.rb
+- spec/acceptance/configure_with_schema_spec.rb