joinfix 0.1.1 → 1.0.0

data/README

@@ -1,86 +1,158 @@
-# = 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
-#
-#
+= JoinFix 
+A reflection-based solution to the fixture join problem.  
 
+== Description
+Making fixtures for models with complex joins can be a redundant, error-prone process.  JoinFix 
+provides a solution to this problem by letting you reference and/or define child entries inline with 
+their parents. 
+
+  [users.yml]
+  john_doe:
+    full_name: John Doe
+    groups: 
+      - admin_group           # => entry reference
+      - devel_group:          # => inline definition
+          name: Developers
+      
+  [groups.yml]
+  admin_group:                # => referenced entry
+    name: Administrators
+          
+JoinFix uses reflection on ActiveRecord associations to determine how to perform joins so 
+no configuration is required.  Simply require joinfix and begin writing entries.
+
+== Info 
+
+Available at {rubyforge.org/projects/joinfix}[http://rubyforge.org/projects/joinfix]
+
+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 :user_groups
+    has_many :users, :through => :user_groups
+  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 referenced across multiple fixture files or defined  inline: 
+
+  [users.yml]
+  john_doe:
+    full_name: John Doe
+    groups: admin_group       # => reference to the 'admin_group' entry
+    
+  jane_doe:
+    full_name: Jane Doe
+    groups:                   # => you can specify an array of entries if needed
+      - admin_group
+      - worker_group:         # => inline definition of the 'worker_group' entry
+          name: Workers
+       
+  [groups.yml]
+  admin_group:                # => the referenced 'admin_group' entry
+    id: 3                     # => you can (but don't have to) specify ids 
+    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 
+produce these entries:
+
+  [users]
+  john_doe:
+    id: 1                     # => primary keys are assigned to all entries (see note)
+    full_name: John Doe
+  jane_doe:
+    id: 2
+    full_name: Jane Doe
+    
+  [groups]
+  admin_group:                
+    id: 3                     
+    name: Administrators
+  worker_group:
+    id: 1
+    name: Workers
+
+  [user_groups]
+  admin_group_john_doe  
+    id: 1
+    user_id: 1                # => references are resolved to their foreign keys
+    group_id: 3               # => explicitly set primary keys are respected  
+  admin_group_jane_doe    
+    id: 2
+    user_id: 2                
+    group_id: 3   
+  jane_doe_worker_group       # => Notice the '<' operator in action
+    id: 3
+    user_id: 2                
+    group_id: 1  
+
+Note: Primary keys are assigned to entries based on the way the entry names are hashed, ie 'john_doe' will not necessarily have id '1'.  If you need a specific id for an entry, then you must explicitly set it.
+
+If you need to add additional fields to an implied entry, simply define them in their
+fixture file.  All fields across all fixtures will be merged into one entry (JoinFix raises 
+an error in the event of a collision).
+
+  [user_groups.yml]
+  admin_group_john_doe:
+    date_added: 2007-06-12
+
+Nesting is allowed.  This will make the same entries as above:
+
+  [users.yml]
+  john_doe:
+    full_name: John Doe
+    groups:    
+      admin_group:
+        id: 3
+        name: Administrators
+        users:
+          jane_doe:
+            full_name: Jane Doe
+            groups:
+              worker_group:
+                name: Workers
+    
+In your tests, require joinfix and use the fixtures exactly as you would normally.  
+One 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(:john_doe).groups.first.name
+      assert_equal 2, User.find_by_full_name("jane_doe").groups.count
+      assert_equal 3, UserGroup.find(user_groups(:admin_group_jane_doe).id).group.id
+    end
+  end
+
+=== Command line options
+
+JoinFix provides some command line options through the ENV variables.  Setting these
+variables is easy if you're using rake[http://rake.rubyforge.org/] to run your test suite:
+
+  % rake test key=value         # => sets ENV['key'] = 'value'
+
+Available options:
+
+format_joinfix_errors:: Unless 'false', this option causes JoinFix to simplify the console output when a JoinFixError occurs.
+joinfix_dump:: Prints all entries for tables matching joinfix_dump to STDOUT upon make_join_fixtures.  Prints entries for all tables if 'true'.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+# tasks
+desc 'Default: Run tests.'
+task :default => :test
+
+desc 'Run tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = File.join('test', ENV['subset'] || '', ENV['pattern'] || '**/*_test.rb')
+  t.verbose = true
+end
+
+desc 'Generate documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'JoinFixtures'
+  rdoc.main = 'README'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README', 'MIT-LICENSE', 'TEST_README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+#
+# Gem specification
+#
+if File.exists?("./gemspecs/1.0.0.gemspec")
+
+Gem::manage_gems
+spec = Gem::SourceIndex.load_specification("./gemspecs/1.0.0.gemspec")
+Rake::GemPackageTask.new(spec) do |pkg|
+	pkg.need_tar = true
+end
+
+end

data/TEST_README

@@ -1,44 +1,45 @@
-# = 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
-#
+= 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 test user
+
+These commands will create the database and grand permissions as needed, assuming 
+you're using mysql on localhost.  Log into 'mysql', then enter:
+
+  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 integrate with 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 test user
+* migrate the table schema into the development database
+
+These commands will create the database and grand permissions as needed, assuming 
+you're using mysql on localhost.  Log into 'mysql', then enter:
+
+  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/error.rb

@@ -0,0 +1,220 @@
+# JoinFix provides help for debugging errors in your fixtures through subclasses of JoinFixError.
+class JoinFixError < RuntimeError 
+  class << self
+    def new(*args)
+      @already_created ||= {}
+      
+      error = super(*args)
+      key = error.fixtures.respond_to?(:fixture_path) ? error.fixtures.fixture_path : error.fixtures
+      @already_created[key] ||= error
+    end
+  end
+  
+  attr_reader :fixtures, :entry_name, :msg
+  attr_accessor :advice
+  
+  def initialize(fixtures, entry_name, msg=nil)
+		@fixtures = fixtures
+		@entry_name = entry_name
+    @msg = msg
+	end
+end
+
+class MissingFixtureError < JoinFixError # :nodoc:
+	attr_reader :table_name
+	def initialize(table_name)
+    @fixtures = table_name
+		@table_name = table_name
+	end
+	
+	def message
+		"No fixture loaded for <#{table_name}>\n" +
+		(advice.nil? ? '' : "#{advice}\n")
+	end
+	
+	def advice
+		%Q{
+Be sure you've specified all the tables for which your fixtures create entries.
+---
+class UserTest < Test::Unit::TestCase
+  fixtures :users, :groups, :user_groups  # => got to name them all!!!
+end}
+	end
+end
+
+class MakeEntryError < JoinFixError # :nodoc:
+	attr_reader :entry
+	attr_accessor :advice
+	
+	def initialize(fixtures, entry_name, entry, msg=nil)
+		super(fixtures, entry_name, msg)
+		@entry = entry
+	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:
+---
+john_doe:
+  full_name: John Doe
+  groups:
+    # an entry name like 'admin_group' is missing here
+    name: Administrators
+    ...
+    
+Or sometimes if you have an error in your YAML:
+---
+john_doe:
+  full_name: John Doe
+  groups:
+    - admin_group:
+        name: Administrators
+    - worker_group:
+      name: Workers # this field is not properly indented
+    ...}
+	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.}
+	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
+
+class ResolveJoinReferenceError < JoinFixError # :nodoc:
+	attr_reader :join_table_name, :join_name
+
+	def initialize(fixtures, entry_name, join_table_name, join_name, msg=nil)
+	  super(fixtures, entry_name, msg)
+		@join_table_name = join_table_name
+		@join_name = join_name
+	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
+
+require 'test/unit/ui/console/testrunner'
+module Test # :nodoc:
+  module Unit # :nodoc:
+    module UI # :nodoc:
+      module Console # :nodoc:
+      
+        # TestRunner is the Test::Unit class providing a user interface for running tests in a console. 
+        # JoinFix modifies this class to provide a nicer output when JoinFix fails.  Without these 
+        # modifications a single error causes the test output to explode into a meaningless jumble, 
+        # once for every test in a suite.  
+        #
+        # Turn off the modifications by setting ENV['format_joinfix_errors'] = 'false', for instance by using:
+        #
+        #   % rake test format_joinfix_errors=false
+        #
+        class TestRunner  
+          private
+
+          alias join_fix_original_finished finished
+          
+          def finished(elapsed_time)
+            if ENV['format_joinfix_errors'].to_s =~ /^false$/i
+              join_fix_original_finished(elapsed_time)
+              return            
+            end
+            
+            nl
+            output("Finished in #{elapsed_time} seconds.")
+            
+            joinfix_faults = {}
+            @faults.each_with_index do |fault, index|
+              if fault.kind_of?(Test::Unit::Error) && fault.exception.kind_of?(JoinFixError)
+                affected_tests = (joinfix_faults[fault.exception] ||= [])
+                affected_tests << [index, fault.test_name]
+              end
+            end
+            
+            joinfix_faults.each_pair do |exception, affected_tests|
+              output("\n**************************************\n")
+              output("JoinFix -- #{exception.class}:\n#{exception.message}\n")
+              output("Caused Errors:\n")
+              affected_tests.each do |index, test_name|
+                output("%3d) Error: %s\n" % [index + 1, test_name])
+              end
+            end
+            
+            @faults.each_with_index do |fault, index|
+              next if fault.kind_of?(Test::Unit::Error) && fault.exception.kind_of?(JoinFixError)
+              
+              nl
+              output("%3d) %s" % [index + 1, fault.long_display])
+            end
+            nl
+            output(@result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/joinfix/fixture.rb

@@ -1,7 +1,6 @@
-# Additional classes to make Fixture behave like a Hash.  Required for resolving joins. 
+# Defines additional methods 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
+# Accomodates both of the allowed internal data structures for Fixture: Hash and YAML::Omap
 class Fixture
 	def has_key?(key)
 		# should work for Hash and Omap
@@ -14,7 +13,7 @@ class Fixture
 			@fixture.each_pair(&block)
 		else
 			# for Omap
-			@fixture.map { |k, v| yield(k,v) } 
+			@fixture.map { |key, value| yield(key, value) } 
 		end
 	end