constructable 0.3.1 → 0.3.2

data/Gemfile

@@ -1,7 +1,6 @@
 source "http://rubygems.org"
 # Add dependencies required to use your gem here.
 # Example:
-#   gem "activesupport", ">= 2.3.5"
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.

data/README.markdown

@@ -2,53 +2,217 @@
 
 Provides a powerful class macro for defining and configuring constructable attributes of a class.
 
-## Facts
 
-* Doesn't break default initialize behaviour(see test/constructable/test_constructable 'should not break the initialize behaviour')
-* Only does what you expect it to do (no real magic involved)
-* Validates your attributes
-* Provides a granular control on how accessible your attributes are(no need to define attr_* yourself)
+## Basic usage
+
+Define your class like this:
 
-## Usage
 ```ruby
-class Foo
-  constructable [:bar, :readable => true], [:baz, :required => true, :readable => true]
+require 'constructable'
+class ProgrammingLanguage
+  constructable :creator, :name
 end
+```
+
+Then you can construct objects by providing a hash as the last argument
+to ProgrammingLanguage.new like this:
+
+```ruby
+ruby = ProgrammingLanguage.new(name: 'Ruby', creator: 'Yukihiro Matsumoto')
+```
 
-foo = Foo.new(bar: 5)
-# raises AttributeError, ':baz is a required attribute'
+The object _ruby_ will now have the instance variables _@name_ and
+_@creator_ set to _'Ruby'_ and _'Yukihiro Matsumoto'_.
 
-foo = Foo.new(baz: 7, bar: 5)
+## Does not break initialize behaviour
 
-foo.bar
-# => 5
-foo.baz
-# => 7
+You can use initialize just like you'd normally do:
 
-class ProgrammingLanguage
-  constructable [:paradigms,
-    readable: true,
-    required: true,
-    validate_type: Array]
+```ruby
+class Animal
+  constructable [:biological_class, readable: true]
+  attr_reader :name
+
+  GuessBiologicalClass = { ['Pig', 'Cow', 'Whale'] => 'Mammal', [ 'Turtle', 'Caiman' ] => 'Reptile' }
+
+  def initialize(name, options = {})
+    @name = name
+    @biological_class = GuessBiologicalClass.find { |animals,_| animals.include?(name) }.last if options[:guess_biological_class]
+  end
+end
+
+rhinocerus = Animal.new('Rhinocerus', biological_class: 'Mammal')
+rhinocerus.biological_class
+#=> 'Mammal'
+
+turtle = Animal.new('Turtle', guess_biological_class: true)
+turtle.biological_class
+#=> 'Reptile'
+```
+
+
+
+## Setters, Getters
+
+You can define your constructable attributes as readable, writable or
+both:
+
+```ruby
+class Train
+  constructable :speed, readable: true
+  constructable :next_stop, writable: true
+  constructable :location, accsessible: true
+end
+
+orient_express = Train.new(speed: 100)
+orient_express.speed
+#=> 100
+
+orient_express.next_stop = 'Bucarest'
+# @next_stop == "Bucarest"
+
+orient_express.next_stop
+# raises NoMethodError
+
+orient_express.location = 'Budapest'
+orient_express.location
+#=> 'Budapest'
+```
+
+## Validations
+
+You can setup validation for constructable attributes, so the users of
+your api won't provide weird values or none at all:
+
+### required
+
+```ruby
+class Holidays
+  constructable :when, required: true
+end
+
+summer_holidays = Holidays.new
+# raises AttributeError, ':when is a required attribute'
+```
+
+### validate\_type
+
+```ruby
+class Conference
+  constructable :attendees, validate_type: Integer
 end
 
-c = ProgrammingLanguage.new(paradigms: :functional)
-#  raises AttributeError, ':paradigms needs to be of type Array'
+euruko = Conference.new('~300') # btw, euruko was really great!
+# raises AttributeError, ':attendees must be of type Integer'
+```
+
+### validate
+
+```ruby
+class Farm
+  costructable :animals,
+    validate_type: Array,
+    validate: ->(array_of_animals) do
+      array_of_animals.all? { |animal| animal.is_a?(String) 
+    end
+end
+
+big_farm = Farm.new(animals: [:pigs, :cows])
+# raises AttributeError, ':animals has not passed validation'
+```
+
+## Convert your attributes
+
+You can pass a converter as an option for a constructable attribute,
+so before attributes are set, their values get converted to the return
+value of the proc, you provided:
+
+```ruby
+class Box
+  constructable :width, :height, converter: ->(value) { value.to_f * 100 }
+end
+
+small_box = Box.new(width: '1.40', height: '2.40')
+small_box.width
+#=> 140
+small_box.height
+#=> 240
+```
+
+## Default values
+
+You can also specify, which values your constructable attributes are set
+to by default:
+
+```ruby
+class Framework
+  constructable :opinionated, default: true
+end
+
+rails = Framework.new
+rails.opinionated
+#=> true
 
-ruby = ProgrammingLanguage.new(paradigms: [:object_oriented, :functional])
-ruby.paradigms
-# => [:object_oriented, :functional]
 ```
 
+## Redefining setters and getters
+
+You can redefine the setters and getters provided by the constructable
+macro and still get all the validations and stuff by calling super:
+
+```ruby
+class Song
+  constructable :length, accessible: true, validate_type: Integer
+
+  def length=(length)
+    if length.is_a?(String) && length =~ /(\d{,2}):(\d{,2})/
+      @length = $1.to_i * 60 + $2.to_i
+    else
+     super
+    end
+  end
+end
+
+song = Song.new(length: 190)
+#=> #<Song:0x000001010ea040 @length=190>
+
+song.length = '1:30'
+song.length
+#=> 90
+
+song.length = 'abc'
+# raises AttributeError, ':length must be of type Integer'
+```
+
+## constructable\_attributes method
+
+You can all the constructable attributes and their values of your class as a hash,
+by calling the constructable_attributes method from within an instance
+of your class:
+
+```ruby
+class Gadget
+  constructable :fancyness, :name, :price
+end
+
+iphone_4 = Gadget.new(fancyness: 1.0/0, name: 'Iphone 4', price: 1.0/0)
+iphone_4.constructable_attributes
+#=> { :fancyness => Infinity, :name => "Iphone 4", :price => Infinity }
+```
+
+## Modules
+
+### WARNING
 
-## Contributing to constructable
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+The constructable macro also works for modules(not for themself, but for
+the classes, you include them) but it will define the 'included' hook.
+So if you want to use the 'included' hook yourself, you either need to
+around alias it or to use another gem. I tried some things, but it is
+impossible, to provide all the magic of this gem, without defining
+the 'included' macro. I thought about getting rid of some of the magic,
+but this would infer with my initial intention, to provide an easy way
+to make constructable classes. If someone has a nice idea, how to solve
+this problem elgantely, please contact me!
 
 ## Copyright
 Copyright (c) 2011 Manuel Korfmann. See LICENSE.txt for

data/TODO.md

@@ -0,0 +1,2 @@
+
+* costum error messages for the validator proc

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.3.2

data/constructable.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{constructable}
-  s.version = "0.3.1"
+  s.version = "0.3.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Manuel Korfmann"]
-  s.date = %q{2011-06-15}
+  s.date = %q{2011-06-17}
   s.description = %q{
 Adds the class macro Class#constructable to easily define what attributes a Class accepts provided as a hash to Class#new.
 Attributes can be configured in their behaviour in case they are not provided or are in the wrong format.
@@ -29,6 +29,7 @@ See the documentation for Constructable::Constructable#constructable or the READ
     "LICENSE.txt",
     "README.markdown",
     "Rakefile",
+    "TODO.md",
     "VERSION",
     "constructable.gemspec",
     "lib/constructable.rb",

data/lib/constructable/attribute.rb

@@ -12,7 +12,7 @@ module Constructable
       },
       {
         name: :validate_type,
-        message: proc {":#{self.name} needs to be of type #{self.validate_type}"},
+        message: proc {":#{self.name} must be of type #{self.validate_type}"},
         check: ->(hash) { hash[self.name].is_a? self.validate_type }
       }
     ]

data/lib/constructable/constructor.rb

@@ -7,9 +7,28 @@ module Constructable
       @module = Module.new
       @base = base
       @base.send :include, @module
+      self.redefine_new_calling
       self.define_concstructable_attributes_method
     end
 
+    def redefine_new_calling
+      case @base
+      when Class
+        self.redefine_new(@base)
+      when Module
+        constructor = self
+        redefine_new_logic = proc do |base|
+          base.instance_variable_set(:@constructor, constructor)
+          if Class == base.class
+            constructor.redefine_new(base)
+          elsif Module == base.class
+            base.define_singleton_method :included, &redefine_new_logic
+          end
+        end
+        @base.define_singleton_method :included, &redefine_new_logic
+      end
+    end
+
     def redefine_new(klass)
       constructor = self
       klass.define_singleton_method(:new) do |*args, &block|
@@ -45,8 +64,14 @@ module Constructable
     end
 
     def generate_attributes(attributes)
+      options = if Hash === attributes.last
+        attributes.pop
+      else
+        {}
+      end
+
       attributes.map do |attribute|
-        Attribute.new(*attribute)
+        Attribute.new(attribute, options)
       end
     end
 

data/lib/constructable/core_ext.rb

@@ -5,7 +5,7 @@ module Constructable
     # @example
     #
     #  class Foo
-    #    constructable [:bar, :readable => true], [:baz, :required => true, :readable => true]
+    #    constructable :bar, :readable => true, :baz, :readable => true, required: true
     #  end
     #
     #  foo = Foo.new(bar: 5)
@@ -19,10 +19,10 @@ module Constructable
     #  # => 7
     #
     #  class ProgrammingLanguage
-    #    constructable [:paradigms,
+    #    constructable :paradigms,
     #      readable: true,
     #      required: true,
-    #      validate: ->(value) { value.is_a?(Array) }]
+    #      validate: ->(value) { value.is_a?(Array) }
     #  end
     #
     #  c = ProgrammingLanguage.new(paradigms: :functional)
@@ -36,22 +36,6 @@ module Constructable
     def constructable(*args)
       @constructor ||= Constructor.new(self)
       @constructor.define_attributes(args)
-      case self
-      when Class
-        @constructor.redefine_new(self)
-      when Module
-        redefine_new_logic = proc do |base|
-
-          base.instance_variable_set(:@constructor, @constructor)
-          if Class == base.class
-            @constructor.redefine_new(base)
-          elsif Module == base.class
-            base.define_singleton_method :included, &redefine_new_logic
-          end
-        end
-
-        define_singleton_method :included, &redefine_new_logic
-      end
       return nil
     end
   end

data/test/constructable/test_attribute.rb

@@ -71,7 +71,7 @@ describe 'Attribute' do
           attribute.process(foo: 'notanumber')
         rescue Exception => e
           assert AttributeError === e, "[#{e.class},#{e.message}] was not expected"
-          assert_equal ':foo needs to be of type Integer', e.message
+          assert_equal ':foo must be of type Integer', e.message
         else
           assert false, 'AttributeError was not raised'
         end

data/test/constructable/test_constructable.rb

@@ -2,61 +2,68 @@ require 'helper'
 describe 'integration' do
   describe 'Class' do
     describe 'constructable' do
+      before do
+        @klass = Class.new
+      end
+
+      it 'has a nice syntax' do
+        @klass.constructable :foo, :bar, accessible: true, validate_type: Integer
+        instance = @klass.new(foo: 5, bar: 2)
+        assert_equal 5, instance.foo
+        assert_raises AttributeError do
+          instance.bar = '5'
+        end
+      end
+
       it 'should assign values found in the constructer hash' do
-        klass = Class.new
-        klass.constructable([:foo, readable: true])
-        instance = klass.new(foo: :bar)
+        @klass.constructable(:foo, readable: true)
+        instance = @klass.new(foo: :bar)
         assert_equal :bar, instance.foo
       end
 
       it 'should work with inheritance' do
-        klass = Class.new
-        klass.constructable([:bar, readable: true])
-        inherited_klass = Class.new(klass)
+        @klass.constructable(:bar, readable: true)
+        inherited_klass = Class.new(@klass)
         instance = inherited_klass.new(bar: 1)
         assert_equal 1, instance.bar
       end
 
       it 'should be possible to make attributes required' do
-        klass = Class.new
-        klass.constructable([:bar, required: true])
+        @klass.constructable(:bar, required: true)
         assert_raises AttributeError do
-          klass.new
+          @klass.new
         end
       end
 
       describe 'should not break the initalize behaviour' do
         it 'works for methods with arguments + options provided' do
-          klass = Class.new
-          klass.constructable [:bar, accessible: true]
-          klass.class_eval do
+          @klass.constructable :bar, accessible: true
+          @klass.class_eval do
             def initialize(options = {})
               self.bar = 20
             end
           end
-          instance = klass.new(bar: 5)
+          instance = @klass.new(bar: 5)
           assert_equal 20, instance.bar
         end
 
         it 'works for initialize methods with arguments' do
-          klass = Class.new
-          klass.constructable [:bar, accessible: true]
-          klass.send :attr_accessor, :baz
-          klass.class_eval do
+          @klass.constructable :bar, accessible: true
+          @klass.send :attr_accessor, :baz
+          @klass.class_eval do
             def initialize(baz, options = {})
               self.baz = baz
             end
           end
 
-          instance = klass.new(1, bar: 5)
+          instance = @klass.new(1, bar: 5)
           assert_equal 1, instance.baz
           assert_equal 5, instance.bar
         end
       end
 
       it 'should return nil' do
-        klass = Class.new
-        assert_equal nil, klass.constructable(:bar)
+        assert_equal nil, @klass.constructable(:bar)
       end
     end
   end

data/test/constructable/test_constructor.rb

@@ -8,13 +8,13 @@ describe 'Constructor' do
   describe 'define_attributes' do
     it 'should define attr_accessors' do
       klass = Class.new
-      klass.constructable([:foo, accessible: true])
+      klass.constructable(:foo, accessible: true)
       assert_respond_to klass.new, :foo
       assert_respond_to klass.new, :foo=
     end
 
     it 'defines public setters validating like in the constructor' do
-      @klass.constructable [:integer, validate_type: Integer, writable: true]
+      @klass.constructable :integer, validate_type: Integer, writable: true
       instance = @klass.new
       assert_raises AttributeError do
         instance.integer = 6.6
@@ -25,14 +25,14 @@ describe 'Constructor' do
 
       describe 'class' do
         it 'getters ' do
-          @klass.constructable [:integer, validate_type: Integer, accessible: true]
+          @klass.constructable :integer, validate_type: Integer, accessible: true
           @klass.class_eval { define_method(:integer){ 1 } }
           instance = @klass.new(integer: 2)
           assert_equal 1, instance.integer
         end
 
         it 'setters ' do
-          @klass.constructable [:integer, validate_type: Integer, accessible: true]
+          @klass.constructable :integer, validate_type: Integer, accessible: true
           @klass.class_eval { def integer=(foo);@integer = 1;end }
           instance = @klass.new(integer: 4)
           instance.integer = 5
@@ -42,7 +42,7 @@ describe 'Constructor' do
 
       describe 'module' do
         before do
-          @module.constructable [:integer, validate_type: Integer, accessible: true]
+          @module.constructable :integer, validate_type: Integer, accessible: true
         end
 
         it 'getters ' do
@@ -74,14 +74,14 @@ describe 'Constructor' do
 
       describe 'allows to super to the generated method' do
         it 'gets' do
-          @klass.constructable [:integer, validate_type: Integer, accessible: true]
+          @klass.constructable :integer, validate_type: Integer, accessible: true
           @klass.class_eval { def integer; super ;end }
           instance = @klass.new(integer: 2)
           assert_equal 2, instance.integer
         end
 
         it 'sets' do
-          @klass.constructable [:integer, validate_type: Integer, accessible: true]
+          @klass.constructable :integer, validate_type: Integer, accessible: true
           @klass.class_eval { def integer=(value); super ;end }
           instance = @klass.new(integer: 2)
           assert_raises Constructable::AttributeError do
@@ -102,21 +102,21 @@ describe 'Constructor' do
 
   describe 'permission' do
     it 'should allow writable attributes' do
-      @klass.constructable [:writable_attribute, writable: true]
+      @klass.constructable :writable_attribute, writable: true
       instance = @klass.new
       instance.writable_attribute = "hello"
       assert_equal "hello", instance.instance_variable_get(:@writable_attribute)
     end
 
     it 'should allow readable attributes' do
-      @klass.constructable [:readable_attribute, readable: true]
+      @klass.constructable :readable_attribute, readable: true
       instance = @klass.new
       instance.instance_variable_set(:@readable_attribute, "hello")
       assert_equal "hello", instance.readable_attribute
     end
 
     it 'should allow accessible attributes' do
-      @klass.constructable [:accessible_attribute, accessible: true]
+      @klass.constructable :accessible_attribute, accessible: true
       instance = @klass.new
       instance.accessible_attribute = 'hello'
       assert_equal 'hello', instance.accessible_attribute
@@ -126,7 +126,7 @@ describe 'Constructor' do
   describe 'module support' do
     before do
       @foo = Module.new do
-        constructable [:foo, readable: true]
+        constructable :foo, readable: true
       end
     end
 

metadata

@@ -2,7 +2,7 @@
 name: constructable
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors: 
 - Manuel Korfmann
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-15 00:00:00 +02:00
+date: 2011-06-17 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -78,6 +78,7 @@ files:
 - LICENSE.txt
 - README.markdown
 - Rakefile
+- TODO.md
 - VERSION
 - constructable.gemspec
 - lib/constructable.rb
@@ -103,7 +104,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 2398714721687136545
+      hash: 932073679521130628
       segments: 
       - 0
       version: "0"