constructor 1.0.0

data/History.txt

@@ -0,0 +1,3 @@
+== 1.0.0 / 2007-11-18
+
+* Released!

data/Manifest.txt

@@ -0,0 +1,6 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/constructor.rb
+specs/constructor_spec.rb

data/README.txt

@@ -0,0 +1,77 @@
+constructor
+
+* http://rubyforge.org/projects/atomicobjectrb/
+* http://atomicobjectrb.rubyforge.org/constructor
+
+== DESCRIPTION:
+  
+Declarative means to define object properties by passing a hash 
+to the constructor, which will set the corresponding ivars.
+
+== FEATURES/PROBLEMS:
+  
+* Declarative constructor definition and ivar initialization 
+
+== SYNOPSIS:
+
+  require 'constructor'
+
+  class Horse
+    constructor :name, :breed, :weight
+  end
+  Horse.new :name => 'Ed', :breed => 'Mustang', :weight => 342
+
+By default the ivars do not get accessors defined.
+But you can get them auto-made if you want:
+
+  class Horse
+    constructor :name, :breed, :weight, :accessors => true
+  end
+  ...
+  puts my_horse.weight
+ 
+Arguments specified are required by default.  You can disable 
+strict argument checking with :strict option.  This means that 
+the constructor will not raise an error if you pass more or 
+fewer arguments than declared.
+
+  class Donkey
+    constructor :age, :odor, :strict => false
+  end
+
+... this allows you to pass either an age or odor key (or neither)
+to the Donkey constructor.
+
+
+== REQUIREMENTS:
+
+* rubygems
+
+== INSTALL:
+
+* sudo gem install constructor
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2007 Atomic Object
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'hoe'
+require './lib/constructor.rb'
+require 'spec/rake/spectask'
+
+
+desc 'Default: run specs'
+task :default => :spec
+Hoe.new('constructor', CONSTRUCTOR_VERSION) do |p|
+  p.rubyforge_name = 'atomicobjectrb'
+  p.author = 'Atomic Object'
+  p.email = 'dev@atomicobject.com'
+  p.summary = 'Declarative, named constructor arguments.'
+  p.description =  p.paragraphs_of('README.txt', 2).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 1).first.gsub(/\* /,'').split(/\n/)
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+end
+
+desc 'Run constructor specs'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['specs/*_spec.rb']
+  t.spec_opts << '-c -f s'
+end

data/lib/constructor.rb

@@ -0,0 +1,106 @@
+CONSTRUCTOR_VERSION = '1.0.0'
+
+class Class
+  def constructor(*attrs)
+    # Look for embedded options in the listing:
+    opts = attrs.find { |a| a.kind_of?(Hash) and attrs.delete(a) } 
+    do_acc = opts.nil? ? false : opts[:accessors] == true
+    require_args = opts.nil? ? true : opts[:strict] != false
+    super_args = opts.nil? ? nil : opts[:super]
+
+    # Incorporate superclass's constructor keys, if our superclass
+    if superclass.constructor_keys
+      attrs = [attrs,superclass.constructor_keys].flatten
+    end
+    # Generate ivar assigner code lines
+    assigns = ''
+    attrs.each do |k|
+      assigns += "@#{k.to_s} = args[:#{k.to_s}]\n"
+    end 
+
+    # If accessors option is on, declare accessors for the attributes:
+    if do_acc
+      self.class_eval "attr_accessor " + attrs.map {|x| ":#{x.to_s}"}.join(',')
+    end
+
+    # If user supplied super-constructor hints:
+    super_call = ''
+    if super_args
+      list = super_args.map do |a|
+        case a
+        when String
+          %|"#{a}"|
+        when Symbol
+          %|:#{a}|
+        end
+      end
+      super_call  = %|super(#{list.join(',')})|
+    end
+
+    # If strict is on, define the constructor argument validator method,
+    # and setup the initializer to invoke the validator method.
+    # Otherwise, insert lax code into the initializer.
+    validation_code = "return if args.nil?"
+    if require_args
+      self.class_eval do 
+        def _validate_constructor_args(args)
+          # First, make sure we've got args of some kind
+          unless args and args.keys and args.keys.size > 0 
+            raise ConstructorArgumentError.new(self.class.constructor_keys)
+          end
+          # Scan for missing keys in the argument hash
+          a_keys = args.keys
+          missing = []
+          self.class.constructor_keys.each do |ck|
+            unless a_keys.member?(ck)
+              missing << ck
+            end
+            a_keys.delete(ck) # Delete inbound keys as we address them
+          end
+          if missing.size > 0 || a_keys.size > 0
+            raise ConstructorArgumentError.new(missing,a_keys)
+          end
+        end
+      end
+      # Setup the code to insert into the initializer:
+      validation_code = "_validate_constructor_args args "
+    end
+
+    # Generate the initializer code
+    self.class_eval %{
+      def initialize(args=nil)
+        #{super_call}
+        #{validation_code}
+        #{assigns}
+        setup if respond_to?(:setup)
+      end
+    }
+
+    # Remember our constructor keys
+    @_ctor_keys = attrs
+  end
+
+  # Access the constructor keys for this class
+  def constructor_keys; @_ctor_keys; end
+end
+
+# Fancy validation exception, based on missing and extraneous keys.
+class ConstructorArgumentError < RuntimeError
+  def initialize(missing,rejected=[])
+    err_msg = ''
+    if missing.size > 0
+      err_msg = "Missing constructor args [#{missing.join(',')}]"
+    end
+    if rejected.size > 0
+      # Some inbound keys were not addressed earlier; this means they're unwanted
+      if err_msg
+        err_msg << "; " # Appending to earlier message about missing items
+      else
+        err_msg = ''
+      end
+      # Enumerate the rejected key names
+      err_msg << "Rejected constructor args [#{rejected.join(',')}]"
+    end
+    super err_msg
+  end
+end

data/specs/constructor_spec.rb

@@ -0,0 +1,319 @@
+require File.expand_path(File.dirname(__FILE__) + '/../lib/constructor') 
+
+class TestingClass
+  attr_accessor :foo, :bar, :why, :qux
+  constructor :foo, :bar, :why, :qux, :strict => false
+
+  def to_pretty_pretty
+    "#{@foo} #{@bar}"
+  end
+
+end
+
+class Mama
+  attr_accessor :fat, :age
+  constructor :age, :strict => false
+  def setup
+    @fat = "much"
+  end
+end
+
+class Baby < Mama
+  constructor :cuteness
+end
+
+class Sissy < Mama
+  attr_accessor :friends, :beauty
+  constructor :beauty, :strict => false
+  def setup
+    super #IMPORTANT!
+    @friends = "many"
+  end
+end
+
+class TestingStrictArgsDefault
+  constructor :foo, :bar
+  def to_pretty_pretty
+    "#{@foo} #{@bar}"
+  end
+end
+
+class TestingStrictArgs
+  constructor :foo, :bar, :strict => true
+  def to_pretty_pretty
+    "#{@foo} #{@bar}"
+  end
+end
+
+class TestingStrictArgs2
+  constructor :foo, :bar, :accessors => true
+end
+
+class SubclassOfTestingClass < TestingClass
+end
+
+class SubclassOfTestingClass2 < TestingClass
+  def initialize; end
+end
+
+class SubclassOfTestingClass3 < TestingClass
+  attr_reader :my_new_var
+  def initialize(hash = nil)
+    super
+    @my_new_var = "something"
+  end
+end
+
+class TestingAutoAccessors
+  constructor :foo, :bar, :why, :qux, :accessors => true, :strict => false
+  def to_pretty_pretty
+    "#{@foo} #{@bar}"
+  end
+end
+
+class TestingSuperConstructorBase
+  attr_reader :a, :b
+  def initialize(a,b)
+    @a = a
+    @b = b
+  end
+end
+
+class TestingSuperConstructor < TestingSuperConstructorBase
+  constructor :far, :away, :accessors => true, :super => ["once", :twice], :strict => false
+end
+
+class TestingSuperConstructorBase2
+  attr_reader :c, :d
+  def initialize
+    @c = 'what a'
+    @d = 'day for'
+  end
+end
+
+class TestingSuperConstructor2 < TestingSuperConstructorBase2
+  constructor :some, :accessors => true, :super => [], :strict => false
+end
+
+class TestingBlockedAccessors
+  constructor :foo, :bar, :accessors => false
+  def to_pretty_pretty
+    "#{@foo} #{@bar}"
+  end
+end
+
+class Papa
+  constructor :car, :saw
+end
+
+class Sonny < Papa
+  constructor :computer, :accessors => true
+end
+
+class Llamma
+  attr_accessor :hungry, :hair
+  constructor :hair
+  def setup
+    @hungry = true
+  end
+end
+  
+describe 'standard constructor usage' do
+  it 'allows for object construction using a hash of named arguments' do
+    fuh = TestingClass.new( 
+      :foo => 'my foo',
+      :bar => 'my bar',
+      :qux => 'my qux',
+      :why => 'lucky'
+    )
+
+    fuh.foo.should eql('my foo')
+    fuh.bar.should eql('my bar') 
+    fuh.qux.should eql('my qux')
+    fuh.why.should eql('lucky')
+    fuh.to_pretty_pretty.should eql('my foo my bar')
+  end
+
+  it 'calls setup method if defined' do
+    ralph = Llamma.new :hair => 'red'
+    ralph.hungry.should be_true
+    ralph.hair.should eql('red')
+  end
+end
+
+describe "constructor's accessor option" do
+  it 'provides accessors for constructor arguments when accessor option is true' do
+    fuh = TestingAutoAccessors.new( 
+      :foo => 'my foo',
+      :bar => 'my bar',
+      :qux => 'my qux',
+      :why => 'lucky'
+    )
+    fuh.foo.should eql('my foo')
+    fuh.bar.should eql('my bar')
+    fuh.qux.should eql('my qux')
+    fuh.why.should eql('lucky')
+    fuh.to_pretty_pretty.should eql('my foo my bar')
+  end
+
+  it 'does not provide accessors for constructor arguments when accessor option is false' do
+    fuh = TestingBlockedAccessors.new :foo => 'my foo', :bar => 'my bar'
+    lambda {fuh.foo}.should raise_error(NoMethodError)
+    lambda {fuh.bar}.should raise_error(NoMethodError)
+    fuh.to_pretty_pretty.should eql('my foo my bar')
+  end
+end
+
+describe 'using constructor with inheritance' do
+  it 'allows for inheritance of constructor arguments using a non-constructor defined subclass' do
+    fuh = SubclassOfTestingClass.new :foo => 'whu?'
+    fuh.foo.should eql('whu?')
+    fuh.bar.should be_nil
+    fuh.qux.should be_nil
+    fuh.why.should be_nil
+  end
+
+  it 'allows for standard construction of a non-constructor subclass of a non-strict constuctor superclass' do
+    fuh = SubclassOfTestingClass2.new 
+    fuh.foo.should be_nil
+  end
+
+  it 'runs initialize method of a sublcass' do
+    fuh = SubclassOfTestingClass3.new
+    fuh.my_new_var.should eql('something')
+    fuh.foo.should be_nil
+    fuh.bar.should be_nil
+    fuh.qux.should be_nil
+    fuh.why.should be_nil
+  end
+
+  it 'passes named constructor args to superclass when subclass calls super' do
+    fuh = SubclassOfTestingClass3.new :foo => 12
+    fuh.my_new_var.should eql('something')
+    fuh.foo.should eql(12)
+    fuh.bar.should be_nil
+    fuh.qux.should be_nil
+    fuh.why.should be_nil
+  end
+
+  it 'allows for inheritance of constructor arguments using a constructor defined subclass' do
+    s = Sonny.new :car => 'Nissan', :saw => 'Dewalt', :computer => 'Dell'
+    s.computer.should eql('Dell')
+    s.saw.should eql('Dewalt')
+    s.car.should eql('Nissan')
+  end
+  
+  it 'calls the setup method on superclass if subclass does not define a setup method' do
+    baby = Baby.new :cuteness => 'little', :age => 1
+    baby.fat.should eql('much')
+  end 
+
+  it 'calls parent class setup when super is called from subclass setup'  do
+    m = Mama.new :age => 55
+    m.age.should eql(55)
+    m.fat.should eql('much')
+    
+    s = Sissy.new :age => 19, :beauty => 'medium', :fat => 'yeah'
+    s.age.should eql(19)
+    s.beauty.should eql('medium')
+    s.fat.should eql('much')
+    s.friends.should eql('many')
+  end
+
+  it 'passes arguments given in the super option to the initializer of a non-constructor defined superclass' do
+    tsc = TestingSuperConstructor.new(:far => 'oo', :away => 'kk')
+    tsc.far.should eql('oo')
+    tsc.away.should eql('kk')
+    tsc.a.should eql("once")
+    tsc.b.should eql(:twice)
+  end 
+
+  it 'calls non-constructor defined superclass constructor when the super option is an empty array' do
+    tsc = TestingSuperConstructor2.new(:some => 'thing')
+    tsc.some.should eql('thing')
+    tsc.c.should eql('what a')
+    tsc.d.should eql('day for')
+  end
+end
+
+describe 'stict mode usage' do
+  it 'allows omission of arguments when strict is off' do
+    fuh = TestingClass.new :foo => 'my foo' 
+    
+    fuh.foo.should eql('my foo')
+    fuh.bar.should be_nil
+    fuh.qux.should be_nil
+    fuh.why.should be_nil
+  end
+
+  it 'allows no arguments to a constructor when strict is off' do
+    fuh = TestingClass.new
+    fuh.foo.should be_nil
+    fuh.bar.should be_nil
+    fuh.qux.should be_nil
+    fuh.why.should be_nil
+  end
+
+  it 'does not interfere with normal object construction' do
+    require 'rexml/document'
+    d = REXML::Document.new '<base/>'
+    d.should_not be_nil
+    d.root.name.should eql('base')
+  end
+
+  def see_strict_args_in_effect_for(clazz)
+    fuh = clazz.new :foo => 'my foo', :bar => 'my bar'
+    fuh.to_pretty_pretty.should eql('my foo my bar')
+
+    # Omit foo
+    lambda {
+      TestingStrictArgsDefault.new :bar => 'ok,yeah'
+    }.should raise_error(ConstructorArgumentError, /foo/)
+    
+    # Omit bar
+    lambda {
+      TestingStrictArgsDefault.new :foo => 'ok,yeah'
+    }.should raise_error(ConstructorArgumentError, /bar/)
+  end
+
+  it 'defaults to strict argument enforcement' do
+    see_strict_args_in_effect_for TestingStrictArgsDefault
+  end
+
+  it 'enforces strict arguments when strict option is true' do
+    see_strict_args_in_effect_for TestingStrictArgs
+  end
+
+  it 'does not allow empty constructor arguments when strict option is true' do
+    lambda {TestingStrictArgs.new {}}.should raise_error(ConstructorArgumentError,/foo,bar/)
+    lambda {TestingStrictArgs.new}.should raise_error(ConstructorArgumentError,/foo,bar/)
+    lambda {TestingStrictArgs.new nil}.should raise_error(ConstructorArgumentError,/foo,bar/)
+  end
+
+  it 'does not allow extraneous arguments when strict option is true' do
+    lambda {
+      TestingStrictArgs.new :foo => 1, :bar => 2, :other => 3, :thing => 4
+    }.should raise_error(ConstructorArgumentError,/thing,other/)
+  end
+
+  it 'allows for setting accessors option while in strict mode' do
+    t2 = TestingStrictArgs2.new :foo => 1, :bar => 2
+    
+    # See that accessors work
+    t2.foo.should eql(1)
+    t2.bar.should eql(2)
+
+    # See that strictness still applies
+    lambda {TestingStrictArgs2.new :no => 'good'}.should raise_error(ConstructorArgumentError)
+  end
+end
+
+describe 'catching ConstructorArgumentError' do
+  it 'allows for generic rescuing of constructor argument errors' do
+    begin
+      TestingStrictArgs.new :broken => 'yoobetcha'
+    rescue => bad_news
+      bad_news.should be_kind_of(ConstructorArgumentError)
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: constructor
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2007-11-18 00:00:00 -05:00
+summary: Declarative, named constructor arguments.
+require_paths: 
+- lib
+email: dev@atomicobject.com
+homepage: http://rubyforge.org/projects/atomicobjectrb/
+rubyforge_project: atomicobjectrb
+description: "== DESCRIPTION:  Declarative means to define object properties by passing a hash  to the constructor, which will set the corresponding ivars."
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Atomic Object
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/constructor.rb
+- specs/constructor_spec.rb
+test_files: []
+
+rdoc_options: 
+- --main
+- README.txt
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.3.0
+    version: