joinfix 0.1.1 → 1.0.0

data/lib/joinfix/fixtures.rb

@@ -1,27 +1,67 @@
+# Fixtures objects are essentially nested hashes:
+#
+#   # A Fixtures is a hash of entry name keys and Fixture values
+#   entry_name:
+#     # A Fixture is a hash of entry fields and values
+#     field: value
+#
+# Fixtures also tracks data required for loading entries into the database, 
+# such as table_name and the connection to use.  See 'active_record/fixtures.rb' 
+# for more details.
+#
+# JoinFix extends Fixtures to track additional information like the ActiveRecord 
+# class modeling the entry data.  Using reflection, Fixtures can figure out which fields 
+# in an entry correspond to an association.  Entries with association fields are  
+# extracted and turned into join entries.  Consider and ActiveRecord class User, with 
+# 'name' as an attribute and a 'groups' association...
+#   
+#  [users.yml]
+#   # This entry will not be extracted as a template because it defines no 'groups'
+#   john:
+#     name: John                     
+#
+#   # This entry will be extracted because it defines the 'groups' association
+#   jane:
+#     name: Jane
+#     groups:                   
+#       - admin_group
+#       - workers
+#
+# If you loaded users.yml into a Fixtures...
+#   users = Fixtures.new( ...arguments to load users.yml...)
+#   users.to_hash     # => {'john' => ..., 'jane' => ...}
+#   users.templates   # => nil
+#
+#   users.extract_templates
+#   users.to_hash     # => {'john' => ...}
+#   users.templates   # => {'jane' => ...}
+#
+# The entry templates are extended with JoinFix and used to create the join entries.
 class Fixtures
-	attr_reader :klass, :attributes, :templates, :fixture_path
+	attr_reader :klass, :association_names, :templates, :fixture_path
 	
 	alias join_fix_original_initialize initialize
-	def initialize(*args)
+	def initialize(*args) # :nodoc:
 		join_fix_original_initialize(*args)
 		@klass = Object.const_get(@class_name)
-		
-		# default attributes, constructed from reflecting on the active record table
-		@attributes = {}
-		@klass.columns.each do |column| 
-			@attributes[column.name] = column.default 
-		end
-		
+    @association_names = klass.reflect_on_all_associations.collect {|assoc| assoc.name.to_s}
 		@join_configs = {}
 	end
 
 	alias join_fix_original_insert_fixtures insert_fixtures
+  
+  # Extends the default method to provide a hook for making join fixtures.  
+  # Now insert_fixtures calls Fixtures.make_join_fixtures before calling
+  # the original insert_fixtures method.
 	def insert_fixtures
-		Fixtures.template_all_loaded_fixtures if templates.nil?
+		Fixtures.make_join_fixtures if templates.nil?
 		join_fix_original_insert_fixtures
 	end
 
-	def template_fixtures
+  # Extracts the child entry templates then makes the entries specified 
+  # by each template.  Does not execute if templates have already been
+  # extracted.
+	def make_child_entries
 		return unless templates.nil?
 		
 		extract_templates
@@ -30,83 +70,88 @@ class Fixtures
 		end
 	end
 	
-	def offset
-		0
-		# FUTURE!: is this even needed?  I don't think so given that all rows are
-		# deleted by delete_existing_fixtures... not sure.
-		# @connection. QUERY FOR NEXT ID
-	end
-	
+  # Returns the join configuration (as per JoinFix.configure) for the given association.  
 	def join_config(assoc_name)
 		@join_configs[assoc_name] ||= JoinFix.send("configure", klass, assoc_name)
 	end
 	
-	def each_pair(&block)
+  # Iterates through each entry
+	def each_pair(&block) 
 		map { |entry_name, fixture| yield(entry_name, fixture) } 
 	end
 	
+  # Returns all entries as a hash of {entry_name => entry} pairs
 	def to_hash
 		hash = {}
-		each_pair do |name, fixture|
-		     hash[name] = fixture.to_hash
+		each_pair do |entry_name, entry|
+		     hash[entry_name] = entry.to_hash
 		end
 		hash
 	end
+  
+  # The initial offset for indexing (ie 0 so that indexing starts at 1).  
+  # This method is provided as a hook for overrides if necessary.
+  def primary_key_offset
+    0
+  end
 	
 	protected
 	
-	def extract_templates
-		# fixture is a template if it contains an association
+  # Extracts template entries.  Entries are Fixture objects, essentially a hash of {attribute => value} pairs.   
+  # An entry is considered a template if it contains an association attribute.  If this is true, then the entry 
+  # is removed from self and stored as a template.  
+	def extract_templates # :nodoc:
 		@templates = {}
-		assoc_names = klass.reflect_on_all_associations.collect {|assoc| assoc.name.to_s}
-		each do |entry_name, fixture|
+
+    # iterate over all entries looking for templates
+    each do |entry_name, fixture|
 			entry = fixture.to_hash
-			next if (entry.keys & assoc_names).empty?
+      
+      # fixture is a template if it contains an association
+			next if (entry.keys & association_names).empty?
 			@templates[entry_name] = entry
 		end
+    
+    # remove template entries
 		delete_if do |entry_name, fixture|
 			@templates.has_key?(entry_name)
 		end
 	end
 
-	def make_entry(entry_name, entry_template, add_entry_on_complete)
-		raise NoEntryNameError.new(self, entry_name, entry_template) unless entry_template.kind_of?(Hash)
+  # Makes the specified entry and adds the entry to self if add_entry_on_complete is true.  
+	def make_entry(entry_name, entry, add_entry_on_complete) # :nodoc:
+    
+    # If the entry is not a hash, then no entry name was specified in the fixture file
+    unless entry.kind_of?(Hash)
+		  raise NoEntryNameError.new(self, entry_name, entry) 
+    end
 		
-		entry = attributes.merge(entry_template)
 		entry.extend JoinFix	
 		entry.entry_name = entry_name
 		
-		# extract templates for entries that will be joined to the current entry
-		#   Associated entries are indicated by any key undeclared in attributes, that also does not
-		#   match one of the reseved key patterns... ie 'id' or keys ending in '_id'.  Additionally includes
-		#   join references, which will all be arrays.
-		assoc_entries = entry.extract_unless(attributes.keys) do |key, value| 
-			key == "id" || key.kind_of?(Array)
-		end
-			
-		# also extract templates for entries that have an array value.  These entries indicate a set of
-		# associated entries that should each be joined to the current entry
-		assoc_entries.merge( entry.extract_if { |key, value| value.kind_of?(Array) } )
-		assoc_entries.each_pair do |assoc_name, assoc_array| 
-			# ensure that assoc_array is an array of template
-			assoc_array = [assoc_array] unless assoc_array.kind_of?(Array)
+		# extract and construct associated entries
+    associated_entries = entry.extract_if(association_names)
+		associated_entries.each_pair do |assoc_name, associations| 
+			# ensure that associations is an array
+			associations = [associations] unless associations.kind_of?(Array)
 		
-			# translate the association configuration into a join configuration
+			# get the join configuration for the association
 			join_config = join_config(assoc_name)	
 			join_table = join_config[:join_table]
 			macro = join_config[:macro]
 			
-			# pull the polymorphic association class out of the entry -- polymorphic joins cannot determine
-			# beforehand what table they will join to.  The associable_type MUST be specified in the fixture.
+			# pull the polymorphic join information out of the entry -- polymorphic joins cannot determine
+			# beforehand what table they will join to; the associable_type MUST be specified in the entry.
 			if join_config[:polymorphic] == true
-				join_config = join_config.dup
+        # be sure to preserve the base configuration...
+				join_config = join_config.dup 
 				
 				associable_type = join_config[:associable_type]
 				associable_class = entry[associable_type]
 				
 				unless associable_class
-					raise MissingPolymorphicTypeError.new(self, entry_name, entry_template,
-						"No <#{associable_type}> was specified.")
+					raise MissingPolymorphicTypeError.new(self, entry_name, entry.merge(associated_entries), 
+            "No <#{associable_type}> was specified.")
 				end
 					
 				join_config[:child_class] = associable_class
@@ -114,16 +159,16 @@ class Fixtures
 			end
 			
 			# raise an error if the macro doesn't allow for multiple joins, but multiple associated entries are specified
-			unless assoc_array.length == 1 || JoinFix.macro_allows_multiple(macro)
-				raise MultipleChildrenError.new(self, entry_name, entry_template,
+			unless associations.length == 1 || JoinFix.macro_allows_multiple(macro)
+				raise MultipleChildrenError.new(self, entry_name, entry.merge(associated_entries),
 					"Multiple joined entries specified for the single-join macro '#{macro}'.")
 			end
 					
-			assoc_array.each do |template|
-				# template is a reference to another entry
+			associations.each do |template|
+				# String templates are references to another entry.  Make a dummy template with a dummy JoinFix.
 				template = {template => JoinFix.new(template)} if template.kind_of?(String)
 				
-				# template is a fixture
+				# Make the entries specified in the template
 				template.each_pair do |child_name, child|
 					# generate the child entry
 					child_fixture = Fixtures.fixture(join_config[:child_table])
@@ -131,12 +176,10 @@ class Fixtures
 							
 					# generate the join entry
 					join = entry.send("join_#{macro}", child, join_config)
-						
-					# add entries
-					#   Note: join is sent through the make_entry machinery before adding... this ensures that the 
-					#   join entry will be processed according to the wizard modules specified for the join table.
+          Fixtures.fixture(join_table).make_entry(join.entry_name, join, true) if join
+          
+					# add the child entry
 					child_fixture.add_entry(child_name, child) 
-					Fixtures.fixture(join_table).make_entry(join.entry_name, join, true) if join
 				end
 			end
 		end	
@@ -145,17 +188,11 @@ class Fixtures
 		add_entry(entry_name, entry) if add_entry_on_complete
 		entry
 	end
-	
-	def add_entry(entry_name, entry)
-		# FUTURE! bring back if you start running methods
-		#return unless entry.addable?  
-		
-		# remove any attributes that are equal to their default
-		entry.delete_if do |attribute, value|
-			default = attributes[attribute]
-			value == default
-		end
-		
+  
+  # Adds the specified entry to self, or merges entry attributes into the
+  # existing entry.  Raises an error in the case of an entry attribute collision 
+  # (ie an existing attribute does not equal the new attribute).
+	def add_entry(entry_name, entry) # :nodoc:
 		# create a new fixture if one by the entry_name doesn't exist
 		existing = self[entry_name] ||= Fixture.new({}, klass.class_name)
 		
@@ -169,78 +206,3 @@ class Fixtures
 		end
 	end
 end
-
-class MakeEntryError < RuntimeError # :nodoc:
-	attr_reader :fixtures, :entry_name, :entry, :msg
-	attr_accessor :advice
-	
-	def initialize(fixtures, entry_name, entry, msg=nil)
-		@fixtures = fixtures
-		@entry_name = entry_name
-		@entry = entry
-		@msg =msg
-	end
-				
-	def message
-		"Error making <#{fixtures.klass.table_name}(:#{entry_name})> in <#{fixtures.fixture_path}>.\n" + 
-		{entry_name => entry}.to_yaml +
-		(msg.nil? ? '' : "\n#{msg}\n") +
-		(advice.nil? ? '' : "#{advice}\n")
-	end
-end
-
-class EntryCollisionError < MakeEntryError # :nodoc:
-end
-
-class NoEntryNameError < MakeEntryError # :nodoc:
-	def advice
-		%Q{
-This error occurs when an entry is not named as in:
----
-dog:
-  title: Dog
-  author:
-    # <an entry name like 'ferlinghetti' is missing here>
-    full_name: Lawrence Ferlinghetti
-    ...}
-	end
-end
-
-class MultipleChildrenError < MakeEntryError # :nodoc:
-	def advice
-		%Q{
-Single entry joins should specify a single entry, not an array of entries.
-Use a different association if you need multiple joined entries.
----
-poem:
-  title: Slave's Dream
-  author: 
-    longfellow:
-      full_name: Henry Wadsworth Longfellow}
-	end
-end
-
-class MissingPolymorphicTypeError < MakeEntryError # :nodoc:
-	def advice
-		%Q{
-When specifying a belongs_to :polymorphic join, the type
-of the joined entry must be specified because it cannot be
-inferred from association itself.  Use something like:
---
-book_I_read:
-  opinion: Great!
-  readable_type: Book
-  readable:
-    the_jungle_books:
-      author: Rudyard Kipling
-      title: The Jungle Books
-
-poem_I_read:
-  opinion: Essential!
-  readable_type: Poem
-  readable:
-    sea_fever:
-      poet: John Masefield 
-      title: Sea-Fever}
-	end
-end

data/lib/joinfix/fixtures_class.rb

@@ -1,26 +1,45 @@
 class Fixtures 
-	# Class methods to tie fixture joining into the standard process for generating fixtures.
 	class << self
 		
-		# Called by individual Fixtures instances just before they insert fixtures.
-		# This allows templating to occur at the correct time (ie after all fixtures 
-		# have been loaded and configured) -- resolution of references naturally requires
-		# that all join tables are available.
-		def template_all_loaded_fixtures
+		# Makes join fixtures for all loaded fixtures.   Called just prior to inserting
+    # fixtures, after all fixtures have been loaded.
+    #
+    # After make_join_fixtures completes, entries for tables matching ENV['joinfix_dump'] 
+    # are printed to STDOUT. You can print entries for each loaded fixture by setting
+    # ENV['joinfix_dump'] = 'true'.  By default, no entries are printed.
+    #
+    # Note: printing does not affect the creation or loading of fixtures.
+		def make_join_fixtures
 			all_loaded_fixtures.each_pair do |table_name, fixtures|
-				fixtures.template_fixtures
+				fixtures.make_child_entries
 			end
+      
 			# note indexing and reference resolution must execute after all 
 			# fixtures have been templated because you never know which fixture(s) 
 			# will recieve new entries.  Additionally, indexing and resolution must
-			# run separately, because reference resolution requires the target ids 
-			# to be set.
+			# run separately, because reference resolution requires the primary key
+      # be set for the referenced entry.
 			all_loaded_fixtures.values.each {|fixtures| index_fixtures(fixtures) }
 			all_loaded_fixtures.values.each {|fixtures| resolve_references(fixtures)}
+      
+      # Print entries to STDOUT for review, if applicable
+      joinfix_dump = ENV['joinfix_dump']
+      if joinfix_dump
+        print_all = (joinfix_dump.to_s =~ /^true$/i)
+        regexp = Regexp.new(joinfix_dump.to_s)
+        
+        all_loaded_fixtures.values.each  do |fixtures|
+          table_name = fixtures.klass.table_name
+          next unless print_all || table_name =~ regexp
+          
+          puts "------- #{fixtures.klass.table_name} --------"
+          puts fixtures.to_hash.to_yaml.gsub(/^---/, '') + "\n"
+        end
+      end
 		end
 		
-		# Retreives the fixture by the given table name.  Raises an error if the fixture has
-		# not yet been loaded.
+		# Retreives the Fixtures for the given table name.  Raises an error if this Fixtures 
+		# has not yet been loaded.
 		def fixture(table_name)
 			fixture = all_loaded_fixtures[table_name.to_s]
 			raise MissingFixtureError.new(table_name) unless fixture
@@ -29,26 +48,25 @@ class Fixtures
 		   
 		protected
 
-		# Sets the primary key in each of the input fixtures, beginning one-past fixtures.offset
-		# (generally this is 1).  If a fixture already has an id assigned, it will be skipped.
-		def index_fixtures(fixtures)
+		# Sets the primary key for entries in each of the input Fixtures, beginning  
+    # one past the Fixtures primary key offset (ie 1).  Skips entries that already 
+    # have a primary key assigned.
+		def index_fixtures(fixtures) # :nodoc:
 			id = fixtures.klass.primary_key
 			
-			# first find entries with an id and record the ids so that they will be skipped
+			# find entries with the primary key and record these so that they will be skipped
 			skip_indicies = []
 			fixtures.each_pair do |name, fixture|
 				skip_indicies << fixture[id].to_i if fixture.has_key?(id)
 			end
 					
-			# next find and index entries that do not have an id defined
-			index = fixtures.offset
+			# find and index entries that do not have a primary key defined
+			index = fixtures.primary_key_offset
 			fixtures.each_pair do |name, fixture|
-				# skip entries that already have an id defined
 				next if fixture.has_key?(id)
 	
-				# find the next available index
-				# note this must happen before the id assignment,
-				# in case index 1 is marked for skipping
+				# find the next available index.  Note this must happen before 
+        # the assignment, in case '1' is marked for skipping
 				while true
 					index += 1
 					break unless skip_indicies.include?(index)
@@ -58,24 +76,17 @@ class Fixtures
 			end
 		end
 		
-		# Resolves each join reference in the input fixtures
-		def resolve_references(fixtures)
-			fixtures.each_pair do |entry_name, fixture|
-				# search the fixture for join references
-				fixture.each_pair do |join_ref, join_name|
+		# Resolves join references in the input Fixtures.
+		def resolve_references(fixtures) # :nodoc:
+			fixtures.each_pair do |entry_name, entry|
+				entry.each_pair do |join_ref, join_name|
 					# next if the key isn't a join reference
 					next unless join_ref.kind_of?(Array)
 					
 					foreign_key = join_ref.first
 					join_table_name = join_ref.last
-				
-					# raise an error if the join table isn't loaded; the reference cannot be resolved
-					unless Fixtures.all_loaded_fixtures.has_key?(join_table_name)
-						raise ResolveJoinReferenceError.new(fixtures, entry_name, join_table_name, join_name,
-							"The join table '#{join_table_name}' has not been loaded.")
-					end
-								
-					join_fixtures = Fixtures.all_loaded_fixtures[join_table_name]
+						
+					join_fixtures = Fixtures.fixture(join_table_name)
 					id = join_fixtures.klass.primary_key
 						
 					# raise an error if the join entry isn't in the join table; the reference cannot be resolved
@@ -86,82 +97,25 @@ class Fixtures
 			
 					join_entry = join_fixtures[join_name]
 								
-					# raise an exception if a join_id was not found
+					# raise an exception if the primary key for the join entry is not set 
 					unless join_entry.has_key?(id)
 						raise ResolveJoinReferenceError.new(fixtures, entry_name, join_table_name, join_name,
 							"No #{id} present in join entry '#{join_name}'.")
 					end
 	
 					# raise an exception if the foreign key is already set
-					unless fixture[foreign_key].nil?
+					unless entry[foreign_key].nil?
 						raise ForeignKeySetError.new(fixtures, entry_name, join_table_name, join_name,
 							"Foreign key <#{foreign_key}> is already set!")
 					end
 						
-					# set the join id
-					fixture[foreign_key] = join_entry[id]
+					# set the foreign key to the joined entry primary key
+					entry[foreign_key] = join_entry[id]
 				end
 						
 				# delete the join references
-				fixture.delete_if {|key,value| key.kind_of?(Array) }
+				entry.delete_if {|key,value| key.kind_of?(Array) }
 			end
 		end
 	end
-end
-
-class MissingFixtureError < RuntimeError # :nodoc:
-	attr_reader :table_name
-	def initialize(table_name)
-		@table_name = table_name
-	end
-	
-	def message
-		"No fixture loaded for <#{table_name}>\n" +
-		(advice.nil? ? '' : "#{advice}\n")
-	end
-	
-	def advice
-		%Q{}
-	end
-end
-
-class ResolveJoinReferenceError < RuntimeError # :nodoc:
-	attr_reader :fixtures, :entry_name, :join_table_name, :join_name, :msg
-	attr_accessor :advice
-	
-	def initialize(fixtures, entry_name, join_table_name, join_name, msg=nil)
-		@fixtures = fixtures
-		@entry_name = entry_name
-		@join_table_name = join_table_name
-		@join_name = join_name
-		@msg =msg
-	end
-				
-	def message
-		"Cannot resolve reference to <#{join_table_name}(:#{join_name})> " + 
-		"for <#{fixtures.klass.table_name}(:#{entry_name})> " + 
-		"in <#{fixtures.fixture_path}>.\n" +
-		(msg.nil? ? '' : "\n#{msg}\n") +
-		(advice.nil? ? '' : "#{advice}\n")
-	end
-end
-
-class ForeignKeySetError < ResolveJoinReferenceError # :nodoc:
-	def advice
-		%Q{
-This error occurs when you specifiy the foreign key, as well as a join entry.  
----
-poem:
-  title: Poetry of Departures
-  author_id: 8
-  author: larkin
-
-If you need to specify the foreign key, do so within the entry.
----
-poem:
-  title: Poetry of Departures
-  author: 
-    larkin:
-      id: 8}
-	end
-end
+end