joinfix 0.1.1 → 1.0.0

data/lib/joinfix.rb

@@ -3,26 +3,34 @@ require 'active_record/fixtures'
 require 'joinfix/fixtures_class'
 require 'joinfix/fixtures'
 require 'joinfix/fixture'
+require 'joinfix/error'
 
-# The actual JoinFix module contains methods managing joins.  In practice, JoinFix
-# extends hashes that contain the entry data.  Calls to the join_(type) methods define
-# join references like ['child_id', 'child_table'] => 'child_entry_name'.  This reference
-# specifies that 'child_id' should be set to the primary key of 'child_entry_name' in 
-# 'child_table'.
+# The JoinFix module contains methods to make joins.  In practice, JoinFix
+# extends hashes that contain the entry data.  Joins are created by calling the
+# join_(macro) methods, which creates join references like:
 #
-# The join methods each take a child entry and a config.  The instance calling the join
-# method is considered the parent entry.  References are added where appropriate.
-# A separate join entry will be returned if required, as for has_and_belongs_to_many
-# or has_many :through.
+#   ['child_id', 'child_table'] => 'child_entry_name'
 #
-# The configurations required by the join methods can be created from an ActiveRecord::Base
-# class and the name of the association through the +configure+ method.
+# Later on these references are resolved so that 'child_id' will be set to 
+# the primary key of 'child_entry_name' in 'child_table'.
+#
+# The hash extended by the JoinFix module is considered the parent entry.  Each
+# join_(macro) method takes a child entry and a config specifiying details of the join.   
+# A separate join entry will be returned if required (as for 'has_and_belongs_to_many' 
+# or 'has_many :through').  The configurations required by the join methods can be 
+# created by providing an ActiveRecord::Base class and association name to 
+# +configure+.
+#
+# A little terminology:
+# macro:: Refers to the join macro (ex :belongs_to, :has_many)
+# associable:: The association name in a belongs_to :polymorphic association
+# associable_type:: The field holding the class name of the associated entry (ie "#{association.name}_type") in a belongs_to :polymorphic association
 module JoinFix
 	class << self
 		# Returns true if the input macro allows for multiple joins. 
 		#
-		# [:belongs_to, :has_one] => false
-		# [:has_many, :has_and_belongs_to_many] => true
+		#   [:belongs_to, :has_one] => false
+		#   [:has_many, :has_and_belongs_to_many] => true
 		def macro_allows_multiple(macro)
 			case macro.to_sym
 			when :belongs_to then false
@@ -32,23 +40,22 @@ module JoinFix
 			end
 		end
 		
-		def configure(klass, assoc_name)
-			association = association(klass, assoc_name)
-			send("configure_#{association.macro}", klass, association).with_indifferent_access
-		end
-		
-		protected
-		
-		def association(klass, assoc_name)
-			association = klass.reflect_on_association(assoc_name.to_sym)
-			raise ArgumentError, "Unknown association '#{assoc_name}' for '#{klass}'."  unless association
-			association.check_validity!
-			association
+    # Constructs a join configuration for the specified assocation. 
+		def configure(active_record_class, assoc_name)
+			association = association(active_record_class, assoc_name)
+			send("configure_#{association.macro}", active_record_class, association).with_indifferent_access
 		end
-		
-		def configure_belongs_to(klass, association)
+		    
+    # Returns a hash of configurations for a belongs_to association.
+    #
+    # Returns configurations:
+    #   [:macro,:parent_table, :foreign_key, :child_table]
+	  #
+	  # Returned configurations for belongs_to :polymorphic
+	  #   [:macro, parent_table, :foreign_key, :polymorphic (=true), :associable, :associable_type]
+		def configure_belongs_to(active_record_class, association)
 			join_config = {
-				:parent_table => klass.table_name,
+				:parent_table => active_record_class.table_name,
 				:macro => association.macro,
 				:foreign_key => association.primary_key_name
 			}
@@ -64,9 +71,13 @@ module JoinFix
 			join_config
 		end
 		
-		def configure_has_one(klass, association)
+    # Returns a hash of configurations for a has_one association
+    #
+    # Returns configurations:
+	  #   [:macro, :parent_table, :child_table, :foreign_key]
+		def configure_has_one(active_record_class, association)
 			join_config = {
-				:parent_table => klass.table_name,
+				:parent_table => active_record_class.table_name,
 				:child_table => association.table_name,
 				:macro => association.macro,
 				:foreign_key => association.primary_key_name
@@ -75,9 +86,19 @@ module JoinFix
 			join_config
 		end
 		
-		def configure_has_many(klass, association)
+    # Returns a hash of configurations for a has_many association
+    #
+    # Returns configurations:
+	  #   [:macro, :parent_table, :child_table, :foreign_key]
+    #
+    # Returned configurations for has_many :as
+    #   [:macro, :parent_table, :child_table, :foreign_key, :as, :parent_class]
+    #
+    # Returned configurations for has_many :through
+    #   [:macro, :parent_table, :child_table, :through, :join_table, :foreign_key, :association_foreign_key]
+		def configure_has_many(active_record_class, association)
 			join_config = {
-				:parent_table => klass.table_name,
+				:parent_table => active_record_class.table_name,
 				:child_table => association.table_name,
 				:macro => association.macro,
 				:foreign_key => association.primary_key_name
@@ -85,7 +106,7 @@ module JoinFix
 			
 			if association.options[:as]
 				join_config[:as] = association.options[:as]
-				join_config[:parent_class] = klass.class_name
+				join_config[:parent_class] = active_record_class.class_name
 			elsif association.options[:through]
 				join_config[:through] = association.options[:through]
 				join_config[:join_table] = association.through_reflection.table_name
@@ -96,9 +117,13 @@ module JoinFix
 			join_config
 		end
 		
-		def configure_has_and_belongs_to_many(klass, association)
+    # Returns a hash of configurations for a has_and_belongs_to_many association
+    #
+    # Returns configurations:
+	  #   [:macro, :parent_table, :child_table, :join_table, :foreign_key, :association_foreign_key]
+		def configure_has_and_belongs_to_many(active_record_class, association)
 			join_config = {
-				:parent_table => klass.table_name,
+				:parent_table => active_record_class.table_name,
 				:child_table => association.table_name,
 				:macro => association.macro,
 				:join_table => association.options[:join_table],
@@ -108,37 +133,46 @@ module JoinFix
 			
 			join_config
 		end
+    
+		protected
+		
+    # Looks up the association and checks that the association is valid.
+		def association(active_record_class, assoc_name) # :nodoc: 
+			association = active_record_class.reflect_on_association(assoc_name.to_sym)
+			raise ArgumentError, "Unknown association '#{assoc_name}' for '#{active_record_class}'."  unless association
+			association.check_validity!
+			association
+		end
 	end
 	
-	# Convenience method for setting up a JoinFix.
+  attr_accessor :entry_name
+  
+	# Convenience method for setting up a JoinFix.  Simply takes the input hash  extends with 
+  # JoinFix and sets the entry_name.
 	def self.new(entry_name, hash={})
 		hash.extend JoinFix
 		hash.entry_name = entry_name
 		hash
 	end
 
-	attr_accessor :entry_name
-
-	# extract_if extracts values where the key is specified
-	# or returns true when passed to the optional block.
-	def extract_if(keys=[], &block)
+	# Extracts values if the key is specified in keys or if the block returns true.
+	def extract_if(keys=[], &block) # :yields: key, value
 		extract(:if, keys, block)
 	end
 	
-	# extract_unless extracts values where the key is not specified
-	# or does not return true when passed to the optional block.
-	def extract_unless(keys=[], &block)
+	# Extracts values unless the key is specified in keys or if the block returns false.
+	def extract_unless(keys=[], &block) # :yields: key, value
 		extract(:unless, keys, block)
 	end
 	
-	# Creates the required key-value pairs for a 'belongs_to' association between the fixture 
-	# and the input entry.  Returns nil
+	# Creates the required key-value pairs for a 'belongs_to' association between self
+	# and the input entry.  Returns nil.
 	#
 	# Required configurations:
-	# * [:foreign_key, :child_table]
+	#   [:foreign_key, :child_table]
 	#
 	# Required configurations for belongs_to :polymorphic
-	# * [:polymorphic (=true), :associable, :foreign_key, :child_table, :child_class]
+	#   [:associable, :child_table, :child_class, :polymorphic (=true),  :foreign_key]
 	def join_belongs_to(entry, config)
 		if config[:polymorphic]
 			# produce entries like:
@@ -162,11 +196,11 @@ module JoinFix
 		nil
 	end
 	
-	# Creates the required key-value pairs for a 'has_one' association between the fixture 
-	# and the input entry.  Returns nil
+	# Creates the required key-value pairs for a 'has_one' association between self 
+	# and the input entry.  Returns nil.
 	#
 	# Required configurations:
-	# * [:foreign_key, :parent_table]
+	#   [:parent_table, :foreign_key]
 	def join_has_one(entry, config)
 		# produces entries like:
 		#   entry[foreign_key_ref_parent_table] = self.entry_name
@@ -178,41 +212,18 @@ module JoinFix
 		nil
 	end
 	
-	# Creates the required key-value pairs for a 'has_and_belongs_to_many' association between 
-	# the fixture and the input entry.  Returns a join entry.
-	#
-	# Required configurations:
-	# * [:foreign_key, :association_foreign_key, :parent_table, :child_table]
-	def join_has_and_belongs_to_many(entry, config)
-		# produces entries like:
-		#   join[foreign_key_ref_parent_table] = self.entry_name
-		#   join[association_foreign_key_ref_child_table] = entry.entry_name
-		# later resolved to:
-		#   join[foreign_key_id] = self.id
-		#   join[association_foreign_key_id] = entry.id
-		validate_inclusion(config, :foreign_key, :association_foreign_key, :parent_table, :child_table)
-		
-		join_entry_name = self.entry_name < entry.entry_name ? 
-						"#{self.entry_name}_#{entry.entry_name}" : 
-						"#{entry.entry_name}_#{self.entry_name}"
-						
-		JoinFix.new join_entry_name, 
-			[config[:foreign_key], config[:parent_table]] => self.entry_name,
-			[config[:association_foreign_key], config[:child_table]] => entry.entry_name
-	end
-	
-	# Creates the required key-value pairs for a 'has_many' association between 
-	# the fixture and the input entry.  Returns a join entry if configuration :through is 
+  # Creates the required key-value pairs for a 'has_many' association between 
+	# self and the input entry.  Returns a join entry if configuration :through is 
 	# specified, otherwise returns nil.
 	#
 	# Required configurations:
-	# * [:foreign_key, :parent_table]
+	#   [:parent_table, :foreign_key]
 	#
 	# Required configurations for has_many :as 
-	# * [:as  (=association), :parent_table] 
+	#   [:parent_table, :as  (=association)] 
 	#
 	# Required configurations for  has_many :through 
-	# * [:through (=join table), :foreign_key, :association_foreign_key, :parent_table, :child_table]
+	#   [:parent_table, :child_table, :through (=join table), :foreign_key, :association_foreign_key]
 	def join_has_many(entry, config)
 		if config[:as]
 			# produces entries like:
@@ -235,18 +246,41 @@ module JoinFix
 			join_has_one(entry, config)
 		end
 	end
+  
+	# Creates the required key-value pairs for a 'has_and_belongs_to_many' association between 
+	# self and the input entry.  Returns a join entry.
+	#
+	# Required configurations:
+	#   [:parent_table, :child_table, :foreign_key, :association_foreign_key]
+	def join_has_and_belongs_to_many(entry, config)
+		# produces entries like:
+		#   join[foreign_key_ref_parent_table] = self.entry_name
+		#   join[association_foreign_key_ref_child_table] = entry.entry_name
+		# later resolved to:
+		#   join[foreign_key_id] = self.id
+		#   join[association_foreign_key_id] = entry.id
+		validate_inclusion(config, :foreign_key, :association_foreign_key, :parent_table, :child_table)
+		
+		join_entry_name = self.entry_name < entry.entry_name ? 
+						"#{self.entry_name}_#{entry.entry_name}" : 
+						"#{entry.entry_name}_#{self.entry_name}"
+						
+		JoinFix.new join_entry_name, 
+			[config[:foreign_key], config[:parent_table]] => self.entry_name,
+			[config[:association_foreign_key], config[:child_table]] => entry.entry_name
+	end
 	
 	protected
 
-	# Checks each input type is present in the config; raises an error when it is not.
-	def validate_inclusion(config, *types)
-		types.each do |type|
-			raise ArgumentError, "Missing configuration '#{type}'" unless config.has_key?(type)
+	# Checks each key is present in the config; raises an error when it is not.
+	def validate_inclusion(config, *keys) # :nodoc:
+		keys.each do |key|
+			raise ArgumentError, "Missing configuration '#{key}'" unless config.has_key?(key)
 		end
 	end
 	
 	# The generalized extraction method called by extract_if and extract_unless
-	def extract(method, keys, block)
+	def extract(method, keys, block) # :nodoc: 
 		# be sure that allowed keys is an array, to respond to include?
 		keys = [keys] unless keys.kind_of?(Array)
 		

data/rails/app/models/group.rb

@@ -1,4 +1,4 @@
-class Group < ActiveRecord::Base
-	has_many :group_users, :class_name => 'UserGroup'
-	has_many :users, :through => :group_users
+class Group < ActiveRecord::Base
+  has_many :user_groups
+	has_many :users, :through => :user_groups
 end

data/rails/db/migrate/004_create_users.rb

@@ -1,7 +1,7 @@
 class CreateUsers < ActiveRecord::Migration
   def self.up
     create_table :users do |t|
-	t.column :login, :string
+	    t.column :full_name, :string
     end
   end
 

data/rails/db/schema.rb

@@ -29,7 +29,7 @@ ActiveRecord::Schema.define(:version => 6) do
   end
 
   create_table "users", :force => true do |t|
-    t.column "login", :string
+    t.column "full_name", :string
   end
 
 end