joinfix 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2006-2007, Regents of the University of Colorado.
+Developer:: Simon Chiang, Biomolecular Structure Program
+Support:: UCHSC School of Medicine Deans Academic Enrichment Fund
+
+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/README

@@ -0,0 +1,86 @@
+# = JoinFix
+# A reflection-based solution to the fixture join problem.
+#
+# == Info 
+#
+# Copyright (c) 2006-2007, Regents of the University of Colorado.
+# Developer:: Simon Chiang, Biomolecular Structure Program
+# Support:: UCHSC School of Medicine Deans Academic Enrichment Fund
+# Licence:: MIT-Style
+#
+# == Usage
+# Consider the following data model:
+#
+#   class User < ActiveRecord::Base
+#     has_many :user_groups, 
+#     has_many :groups, :through => :user_groups
+#   end
+#
+#   class Group < ActiveRecord::Base
+#     has_many :group_users, :class_name => 'UserGroup'
+#     has_many :users, :through => :group_users
+#   end
+#
+#   class UserGroup < ActiveRecord::Base
+#     belongs_to :user
+#     belongs_to :group
+#   end
+#
+# Write your fixtures using the naming scheme you lay out in your models.
+# Entries can be spread across multiple fixture files, or not.  Joins between
+# entries are written inline, either by referening the name of another entry
+# or by defining the joined entry: 
+#
+#   [users.yml]
+#   bob:
+#     login: bob
+#     groups: admin_group       # => reference to the 'admin_group' entry
+#     
+#   jane:
+#     id: 3                       # => you can specify ids if you want
+#     login: jane
+#     groups:                   # => an array of joins
+#       - admin_group
+#       - workers:
+#         name: worker bees
+#        
+#   samantha:
+#     login: sam
+#   groups:                     # => inline definition of joined entries
+#     movers:
+#       name: movers
+#     shakers:
+#       name: shakers
+#
+#   [groups.yml]
+#   admin_group:                # => references can span files
+#     name: administrators
+#
+# Join entries implied in your definition, as in a has_and_belongs_to_many association, will
+# be created and named by joining together the names of the parent and child, ordered
+# by the '<' operator.  For example, the users.yml and groups.yml fixtures will also produce:
+#
+#    admin_group_bob # => join for bob and admin_group
+#    jane_workers # => join for jane and workers
+#    ...
+#
+# In your tests, require joinfix and use the fixtures exactly as you would normally.  
+# One gotcha (which really isn't a gotcha) -- you must be sure to name all the tables 
+# for which your fixtures create entries.  In fact this is no different than normal, 
+# but it's easy to forget if you lump joins into one file.
+#
+#   require 'joinfix'
+#
+#   class UserTest < Test::Unit::TestCase
+#     fixtures :users, :groups, :user_groups  # => got to name them all!
+#
+#     def test_joinfix
+#       assert_equal "administrators", users(:bob).groups.first.name
+#       assert_equal 2, User.find_by_login("jane").groups.count
+#       assert_equal 3, UserGroup.find(user_groups(:jane_workers).id).user.id
+#       assert_equal users(:samantha), User.find_by_login("sam").groups.find_by_name("movers").users.first
+#     end
+#   end
+#
+#
+

data/TEST_README

@@ -0,0 +1,44 @@
+# = JoinFix Tests
+# JoinFix does not have an active test suite that can be run when installed via RubyGems,
+# because as you may expect, running the tests for joinfix requires that ActiveRecord can 
+# connect to a test database.  Additionally, the tests depend on the 'gemdev' gem.
+#
+# If you want to run the tests, you need to do the following:
+# * install gemdev ('gem install gemdev')
+# * create the database and grant permissions to a test user
+# * modify config.yml to reflect the database and user
+#  
+# Execute these commands when logged into 'mysql' (assuming you're using mysql on localhost)
+#
+#   create database joinfix;
+#   grant all on joinfix.* to 'ruby'@'localhost' identified by 'rubypass'
+#
+# Now you can run the test from the command line using:
+# 
+#   % rake test
+#
+# = Rails Tests
+# JoinFix is intended to be used in Ruby on Rails.  I've set up a rails project for 
+# testing, complete with models, migrations, fixtures, and the appropriate tests.
+# 
+# The rails tests require a '_development' and '_test' database to connect to.
+#
+# To setup the databases:
+# * create the databases and grant permissions to a test user
+# * modify rails/config/database.yml to reflect the databases and user
+# * migrate the table schema into the development database
+# 
+# Execute these commands when logged into 'mysql' (assuming you're using mysql on localhost)
+#
+#   create database joinfix_development;
+#   grant all on joinfix_development.* to 'ruby'@'localhost' identified by 'rubypass';
+#
+#   create database joinfix_test;
+#   grant all on joinfix_test.* to 'ruby'@'localhost' identified by 'rubypass';
+#
+# Subsequently you need to migrate the database specification into these tables
+# and run the tests.  From the command line, in the rails directory:
+#
+#   % rake db:migrate
+#   % rake test
+#

data/lib/joinfix/fixture.rb

@@ -0,0 +1,29 @@
+# Additional classes to make Fixture behave like a Hash.  Required for resolving joins. 
+#
+# Just off of trivial because the internal data structure for Fixture can be a Hash or
+# a YAML::Omap
+class Fixture
+	def has_key?(key)
+		# should work for Hash and Omap
+		@fixture.keys.include?(key)
+	end
+	
+	def each_pair(&block)
+		if @fixture.respond_to?(:each_pair) 
+			# for Hash
+			@fixture.each_pair(&block)
+		else
+			# for Omap
+			@fixture.map { |k, v| yield(k,v) } 
+		end
+	end
+	
+	def delete_if(&block)
+		# should work for Hash and Omap
+		@fixture.delete_if(&block)
+	end
+	
+	def []=(key, value)
+		@fixture[key] = value
+	end
+end

data/lib/joinfix/fixtures.rb

@@ -0,0 +1,271 @@
+class Fixtures
+	attr_reader :join_configs, :templates
+	
+	alias join_fix_original_insert_fixtures insert_fixtures
+	def insert_fixtures
+		Fixtures.template_all_loaded_fixtures if templates.nil?
+		join_fix_original_insert_fixtures
+	end
+	
+	@@entry_stack = []
+	
+	def template_fixtures
+		return unless templates.nil?
+		
+		begin
+			configure
+		rescue
+			raise "\nError configuring fixtures for: #{@class_name}\n#{$!.message}"
+		end
+		
+		extract_templates
+		
+		begin 
+			templates.each_pair do |entry_name, entry|
+				make_entry(entry_name, entry, true)
+			end
+		rescue
+			entry_str = "Entry:\n" + @@entry_stack.last.to_yaml
+			raise "Error making entry for: '#{@class_name}'\n#{entry_str}#{$!.message}"
+		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
+	
+	def each_pair(&block)
+		map { |entry_name, fixture| yield(entry_name, fixture) } 
+	end
+	
+	def config
+		configure unless @config
+		@config
+	end
+	
+	protected
+	
+	def configure
+		klass = @class_name.constantize
+		file_base = @class_name.underscore.singularize
+			
+		# default attributes, constructed from reflecting on the active record table
+		attributes = {}
+		klass.columns.each do |column| 
+			next if JoinFix.preserves?(column.name)
+			attributes[column.name] = column.default 
+		end
+		
+		# default associations, constructed from reflecting on the active record class
+		associations = {}
+		klass.reflect_on_all_associations.each do |association|
+			begin
+				config = {:macro => association.macro}.merge(association.options)
+					
+				# get the child table name either by reflecting on the association class
+				config[:class_name] ||= association.class_name
+				config[:table_name] = config[:class_name].constantize.table_name unless config[:polymorphic]
+
+				associations[association.name] = config
+			rescue
+				# known failure retrieving class name for has_many :through if the join model doesn't
+				# have a 'belongs_to' pointing to the source model
+				raise "Could not reflect on association: #{association.name}\n" +
+					"Check that your join models are properly configured.\n" + 
+					$!.message
+			end
+		end
+
+		# merge the defaults with the file configurations 
+		@config = {
+			'class_name' => klass.class_name,
+			'table_name' => klass.table_name,
+			'attributes' => attributes, 
+			'associations' => associations
+			# FUTURE! bring back if you start running methods
+			#'modules' => [JoinFix, "#{@class_name}Template"]
+		}.with_indifferent_access
+			
+		@join_configs = {}.with_indifferent_access
+		parent_config = @config
+		associations.each_pair do |association, child_config|
+			# define shared parameters
+			join_config = {
+				:parent_table => parent_config[:table_name],
+				:child_table => child_config[:table_name],
+				:macro => child_config[:macro]
+			}.with_indifferent_access
+				
+			case join_config[:macro].to_sym
+			when :belongs_to 
+				if child_config[:polymorphic]
+					join_config[:polymorphic] = true
+					join_config[:associable] = association.to_s
+					join_config[:foreign_key] =  child_config[:foreign_key] || "#{association}_id"
+					join_config.delete(:child_table) # not necessary, but reflects the fact that the polymorphic entry must specify this directly
+				else
+					join_config[:foreign_key] = child_config[:foreign_key] || "#{join_config[:child_table].singularize}_id"
+				end
+			when :has_one
+				join_config[:foreign_key] = child_config[:foreign_key] || "#{join_config[:parent_table].singularize}_id"
+			when :has_many
+				if child_config[:as]
+					join_config[:as] = child_config[:as]
+					join_config[:foreign_key] = child_config[:foreign_key] || "#{child_config[:as]}_id"
+					join_config[:parent_class] = parent_config[:class_name]
+				elsif child_config[:through]
+					join_config[:through] = child_config[:through]
+					join_config[:join_table] = associations[child_config[:through]][:table_name]
+					join_config[:foreign_key] = "#{join_config[:parent_table].singularize}_id"
+					join_config[:association_foreign_key] = "#{join_config[:child_table].singularize}_id"
+				else
+					join_config[:foreign_key] = child_config[:foreign_key] || "#{join_config[:parent_table].singularize}_id"
+				end
+			when :has_and_belongs_to_many
+				join_config[:join_table] = child_config[:join_table] || (join_config[:parent_table] < join_config[:child_table] ? "#{join_config[:parent_table]}_#{join_config[:child_table]}" : "#{join_config[:child_table]}_#{join_config[:parent_table]}") # echos the way join tables are guessed by ActiveRecord
+				join_config[:foreign_key] = child_config[:foreign_key] || "#{join_config[:parent_table].singularize}_id"
+				join_config[:association_foreign_key] = child_config[:association_foreign_key] ||  "#{join_config[:child_table].singularize}_id"
+			else
+				raise ArgumentError, "Unknown join type '#{join_config[:macro]}'."
+			end
+			
+			join_config[:attributes] = Fixtures.fixture(join_config[:join_table]).config[:attributes]  if join_config.has_key?(:join_table)
+			@join_configs[association] = join_config
+		end
+	end
+	
+	def extract_templates
+		# fixture is a template if it contains an association
+		@templates = {}
+		associations = config[:associations].keys
+		each do |entry_name, fixture|
+			#next if key.to_s !~ /[=|!]$/  # FUTURE! bring back if you start running methods
+			entry = fixture.to_hash
+			next if (entry.keys & associations).empty?
+			@templates[entry_name] = entry
+		end
+		delete_if do |entry_name, fixture|
+			@templates.has_key?(entry_name)
+		end
+	end
+	
+	def make_entry(entry_name, entry, add_entry_on_complete)
+		@@entry_stack << entry.dup
+		
+		attributes = config[:attributes]
+		#modules = config[:modules] # FUTURE! bring back if you start running methods
+	
+		entry = attributes.merge(entry)
+		entry.extend JoinFix	
+		entry.entry_name = entry_name
+		
+		# FUTURE! bring back if you start running methods
+		#modules.each do |module_name| 
+		#	mod = get_module(module_name, module_options)
+		#	template.extend(mod) if mod
+		#end
+	
+		# 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.
+		associated_entries = entry.extract_unless(attributes.keys) do |key, value| 
+			JoinFix.preserves?(key) || 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
+		associated_entries.merge( entry.extract_if { |key, value| value.kind_of?(Array) } )
+		associated_entries.each_pair do |association, association_templates| 
+			# ensure that association_templates is an array of template
+			association_templates = [association_templates] unless association_templates.kind_of?(Array)
+		
+			# translate the association configuration into a join configuration
+			join_config = join_configs[association]
+			unless join_config
+				raise ArgumentError, "Unknown association '#{association}' for '#{table_name}'." 
+			end
+				
+			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.
+			if join_config[:polymorphic] == true
+				join_config = join_config.dup
+				
+				associable_type = "#{join_config[:associable]}_type"
+				unless entry.has_key?(associable_type)
+					raise ArgumentError, "Polymorphic type '#{associable_type}' missing in entry '#{entry_name}' for '#{table_name}'." 
+				end
+				
+				associable_class = entry[associable_type]
+				join_config[:child_class] = associable_class
+				join_config[:child_table] = associable_class.constantize.table_name
+			end
+			
+			# raise an error if the macro doesn't allow for multiple joins, but multiple associated entries are specified
+			unless association_templates.length == 1 || JoinFix.macro_allows_multiple(macro)
+				raise ArgumentError, "Multiple associated entries specified for the single-association macro '#{macro}' in table '#{table_name}'."
+			end
+					
+			association_templates.each do |template|
+				# template is a reference to another entry
+				template = {template => JoinFix.new(template)} if template.kind_of?(String)
+				
+				# template is a fixture
+				template.each_pair do |child_name, child|
+					# generate the child entry
+					child_fixture = Fixtures.fixture(join_config[:child_table])
+					child = child_fixture.make_entry(child_name, child, false) unless child.kind_of?(JoinFix)
+							
+					# 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.
+					child_fixture.add_entry(child_name, child) 
+					Fixtures.fixture(join_table).make_entry(join_name(entry_name, child_name), join, true) if join
+				end
+			end
+		end	
+
+		# add the entry if flagged and return the entry
+		add_entry(entry_name, entry) if add_entry_on_complete
+		@@entry_stack.pop
+		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
+		attributes = config[:attributes]
+		entry.delete_if do |attribute, value|
+			default = attributes[attribute]
+			value == default
+		end
+		
+		# create a new fixture if one by the entry_name doesn't exist
+		existing = self[entry_name] ||= Fixture.new({}, config[:class_name])
+		
+		# merge new data, checking for data collissions
+		entry.each_pair do |attribute, value|
+			if existing.has_key?(attribute) && existing[attribute] != value
+				raise ArgumentError, 
+					"Data collision: #{@table_name}(:#{entry_name}).#{attribute}\n" + 
+					"<#{existing[attribute]}> is not equal to\n<#{value}>"
+			end
+			existing[attribute] = value
+		end
+	end
+	
+	def join_name(entry_name, child_name)
+		entry_name < child_name ? "#{entry_name}_#{child_name}" : "#{child_name}_#{entry_name}"
+	end
+end

data/lib/joinfix/fixtures_class.rb

@@ -0,0 +1,102 @@
+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
+			all_loaded_fixtures.each_pair do |table_name, fixtures|
+				fixtures.template_fixtures
+			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.
+			all_loaded_fixtures.values.each {|fixtures| index_fixtures(fixtures) }
+			all_loaded_fixtures.values.each {|fixtures| resolve_references(fixtures)}
+		end
+		
+		# Retreives the fixture by the given table name.  Raises an error if the fixture has
+		# not yet been loaded.
+		def fixture(table_name)
+			fixture = all_loaded_fixtures[table_name.to_s]
+			raise ArgumentError, "No fixture loaded for: #{table_name}" unless fixture
+			fixture
+		end
+		   
+		protected
+
+		def index_fixtures(fixtures)
+			# first find entries with an id and record the ids 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
+			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
+				while true
+					index += 1
+					break unless skip_indicies.include?(index)
+				end
+		
+				fixture["id"] = index
+			end
+		end
+		
+		def resolve_references(fixtures)
+			fixtures.each_pair do |name, fixture|
+				# search the fixture for join references
+				fixture.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
+		
+					# next if the foreign key is already defined
+					next if fixture.has_key?(foreign_key)
+							
+					begin 
+						# 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 ArgumentError, "The join table '#{join_table_name}' has not been loaded." 
+						end
+								
+						join_fixtures = Fixtures.all_loaded_fixtures[join_table_name]
+								
+						# raise an error if the join entry isn't in the join table; the reference cannot be resolved
+						unless join_fixtures.has_key?(join_name)
+							raise ArgumentError, "The join entry '#{join_name}' doesn't exist in '#{join_table_name}'." 
+						end
+			
+						join_entry = join_fixtures[join_name]
+								
+						# raise an exception if a join_id was not found
+						unless join_entry.has_key?("id")
+							raise ArgumentError, "No id present in join entry '#{join_name}'."
+						end
+					rescue
+						raise ArgumentError, "Cannot resolve reference '#{join_reference} => #{join_name}' in '#{@table_name}.#{name}'. #{$!}"
+					end
+							
+					# set the join id
+					fixture[foreign_key] = join_entry["id"]
+				end
+						
+				# delete the join references
+				fixture.delete_if {|key,value| key.kind_of?(Array) }
+			end
+		end
+	end
+end