polymorpheus 1.1.3 → 2.0.0

data/README.md

@@ -1,25 +1,42 @@
+[![Build Status](https://travis-ci.org/wegowise/polymorpheus.png?branch=master)](https://travis-ci.org/wegowise/polymorpheus)
+[![Code Climate](https://codeclimate.com/github/wegowise/polymorpheus.png)](https://codeclimate.com/github/wegowise/polymorpheus)
+
 # Polymorpheus
-**Polymorphic relationships in Rails that keep your database happy with almost no setup**
+**Polymorphic relationships in Rails that keep your database happy with almost
+no setup**
 
 ### Background
-* **What is polymorphism?** [Rails Guides has a great overview of what polymorphic relationships are and how Rails handles them](http://guides.rubyonrails.org/association_basics.html#polymorphic-associations)
+* **What is polymorphism?** [Rails Guides has a great overview of what
+  polymorphic relationships are and how Rails handles them](
+  http://guides.rubyonrails.org/association_basics.html#polymorphic-associations)
 
-* **If you don't think database constraints are important** then [here is a presentation that might change your mind](http://bostonrb.org/presentations/databases-constraints-polymorphism). If you're still not convinced, this gem won't be relevant to you.
+* **If you don't think database constraints are important** then [here is a
+  presentation that might change your mind](
+  http://bostonrb.org/presentations/databases-constraints-polymorphism). If
+  you're still not convinced, this gem won't be relevant to you.
 
-* **What's wrong with Rails' built-in approach to polymorphism?** Using Rails, polymorphism is implemented in the database using a `type` column and an `id` column, where the `id` column references one of multiple other tables, depending on the `type`. This violates the basic principle that one column in a database should mean to one thing, and it prevents us from setting up any sort of database constraint on the `id` column.
+* **What's wrong with Rails' built-in approach to polymorphism?** Using Rails,
+  polymorphism is implemented in the database using a `type` column and an `id`
+  column, where the `id` column references one of multiple other tables,
+  depending on the `type`. This violates the basic principle that one column in
+  a database should mean to one thing, and it prevents us from setting up any
+  sort of database constraint on the `id` column.
 
 
 ## Basic Use
 
-We'll outline the use case to mirror the example [outline in the Rails Guides](http://guides.rubyonrails.org/association_basics.html#polymorphic-associations):
+We'll outline the use case to mirror the example [outline in the Rails Guides](
+http://guides.rubyonrails.org/association_basics.html#polymorphic-associations):
 
-* You have a `Picture` object that can belong to an `Imageable`, where an `Imageable` is a polymorphic representation of either an `Employee` or a `Product`.
+* You have a `Picture` object that can belong to an `Imageable`, where an
+  `Imageable` is a polymorphic representation of either an `Employee` or a
+  `Product`.
 
 With Polymorpheus, you would define this relationship as follows:
 
 **Database migration**
 
-```
+```ruby
 class SetUpPicturesTable < ActiveRecord::Migration
   def self.up
     create_table :pictures do |t|
@@ -44,18 +61,18 @@ end
 
 **ActiveRecord model definitions**
 
-```
+```ruby
 class Picture < ActiveRecord::Base
   belongs_to_polymorphic :employee, :product, :as => :imageable
   validates_polymorphic :imageable
 end
 
 class Employee < ActiveRecord::Base
-  has_many :pictures
+  has_many_as_polymorph :pictures
 end
 
 class Product < ActiveRecord::Base
-  has_many :pictures
+  has_many_as_polymorph :pictures
 end
 ```
 
@@ -66,28 +83,57 @@ Now let's review what we've done.
 
 ## Database Migration
 
-* Instead of `imageable_type` and `imageable_id` columns in the pictures table, we've created explicit columns for the `employee_id` and `product_id`
-* The `add_polymorphic_constraints` call takes care of all of the database constraints you need, without you needing to worry about sql! Specifically it:
-  * Creates foreign key relationships in the database as specified. So in this example, we have specified that the `employee_id` column in the `pictures` table should have a foreign key constraint with the `id` column of the `employees` table.
-  * Creates appropriate triggers in our database that make sure that exactly on or the other of `employee_id` or `product_id` are specified for a given record. An exception will be raised if you try to save a database record that contains both or none of them.
-* **Options for migrations**: There are options to customize the foreign keys generated by Polymorpheus and add uniqueness constraints. For more info on this, [read the wiki entry](https://github.com/wegowise/polymorpheus/wiki/Migration-options).
+* Instead of `imageable_type` and `imageable_id` columns in the pictures table,
+  we've created explicit columns for the `employee_id` and `product_id`
+* The `add_polymorphic_constraints` call takes care of all of the database
+  constraints you need, without you needing to worry about sql! Specifically it:
+  * Creates foreign key relationships in the database as specified. So in this
+    example, we have specified that the `employee_id` column in the `pictures`
+    table should have a foreign key constraint with the `id` column of the
+    `employees` table.
+  * Creates appropriate triggers in our database that make sure that exactly one
+    or the other of `employee_id` or `product_id` are specified for a given
+    record. An exception will be raised if you try to save a database record
+    that contains both or none of them.
+* **Options for migrations**: There are options to customize the foreign keys
+  generated by Polymorpheus and add uniqueness constraints. For more info
+  on this, [read the wiki entry](https://github.com/wegowise/polymorpheus/wiki/Migration-options).
 
 ## Model definitions
 
-* The `belongs_to_polymorphic` declaration in the `Picture` class specifies the polymorphic relationship. It provides all of the same methods that Rails does for it's built-in polymorphic relationships, plus a couple additional features. See the Interface section below.
-* `validates_polymorph` declaration: checks that exactly one of the possible polymorphic relationships is specified. In this example, either an `employee_id` or `product_id` must be specified -- if both are nil or if both are non-nil a validation error will be added to the object.
-* The `has_many` declarations are just normal Rails declarations.
-
+* The `belongs_to_polymorphic` declaration in the `Picture` class specifies the
+  polymorphic relationship. It provides all of the same methods that Rails does
+  for its built-in polymorphic relationships, plus a couple additional features.
+  See the Interface section below.
+* `validates_polymorph` declaration: checks that exactly one of the possible
+  polymorphic relationships is specified. In this example, either an
+  `employee_id` or `product_id` must be specified -- if both are nil or if both
+  are non-nil a validation error will be added to the object.
+* The `has_many_as_polymorph` declaration generates a normal Rails `has_many`
+  declaration, but adds a constraint that ensures that the correct records are
+  retrieved. This means you can still use the same conditions with it that you
+  would use with a `has_many` association (such as `:order`, `:class_name`,
+  etc.). Specifically, the `has_many_as_polymorph` declaration in the `Employee`
+  class of the example above is equivalant to
+  `has_many :pictures, { picture_id: nil }`
+  and the `has_many_as_polymorph` declaration in the `Product` class is
+  equivalent to `has_many :pictures, { employee_id: nil }`
 
 ## Requirements / Support
 
-* Currently the gem only supports MySQL. Postgres support is planned; please feel free to fork and submit a (well-tested) pull request if you want to add Postgres support before then.
-* This gem is tested and has been tested for Rails 2.3.8, 3.0.x, 3.1.x and 3.2.x
-* For Rails 3.1+, you'll still need to use `up` and `down` methods in your migrations.
+* Currently the gem only supports MySQL. Please feel free to fork and submit a
+  (well-tested) pull request if you want to add Postgres support.
+* This gem is tested and has been tested for Rails 2.3.8, 3.0.x, 3.1.x, 3.2.x,
+  and 4.0.0
+* For Rails 3.1+, you'll still need to use `up` and `down` methods in your
+  migrations.
 
 ## Interface
 
-The nice thing about Polymorpheus is that under the hood it builds on top of the Rails conventions you're already used to which means that you can interface with your polymorphic relationships in simple, familiar ways. There are also a number of helpful interface helpers that you can use.
+The nice thing about Polymorpheus is that under the hood it builds on top of the
+Rails conventions you're already used to which means that you can interface with
+your polymorphic relationships in simple, familiar ways. It also lets you
+introspect on the polymorphic associations.
 
 Let's use the example above to illustrate.
 
@@ -101,11 +147,12 @@ pic = Picture.new
 pic.imageable
  => nil
 
-# the following two options are equivalent, just as they are normally with ActiveRecord:
+# The following two options are equivalent, just as they are normally with
+# ActiveRecord:
 #   pic.employee = sam
 #   pic.employee_id = sam.id
 
-# if we specify an employee, the imageable getter method will return that employee:
+# If we specify an employee, the imageable getter method will return that employee:
 pic.employee = sam;
 pic.imageable
  => #<Employee id: 1, name: "Sam">
@@ -114,32 +161,43 @@ pic.employee
 pic.product
  => nil
 
-# if we specify a product, the imageable getting will return that product:
+# If we specify a product, the imageable getting will return that product:
 Picture.new(product: nintendo).imageable
  => #<Product id: 1, name: "Nintendo">
 
-# but if we specify an employee and a product, the getter will know this makes no sense and return nil for the imageable:
+# But, if we specify an employee and a product, the getter will know this makes
+# no sense and return nil for the imageable:
 Picture.new(employee: sam, product: nintendo).imageable
  => nil
 
-# There are some useful helper methods:
+# A `polymorpheus` instance method is attached to your model that allows you
+# to introspect:
 
-pic.imageable_active_key
- => "employee_id"
+pic.polymorpheus.associations
+ => [
+      #<Polymorpheus::InterfaceBuilder::Association:0x007f88b5528b00 @name="employee">,
+      #<Polymorpheus::InterfaceBuilder::Association:0x007f88b55289c0 @name="picture">
+    ]
 
-pic.imageable_query_condition
- => {"employee_id"=>"1"}
+pic.polymorpheus.associations.map(&:name)
+ => ["employee", "product"]
+
+pic.polymorpheus.associations.map(&:key)
+ => ["employee_id", "product_id"]
 
-pic.imageable_types
- => ["employee", "picture"]
+pic.polymorpheus.active_association
+ => #<Polymorpheus::InterfaceBuilder::Association:0x007f88b5528b00 @name="employee">,
 
-Picture::IMAGEABLE_KEYS
- => ["employee_id", "picture_id"]
+pic.polymorpheus.query_condition
+ => {"employee_id"=>"1"}
 ```
 
 ## Credits and License
 
 * This gem was written by [Barun Singh](https://github.com/barunio)
-* It uses the [Foreigner gem](https://github.com/matthuhiggins/foreigner) under the hood for a few things
+* It uses the [Foreigner gem](https://github.com/matthuhiggins/foreigner) under
+  the hood for a few things
 
-polymorpheus is Copyright © 2011-2012 Barun Singh and [WegoWise](http://wegowise.com). It is free software, and may be redistributed under the terms specified in the LICENSE file.
+polymorpheus is Copyright © 2011-2012 Barun Singh and [WegoWise](
+http://wegowise.com). It is free software, and may be redistributed under the
+terms specified in the LICENSE file.

data/lib/polymorpheus.rb

@@ -1,9 +1,14 @@
 module Polymorpheus
   autoload :Adapter, 'polymorpheus/adapter'
   autoload :Interface, 'polymorpheus/interface'
+  autoload :InterfaceBuilder, 'polymorpheus/interface_builder'
   autoload :Trigger, 'polymorpheus/trigger'
   autoload :SchemaDumper, 'polymorpheus/schema_dumper'
 
+  class InterfaceBuilder
+    autoload :Association, 'polymorpheus/interface_builder/association'
+  end
+
   module ConnectionAdapters
     autoload :SchemaStatements, 'polymorpheus/schema_statements'
   end

data/lib/polymorpheus/interface.rb

@@ -22,81 +22,71 @@ module Polymorpheus
 
     module ClassMethods
 
-      def belongs_to_polymorphic(*args)
-        options = args.extract_options!
+      def belongs_to_polymorphic(*association_names, options)
         polymorphic_api = options[:as]
-        associations = args.collect(&:to_s).collect(&:downcase)
-        association_keys = associations.collect{|association| "#{association}_id"}
-
-        # Set belongs_to assocaitions
-        associations.each do |associated_model|
-          belongs_to associated_model.to_sym
-        end
-
-        # Class constant defining the keys
-        const_set "#{polymorphic_api}_keys".upcase, association_keys
-
-        # Helper methods and constants
-        define_method "#{polymorphic_api}_types" do
-          associations
+        builder = Polymorpheus::InterfaceBuilder.new(polymorphic_api,
+                                                     association_names)
+
+        # The POLYMORPHEUS_ASSOCIATIONS constant is useful for two reasons:
+        #
+        # 1. It is useful for other classes to be able to ask this class
+        #    about its polymorphic relationship.
+        #
+        # 2. It prevents a class from defining multiple polymorphic
+        #    relationships. Doing so would be a bad idea from a design
+        #    standpoint, and we don't want to allow for (and support)
+        #    that added complexity.
+        #
+        const_set('POLYMORPHEUS_ASSOCIATIONS', builder.association_names)
+
+        # Set belongs_to associations
+        builder.associations.each do |association|
+          belongs_to association.name.to_sym
         end
 
-        define_method "#{polymorphic_api}_active_key" do
-          keys = association_keys.select { |key| self.send(key).present? }
-          keys.first if keys.length == 1
-        end
-
-        define_method "#{polymorphic_api}_query_condition" do
-          fk = self.send("#{polymorphic_api}_active_key")
-          { fk.to_s => self.send(fk) } if fk
+        # Exposed interface for introspection
+        define_method 'polymorpheus' do
+          builder.exposed_interface(self)
         end
 
         # Getter method
         define_method polymorphic_api do
-          if key = self.send("#{polymorphic_api}_active_key")
-            # we are connecting to an existing item in the db
-            self.send key.gsub(/_id$/,'')
-          else
-            # we can also link to a new record if we're careful
-            objs = associations.map { |association| self.send(association) }.compact
-            objs.first if objs.length == 1
-           end
+          builder.get_associated_object(self)
         end
 
         # Setter method
-        define_method "#{polymorphic_api}=" do |polymorphic_obj|
-
-          klass_ancestors = polymorphic_obj.class
-                            .ancestors.map(&:name).compact.map(&:underscore)
-          match = associations & klass_ancestors
-
-          if match.blank?
-            raise Polymorpheus::Interface::InvalidTypeError, associations
-          elsif match.length > 1
-            raise Polymorpheus::Interface::AmbiguousTypeError
-          else
-            accessor = "#{polymorphic_obj.class.base_class.name.underscore}_id="
-            self.send(accessor, polymorphic_obj.id)
-            (associations - match).each do |association_to_reset|
-              self.send("#{association_to_reset}_id=", nil)
-            end
-          end
+        define_method "#{polymorphic_api}=" do |object_to_associate|
+          builder.set_associated_object(self, object_to_associate)
         end
+      end
 
-        # Private method called as part of validation
-        # Validate that there is exactly one associated object
-        define_method "polymorphic_#{polymorphic_api}_relationship_is_valid" do
-          if !self.send(polymorphic_api)
-            self.errors.add(:base,
-              "You must specify exactly one of the following: {#{associations.join(', ')}}")
-          end
-        end
-        private "polymorphic_#{polymorphic_api}_relationship_is_valid"
+      def has_many_as_polymorph(association, options = {})
+        options.symbolize_keys!
+        conditions = options.fetch(:conditions, {})
+        fkey = name.foreign_key
+
+        class_name = options[:class_name] || association.to_s.classify
 
+        options[:conditions] = proc {
+          keys = class_name.constantize
+                  .const_get('POLYMORPHEUS_ASSOCIATIONS')
+                  .map(&:foreign_key)
+          keys.delete(fkey)
+
+          keys.reduce({}) { |hash, key| hash.merge!(key => nil) }
+        }
+
+        has_many association, options
       end
 
       def validates_polymorph(polymorphic_api)
-        validate "polymorphic_#{polymorphic_api}_relationship_is_valid"
+        validate Proc.new {
+          unless polymorpheus.active_association
+            association_names = polymorpheus.associations.map(&:name)
+            errors.add(:base, "You must specify exactly one of the following: "\
+                              "{#{association_names.join(', ')}}")
+          end
+        }
       end
 
     end

data/lib/polymorpheus/interface_builder.rb

@@ -0,0 +1,93 @@
+require 'ostruct'
+
+module Polymorpheus
+  class InterfaceBuilder
+
+    attr_reader :interface_name,
+                :associations
+
+    def initialize(interface_name, association_names)
+      @interface_name = interface_name
+      @associations = association_names.map do |association_name|
+        Polymorpheus::InterfaceBuilder::Association.new(association_name)
+      end
+    end
+
+    def exposed_interface(calling_object)
+      OpenStruct.new(
+        associations: associations,
+        active_association: active_association(calling_object),
+        query_condition: query_condition(calling_object)
+      )
+    end
+
+    def association_keys
+      @association_keys ||= associations.map(&:key)
+    end
+
+    def association_names
+      @association_names ||= associations.map(&:name)
+    end
+
+    def active_association(calling_object)
+      active_associations = associations.select do |association|
+        # If the calling object has a non-nil value for the association
+        # key, we know it has an active associatin without having to
+        # make a database query to retrieve the associated object itself.
+        #
+        # If it has a nil value for the association key, we then ask if
+        # it has a non-nil result for the association itself, since it
+        # may have an active association that has not yet been saved to
+        # the database.
+        #
+        calling_object.public_send(association.key).present? ||
+          calling_object.public_send(association.name).present?
+      end
+
+      active_associations.first if active_associations.length == 1
+    end
+
+    def active_association_key(calling_object)
+      association = active_association(calling_object)
+      return unless association
+
+      association.key if calling_object.public_send(association.key)
+    end
+
+    def query_condition(calling_object)
+      key = active_association_key(calling_object)
+      object = calling_object.public_send(key) if key
+
+      { key.to_s => object } if object
+    end
+
+    def get_associated_object(calling_object)
+      association = active_association(calling_object)
+      calling_object.public_send(association.name) if association
+    end
+
+    def set_associated_object(calling_object, object_to_associate)
+      association = get_relevant_association_for_object(object_to_associate)
+      calling_object.public_send("#{association.name}=", object_to_associate)
+
+      (associations - [association]).each do |association|
+        calling_object.public_send("#{association.name}=", nil)
+      end
+    end
+
+    def get_relevant_association_for_object(object_to_associate)
+      match = associations.select do |association|
+        object_to_associate.is_a?(association.association_class)
+      end
+
+      if match.blank?
+        raise Polymorpheus::Interface::InvalidTypeError, association_names
+      elsif match.length > 1
+        raise Polymorpheus::Interface::AmbiguousTypeError
+      end
+
+      match.first
+    end
+
+  end
+end

data/lib/polymorpheus/interface_builder/association.rb

@@ -0,0 +1,23 @@
+module Polymorpheus
+  class InterfaceBuilder
+    class Association
+
+      include ActiveSupport::Inflector
+
+      attr_reader :name,
+                  :key
+
+      def initialize(name)
+        @name = name.to_s.downcase
+        @key = "#{@name}_id"
+      end
+
+      # The association class may not be loaded at the time this object
+      # is initialized, so we can't set it via an accessor in the initializer.
+      def association_class
+        @association_class ||= name.classify.constantize
+      end
+
+    end
+  end
+end

data/lib/polymorpheus/version.rb

@@ -1,3 +1,3 @@
 module Polymorpheus
-  VERSION = '1.1.3'
+  VERSION = '2.0.0'
 end

data/spec/interface_spec.rb

@@ -11,16 +11,18 @@ class Shoe < ActiveRecord::Base
 end
 
 class Man < ActiveRecord::Base
+  has_many_as_polymorph :shoes
 end
 
 class Woman < ActiveRecord::Base
+  has_many_as_polymorph :shoes, order: 'id DESC'
 end
 
 class Dog < ActiveRecord::Base
 end
 
 class Glove < ActiveRecord::Base
-  belongs_to_polymorphic :gentleman, :as => :wearer
+  belongs_to_polymorphic :gentleman, :gentlewoman, :as => :wearer
   validates_polymorph :wearer
 end
 
@@ -30,26 +32,47 @@ end
 class Knight < Gentleman
 end
 
-describe Shoe do
-
-  let(:shoe) { Shoe.new(attributes) }
-  let(:man) { Man.create! }
-  let(:woman) { Woman.create! }
+class Gentlewoman < Woman
+end
 
-  describe "class level constant" do
-    specify { Shoe::WEARER_KEYS.should == ["man_id", "woman_id"] }
+describe '.belongs_to_polymorphic' do
+  it 'sets conditions on association to ensure we retrieve correct result' do
+    man = Man.create!
+    man.shoes.to_sql.squish
+      .should == %{SELECT `shoes`.* FROM `shoes`
+                   WHERE `shoes`.`man_id` = 1
+                   AND `shoes`.`woman_id` IS NULL}.squish
   end
 
-  describe "helper methods" do
-    specify { Shoe.new.wearer_types.should == ["man", "woman"] }
+  it 'supports existing conditions on the association' do
+    woman = Woman.create!
+    woman.shoes.to_sql.squish
+      .should == %{SELECT `shoes`.* FROM `shoes`
+                   WHERE `shoes`.`woman_id` = 1
+                   AND `shoes`.`man_id` IS NULL
+                   ORDER BY id DESC}.squish
   end
 
-  it "make the dynamically defined validation method private" do
-    Shoe.private_instance_methods.
-      include?(:polymorphic_wearer_relationship_is_valid).should be_true
+  it 'returns the correct result when used with new records' do
+    woman = Woman.create!
+    shoe = Shoe.create!(woman: woman, other_id: 10)
+    Man.new.shoes.where(other_id: 10).should == []
   end
+end
+
+describe "polymorphic interface" do
+
+  let(:man) { Man.create! }
+  let(:woman) { Woman.create! }
+  let(:gentleman) { Gentleman.create! }
+  let(:knight) { Knight.create! }
 
-  describe "dynamic generated setter" do
+  specify { Shoe::POLYMORPHEUS_ASSOCIATIONS.should == %w[man woman] }
+  specify { Glove::POLYMORPHEUS_ASSOCIATIONS.should == %w[gentleman
+                                                          gentlewoman] }
+
+  describe "setter methods for ActiveRecord objects" do
+    let(:shoe) { Shoe.new(attributes) }
     let(:attributes) { {} }
 
     it "sets the correct attribute value for the setter" do
@@ -73,76 +96,105 @@ describe Shoe do
                         "Invalid type. Must be one of {man, woman}")
     end
 
-    it "does not throw an error if the assigned object is a subclass of a valid type" do
-      gentleman = Gentleman.create!
+    it "does not throw an error if the assigned object is a subclass of a
+    valid type" do
       expect { shoe.wearer = gentleman }.not_to raise_error
       shoe.man_id.should == gentleman.id
     end
 
-    it "does not throw an error if the assigned object is a descendant of a valid type" do
-      knight = Knight.create!
+    it "does not throw an error if the assigned object is a descendant of a
+    valid type" do
       expect { shoe.wearer = knight }.not_to raise_error
       shoe.man_id.should == knight.id
     end
+  end
 
-    it "does not throw an error if the association is to a parent class of
-    assigned object that is not the base" do
-      glove = Glove.new({})
-      knight = Knight.create!
-      expect { glove.wearer = knight }.not_to raise_error
-      glove.man_id.should == knight.id
+  describe "setter methods for objects inheriting from ActiveRecord objects" do
+    let(:glove) { Glove.new }
+
+    it "throws an error if the assigned object is an instance of the parent
+    ActiveRecord class" do
+      expect { glove.wearer = man }.to raise_error(
+        Polymorpheus::Interface::InvalidTypeError,
+        "Invalid type. Must be one of {gentleman, gentlewoman}"
+      )
     end
 
-    it "throws an error if assigned object is a less specific instance of the association" do
-      glove = Glove.new({})
-      man = Man.create!
-      expect { glove.wearer = man }
-        .to raise_error(Polymorpheus::Interface::InvalidTypeError,
-                        "Invalid type. Must be one of {gentleman}")
+    it "works if the assigned object is of the specified class" do
+      expect { glove.wearer = gentleman }.not_to raise_error
+      glove.gentleman_id.should == gentleman.id
+    end
+
+    it "works if the assigned object is an instance of a child class" do
+      expect { glove.wearer = knight }.not_to raise_error
+      glove.gentleman_id.should == knight.id
     end
   end
 
-  shared_examples_for "invalid polymorphic relationship" do
-    specify { shoe.wearer.should == nil }
-    specify { shoe.wearer_active_key.should == nil }
-    specify { shoe.wearer_query_condition.should == nil }
-    it "validates appropriately" do
-      shoe.valid?.should be_false
+  describe '.validates_polymorph validation' do
+    specify { Shoe.new(wearer: man).valid?.should == true }
+    specify { Shoe.new(wearer: woman).valid?.should == true }
+    specify { Shoe.new(man_id: man.id).valid?.should == true }
+    specify { Shoe.new(man: man).valid?.should == true }
+    specify { Shoe.new(man: Man.new).valid?.should == true }
+
+    it 'is invalid if no association is specified' do
+      shoe = Shoe.new
+      shoe.valid?.should == false
       shoe.errors[:base].should ==
         ["You must specify exactly one of the following: {man, woman}"]
     end
-  end
 
-  context "when there is no relationship defined" do
-    let(:attributes) { {} }
-    it_should_behave_like "invalid polymorphic relationship"
+    it 'is invalid if multiple associations are specified' do
+      shoe = Shoe.new(man_id: man.id, woman_id: woman.id)
+      shoe.valid?.should == false
+      shoe.errors[:base].should ==
+        ["You must specify exactly one of the following: {man, woman}"]
+    end
   end
 
-  context "when there are multiple relationships defined" do
-    let(:attributes) { { man_id: man.id, woman_id: woman.id } }
-    it_should_behave_like "invalid polymorphic relationship"
-  end
+  describe '#polymorpheus exposed interface method' do
+    subject(:interface) { shoe.polymorpheus }
 
-  context "when there is exactly one relationship defined" do
-    shared_examples_for "valid polymorphic relationship" do
-      specify { shoe.wearer.should == man }
-      specify { shoe.wearer_active_key.should == 'man_id' }
-      specify { shoe.wearer_query_condition.should == { 'man_id' => man.id } }
+    context 'when there is no relationship defined' do
+      let(:shoe) { Shoe.new }
+
+      its(:associations) { should match_associations(:man, :woman) }
+      its(:active_association) { should == nil }
+      its(:query_condition) { should == nil }
     end
-    context "and we have specified it via the id value" do
-      let(:attributes) { { man_id: man.id } }
-      it_should_behave_like "valid polymorphic relationship"
+
+    context 'when there is are multiple relationships defined' do
+      let(:shoe) { Shoe.new(man_id: man.id, woman_id: woman.id) }
+
+      its(:associations) { should match_associations(:man, :woman) }
+      its(:active_association) { should == nil }
+      its(:query_condition) { should == nil }
+    end
+
+    context 'when there is one relationship defined through the id value' do
+      let(:shoe) { Shoe.new(man_id: man.id) }
+
+      its(:associations) { should match_associations(:man, :woman) }
+      its(:active_association) { be_association(:man) }
+      its(:query_condition) { should == { 'man_id' => man.id } }
     end
-    context "and we have specified it via the id value" do
-      let(:attributes) { { man: man } }
-      it_should_behave_like "valid polymorphic relationship"
+
+    context 'when there is one relationship defined through the setter' do
+      let(:shoe) { Shoe.new(wearer: man) }
+
+      its(:associations) { should match_associations(:man, :woman) }
+      its(:active_association) { be_association(:man) }
+      its(:query_condition) { should == { 'man_id' => man.id } }
     end
-    context "and the record we are linking to is a new record" do
+
+    context 'when there is one association, to a new record' do
       let(:new_man) { Man.new }
-      let(:attributes) { { man: new_man } }
-      specify { shoe.wearer.should == new_man }
-      specify { shoe.wearer_active_key.should be_nil }
-      specify { shoe.wearer_query_condition.should be_nil }
+      let(:shoe) { Shoe.new(wearer: new_man) }
+
+      its(:associations) { should match_associations(:man, :woman) }
+      its(:active_association) { be_association(:man) }
+      its(:query_condition) { should == nil }
     end
   end
 

data/spec/spec_helper.rb

@@ -14,10 +14,11 @@ ActiveRecord::Schema.define do
   create_table :shoes do |t|
     t.integer :man_id
     t.integer :woman_id
+    t.integer :other_id
   end
   create_table :gloves do |t|
-    t.integer :man_id
-    t.integer :woman_id
+    t.integer :gentleman_id
+    t.integer :gentlewoman_id
   end
   create_table :men do |t|
     t.string :type
@@ -26,3 +27,19 @@ ActiveRecord::Schema.define do
   create_table :dogs
 end
 
+
+RSpec::Matchers.define :be_association do |association_name|
+  match do |actual|
+    actual.should be_instance_of(Polymorpheus::InterfaceBuilder::Association)
+    actual.name.should == association_name.to_s
+  end
+end
+
+RSpec::Matchers.define :match_associations do |*association_names|
+  match do |actual|
+    actual.length.should == association_names.length
+    actual.each_with_index do |item, ind|
+      item.should be_association(association_names[ind])
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polymorpheus
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-10 00:00:00.000000000 Z
+date: 2013-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: foreigner
@@ -85,6 +85,8 @@ extra_rdoc_files:
 files:
 - lib/polymorpheus/adapter.rb
 - lib/polymorpheus/interface.rb
+- lib/polymorpheus/interface_builder/association.rb
+- lib/polymorpheus/interface_builder.rb
 - lib/polymorpheus/mysql_adapter.rb
 - lib/polymorpheus/railtie.rb
 - lib/polymorpheus/schema_dumper.rb
@@ -124,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Provides a database-friendly method for polymorphic relationships