castor 0.0.1 → 0.0.2

data/README.md

@@ -1,6 +1,154 @@
 # Castor
 
-TODO: Write a gem description
+Castor is intended to help define third-party developer facing configurations for gems.
+
+## Usage
+
+The goal of Castor is to use it to define Gem configurations. As such you would probably do something like this:
+
+```ruby
+class MyGem
+  def configure(&block)
+    @config = Castor.configure do |config|
+      config.def :name, :old_value
+    end
+    block.call(@config) if block
+  end
+end
+
+gem = MyGem.new.configure do |config|
+  config.name = :new_value
+end
+```
+
+There are many ways to define config values.
+
+### Basic use-case
+
+Setting config nodes this way will not use validation in any way, but makes it easy to quickly define nodes
+
+```ruby
+config.def :name, :value
+```
+
+### Mass assignment
+
+Self explanatory. As will the basic setter, this doesn't offer any validation.
+
+```ruby
+config.def_many(:name => :value, :other_name => 'toto')
+```
+
+
+### Adding validations
+
+```ruby
+config.def :validated_symbol do 
+  type Symbol
+  default :value
+end
+
+config.def :validated_range do
+  value_in 1..50
+  default 1
+end
+```
+
+The config nodes `validated_symbol` and `validated_range` will now have validation.
+
+`validated_symbol` will only be accepted if new value is a Symbol
+
+`validated_range` will only accept values between 1 and 50
+
+If the validation fails, an `InvalidValueError` will be thrown
+
+### Lazy evaluations
+
+```ruby
+configuration = Castor.configure do |config|
+  i = 0
+  config.def :next_id, :lazy => lambda { i += 1 }
+
+  config.def :time_now do
+    type Time, Date
+    default { Time.now }
+  end
+
+  config.def :some_name, "a value"
+end
+
+# You can always pass lambdas as values,
+# they will be lazy-evaluated when called
+configuration.some_name = lambda { "some other value" }
+
+configuration.next_id
+# => 1
+configuration.next_id
+# => 2
+configuration.time_now
+# => 2013-03-22 23:32:03 -0400
+
+configuration.some_name
+# => "some other value"
+```
+
+Castor will validate the return value and throw an `InvalidValueError` if it is invalid
+
+```ruby
+config.time_now = lambda { 3 }
+config.time_now
+#=> InvalidValueError
+```
+
+### Procs
+
+Because Castor lazy-evals lambdas, if what you need is an actual proc, you'll have to enforce the type
+
+```ruby
+configuration = Castor.configure do |config|
+  config.def :a_proc do
+    type Proc
+    default { :some_value }
+  end
+end
+
+configuration.a_proc
+# => #<Proc:0x007ffdda2edda0 ...
+```
+
+### Nested config
+
+You can nest Castor configurations. Castor will not create setters for the intermediate node. A user could therefore not overwrite it by accident.
+
+```ruby
+configuration = Castor.configure do |config|
+  config.nested_config :nested => true do |nested|
+    nested.def :value, 5
+  end
+
+  config.other_nested Castor.configure{|nested|
+    nested.def :other_value, "value"
+  }
+end
+
+configuration.nested_config.value
+# => 5
+
+configuration.other_nested.other_value 
+# => "value"
+
+configuration.other_nested = 3
+# => NoMethodError
+```
+
+### Going Meta
+
+It's possible to use `#{node}!` method to get the `Castor::Configuration::Node` object. It's currently not very useful :(.
+
+```ruby
+config.time_now!
+# => #<Castor::Configuration::Node:0x007ffdda363af0 ...
+```
 
 ## Installation
 
@@ -16,10 +164,6 @@ Or install it yourself as:
 
     $ gem install castor
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Contributing
 
 1. Fork it

data/lib/castor.rb

@@ -1,5 +1,6 @@
 require "castor/version"
 require "castor/configuration"
+require "castor/configuration/node"
 
 module Castor
   def self.configure(&block)

data/lib/castor/configuration.rb

@@ -1,15 +1,17 @@
-require 'pry'
-
 module Castor
   class Configuration
+    include Enumerable
+
     def initialize(block)
       @values = {}
       instance_eval(&block)
+      @initialized = true
     end
 
-    def method_missing(name, *args, &block)
-      options = args.last.is_a?(::Hash) ? args.pop : {}
+    def def(name, *args, &block)
+      return super(name, *args, block) if @initialized
 
+      options = args.last.is_a?(::Hash) ? args.pop : {}
       config_value = nil
 
       if options[:nested]
@@ -23,7 +25,7 @@ module Castor
           default (args.first || options.delete(:lazy))
         } unless block
 
-        config_value = Castor::Configuration::Value.new(name, block)
+        config_value = Castor::Configuration::Node.new(name, block)
 
         selfclass.define_method(name) do
           config_value.value
@@ -33,7 +35,7 @@ module Castor
           config_value.value = args
         end
 
-        selfclass.define_method("#{name}!") do |arg|
+        selfclass.define_method("#{name}!") do
           config_value
         end
       end
@@ -41,9 +43,9 @@ module Castor
       @values[name] = config_value
     end
 
-    def call(attributes)
+    def def_many(attributes)
       attributes.each do |key, value|
-        self.send key, value
+        self.def key, value
       end
     end
 
@@ -51,73 +53,17 @@ module Castor
       class << self; self; end;
     end
 
+    def each(&block)
+      @values.each(&block)
+    end
 
-    class Value
-      def initialize(name, block)
-        @name = name
-        instance_eval(&block)
-        self.value = @default
-      end
-
-      def value=(new_value)
-        if validate!(new_value)
-          @value = new_value
-        end
-      end
-
-      def value
-        lazy? ? lazy_value : @value
-      end
-
-      private 
-
-      def lazy_value
-        v = @value.call
-        validate!(v, true)
-        v
-      end
-
-      def desc(description)
-        @description = description
-      end
-
-      def type(*types)
-        @types = types.flatten
-      end
-
-      def value_in(*values)
-        @possible_values = if values.length == 1 && values.first.is_a?(Enumerable)
-          values.first
+    def merge(hash)
+      hash.each do |k, v|
+        if self.send(k).is_a?(Castor::Configuration)
+          self.send(k).merge(v)
         else
-          values.flatten
-        end
-      end
-
-      def default(default_value = nil, &block)
-        @default = default_value || block
-      end
-
-      def lazy?(lazy_value = nil)
-        lazy_value = lazy_value || @value || @default
-        lazy_value.is_a?(Proc) && !(@types && @types.include?(Proc))
-      end
-
-      def validate!(new_value, jit = false)
-        return true if lazy?(new_value) && !jit
-
-        if (@possible_values && !@possible_values.include?(new_value))
-          raise_validation_error(new_value, "Value must be included in #{@possible_values.to_s}")
-        end
-
-        if (@types && @types.none?{|klass| new_value.is_a?(klass)})
-          raise_validation_error(new_value, "Value must be in types #{@types.to_s}")
+          self.send("#{k}=", v)
         end
-
-        true
-      end
-
-      def raise_validation_error(new_value, message)
-        raise InvalidValueError.new("Invalid value #{new_value} for #{@name}. #{message}")
       end
     end
 

data/lib/castor/configuration/node.rb

@@ -0,0 +1,72 @@
+module Castor
+  class Configuration
+    class Node
+      def initialize(name, block)
+        @name = name
+        instance_eval(&block)
+        self.value = @default
+      end
+
+      def value=(new_value)
+        if validate!(new_value)
+          @value = new_value
+        end
+      end
+
+      def value
+        lazy? ? lazy_value : @value
+      end
+
+      private 
+
+      def lazy_value
+        v = @value.call
+        validate!(v, true)
+        v
+      end
+
+      def desc(description)
+        @description = description
+      end
+
+      def type(*types)
+        @types = types.flatten
+      end
+
+      def value_in(*values)
+        @possible_values = if values.length == 1 && values.first.is_a?(Enumerable)
+          values.first
+        else
+          values.flatten
+        end
+      end
+
+      def default(default_value = nil, &block)
+        @default = default_value || block
+      end
+
+      def lazy?(lazy_value = nil)
+        lazy_value = lazy_value || @value || @default
+        lazy_value.is_a?(Proc) && !(@types && @types.include?(Proc))
+      end
+
+      def validate!(new_value, jit = false)
+        return true if lazy?(new_value) && !jit
+
+        if (@possible_values && !@possible_values.include?(new_value))
+          raise_validation_error(new_value, "Value must be included in #{@possible_values.to_s}")
+        end
+
+        if (@types && @types.none?{|klass| new_value.is_a?(klass)})
+          raise_validation_error(new_value, "Value must be in types #{@types.to_s}")
+        end
+
+        true
+      end
+
+      def raise_validation_error(new_value, message)
+        raise InvalidValueError.new("Invalid value #{new_value} for #{@name}. #{message}")
+      end
+    end
+  end
+end

data/lib/castor/version.rb

@@ -1,3 +1,3 @@
 module Castor
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/castor_spec.rb

@@ -5,38 +5,39 @@ describe Castor do
     Castor.configure do |config|
 
       # Complete syntax
-      config.toto do
+      config.def :toto do
         type Integer
         value_in 1..50
         default 42
       end
 
       # Short syntax
-      config.titi "hello"
+      config.def :titi, "hello"
 
       # Mass-assign syntax
-      config.(:mass => :assign, :is => :working, :for => 100)
+      config.def_many(:mass => :assign, :is => :working, :for => 100)
       
       # Nested
-      config.more :nested => true do |nested_config|
-        nested_config.titi :toto
+      config.def :more, :nested => true do |nested_config|
+        nested_config.def :titi, :toto
       end
 
       # Nested through new Castor
-      config.other_nested Castor.configure{|nested_config|
-        nested_config.is_nested true
+      config.def :other_nested, Castor.configure{|nested_config|
+        nested_config.def :is_nested, true
       }
 
       # Lazy Eval
-      config.time_now :lazy => lambda { Time.now }
+      config.def :time_now, :lazy => lambda { Time.now }
 
       # Lazy eval with block
-      config.lazy_increment do
+      config.def :lazy_increment do
         type Fixnum
         default 3
       end
 
-      config.proc do
+      # Expected procs
+      config.def :proc do
         type Proc
         default { 3 }
       end
@@ -44,11 +45,12 @@ describe Castor do
   }
   
   context "default values" do
-    its(:toto) { should == 42 }
-    its(:titi) { should == "hello" }
-    its(:mass) { should == :assign }
-    its(:is)   { should == :working }
-    its(:for)  { should == 100 }
+    its(:toto)      { should == 42 }
+    its(:titi)      { should == "hello" }
+    its(:mass)      { should == :assign }
+    its(:is)        { should == :working }
+    its(:for)       { should == 100 }
+    its(:time_now)  { should be_a Time }
   end
 
   context "nested values" do
@@ -59,7 +61,7 @@ describe Castor do
   end
 
   context "lazy values" do
-    it "doesn't override procs" do
+    it "doesn't override the behavior of expected procs" do
       subject.proc.should be_a Proc
     end
   end
@@ -86,9 +88,29 @@ describe Castor do
     end
 
     context "to a value out of range" do
-      it "throws an exception" do
+      it "throws an error" do
         expect { subject.toto = 100 }.to raise_error Castor::Configuration::InvalidValueError
       end
     end
+
+    context "setting a value not specified" do
+      it "throws an error" do 
+        expect { subject.undefined_config_value(3) }.to raise_error NoMethodError
+      end
+    end
+
+    context "by merging with a Hash" do
+      before {
+        subject.merge :toto => 21, :more => { :titi => 21 }
+      }
+
+      its(:toto) { should == 21 }
+
+      it "deep merges hashes" do
+        subject.more.titi.should == 21
+      end
+    end
   end
+
+  it "behaves like an enumerable"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: castor
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-20 00:00:00.000000000 Z
+date: 2013-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
@@ -60,6 +60,7 @@ files:
 - castor.gemspec
 - lib/castor.rb
 - lib/castor/configuration.rb
+- lib/castor/configuration/node.rb
 - lib/castor/version.rb
 - spec/castor_spec.rb
 - spec/spec_helper.rb