pluginaweek-enumerate_by 0.4.2

data/CHANGELOG.rdoc

@@ -0,0 +1,111 @@
+== master
+
+* Improve compatibility with the stable branch of Rails 2.3 [Michael Schuerig]
+
+== 0.4.2 / 2009-05-03
+
+* Fix bootstrapping without ids not working on update for certain database adapters
+
+== 0.4.1 / 2009-05-01
+
+* Improve #fast_bootstrap speed by 50% by using the connection directly
+
+== 0.4.0 / 2009-04-30
+
+* Allow cache to be cleared on a per-enumeration basis
+* Add #fast_bootstrap for bootstrapping large numbers of records
+* Don't require an id during bootstrap
+* Allow bootstrapping to be easily added to non-enumerations
+* Cache results for #exists? / #calculate
+* Add the ability to skip the internal cache via Model#uncached
+* Add Model#find_all_by_enumerator
+* Don't internally rely on Model#[] being available since it may conflict with other plugins
+* Enable caching by default for all enumerations
+* Allow caching to be turned off on an application-wide basis
+* Allow cache store to be configurable
+* Automatically trigger in-memory caching of the enumeration's table when bootstrapping
+* Add #bootstrap for automatically synchronizing the records in an enumeration's table
+* Improve serialization performance
+* No longer use tableless models
+* Re-brand under the enumerate_by name
+
+== 0.3.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+
+== 0.2.6 / 2008-11-29
+
+* Fix enumeration collections not being able to convert to JSON
+* Add support for multiple enumeration values in finder conditions, e.g. Car.find_all_by_color(%w(red blue))
+
+== 0.2.5 / 2008-10-26
+
+* Fix non-ActiveRecord associations (e.g. ActiveResource) failing
+* Fix reloading of associations not working
+* Raise an exception if equality is performed with an invalid enumeration identifier
+* Change how the base module is included to prevent namespacing conflicts
+
+== 0.2.4 / 2008-08-31
+
+* Add support for serialization in JSON/XML
+
+== 0.2.3 / 2008-06-29
+
+* Fix named scope for enumerations that belong_to other enumerations
+
+== 0.2.2 / 2008-06-23
+
+* Remove log files from gems
+
+== 0.2.1 / 2008-06-22
+
+* Improve documentation
+
+== 0.2.0 / 2008-06-22
+
+* Improve performance by disabling unnecessary ActiveRecord hooks including callbacks, dirty attributes, timestamps, and transactions (important for enumerations with large sets of values)
+* Don't let #create silently fail
+* Remove ability to reset the cache
+* Improve performance by adding pre-indexing of enumeration attributes (important for enumerations with large sets of values)
+* Remove support for array comparison
+* Remove support for multiple enumeration attributes
+
+== 0.1.2 / 2008-06-15
+
+* Avoid string evaluation for dynamic methods
+* Fix has_many/has_one associations improperly loading classes too early
+* Add support for string and array comparison
+* Use after_create/after_destroy callbacks instead of defining the callback method itself
+
+== 0.1.1 / 2008-05-14
+
+* Fix automatically clearing association cache when it shouldn't be
+
+== 0.1.0 / 2008-05-05
+
+* Add support for overriding the unique attribute that defines an enumeration e.g.
+
+  acts_as_enumeration :title
+  acts_as_enumeration :controller, :action
+
+* Add support for using enumerations in has_many/has_one associations
+* Add support for Rails 2.0
+* Use has_finder to auto-generate finders for each enumeration value after defining a belongs_to association
+* Removed support for database-backed enumerations in favor of always using virtual enumerations
+* Fix enumerations failing when being reloaded
+* Fix problems with setting enumeration attributes to nil
+* Add inheritance support for virtual enumerations
+* Add support for converting unsafe identifier names (like "red!") to their safe symbol equivalent ("red")
+* Add ability to use truth accessors for determing the identifier name
+* Add support for virtual enumerations that don't need to be backed by the database
+
+== 0.0.2 / 2007-09-26
+
+* Move test fixtures out of the test application root directory
+* Convert dos newlines to unix newlines
+
+== 0.0.1 / 2007-08-04
+
+* Initial public release
+* Add/refactor unit tests
+* Add documentation

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2009 Aaron Pfeifer
+
+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.rdoc

@@ -0,0 +1,117 @@
+= enumerate_by
+
++enumerate_by+ adds support for declaring an ActiveRecord class as an
+enumeration.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/enumerate_by
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13265-enumerate_by
+
+Development
+
+* http://github.com/pluginaweek/enumerate_by
+
+Source
+
+* git://github.com/pluginaweek/enumerate_by.git
+
+== Description
+
+Support for enumerations is dependent on the type of database you use.  For
+example, MySQL has native support for the enum data type.  However, there is
+no native Rails support for defining enumerations and the associations between
+it and other models in the application.
+
+In addition, enumerations may often have more complex data and/or functionality
+associated with it that cannot simply be describe in a single column.
+
+enumerate_by adds support for pseudo-enumerations in Rails by allowing the
+enumeration's records to be defined in code, but continuing to express the
+relationship between an enumeration and other models using ActiveRecord
+associations.  The important thing to remember, however, is that while the
+associations exist, the enumerator is always used outside of the application,
+while either the enumerator or the enumerator's record would be referenced
+*within* the application.  This means that you would reference a Color record
+via it's enumerator (such as "red") everywhere in the code (conditions,
+assigning associations, forms, etc.), but it would always be stored in the
+database as a true association with the integer value of 1.
+
+== Usage
+
+  class Color < ActiveRecord::Base
+    enumerate_by :name
+    
+    belongs_to :group, :class_name => 'ColorGroup'
+    has_many :cars
+    
+    bootstrap(
+      {:id => 1, :name => 'red', :group => 'RGB'},
+      {:id => 2, :name => 'blue', :group => 'RGB'},
+      {:id => 3, :name => 'green', :group => 'RGB'},
+      {:id => 4, :name => 'cyan', :group => 'CMYK'}
+    )
+  end
+  
+  class ColorGroup < ActiveRecord::Base
+    enumerate_by :name
+    
+    has_many :colors, :foreign_key => 'group_id'
+    
+    bootstrap(
+      {:id => 1, :name => 'RGB'},
+      {:id => 2, :name => 'CMYK'}
+    )
+  end
+  
+  class Car < ActiveRecord::Base
+    belongs_to :color
+  end
+
+Each of the above models is backed by the database with its own table.  Both
+the Color and ColorGroup enumerations automatically synchronize with the
+records in the database based on what's define in their bootstrap data.
+
+The enumerations and their associations can be then be used like so:
+
+  car = Car.create(:color => 'red')   # => #<Car id: 1, color_id: 1>
+  car.color                           # => #<Color id: 1, name: "red">
+  car.color == 'red'                  # => true
+  car.color.name                      # => "red"
+  
+  car.color = 'blue'
+  car.save                            # => true
+  car                                 # => #<Car id: 1, color_id: 2>
+  
+  # Serialization
+  car.to_json                         # => "{id: 1, color: \"blue\"}"
+  car.to_xml                          # => "<car><id type=\"integer\">1</id><color>blue</color></car>"
+  
+  # Lookup
+  Car.with_color('blue')              # => [#<Car id: 1, color_id: 2>]
+  car = Car.find_by_color('blue')     # => #<Car id: 1, color_id: 2>
+  car.color == Color['blue']          # => true
+
+As mentioned previously, the important thing to note from the above example is
+that from an external perspective, "color" is simply an attribute on the Car.
+However, it's backed by a more complex association and model that allows Color
+to include advanced functionality that would normally not be possible with a
+simple attribute.
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
+
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
+== Dependencies
+
+* Rails 2.1 or later

data/Rakefile

@@ -0,0 +1,96 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'enumerate_by'
+  s.version           = '0.4.2'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Adds support for declaring an ActiveRecord class as an enumeration'
+  s.description       = s.summary
+  
+  s.files             = FileList['{lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
+task :default => :test
+
+desc "Test the #{spec.name} plugin."
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = spec.test_files
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb')
+end
+
+desc 'Generate a gemspec file.'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem.'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
+end
+
+desc 'Publish the API documentation.'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pgem, :pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new.configure
+  ruby_forge.login
+  
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'enumerate_by'

data/lib/enumerate_by/extensions/associations.rb

@@ -0,0 +1,109 @@
+module EnumerateBy
+  module Extensions #:nodoc:
+    # Adds a set of helpers for using enumerations in associations, including
+    # named scopes and assignment via enumerators.
+    # 
+    # The examples below assume the following models have been defined:
+    # 
+    #   class Color < ActiveRecord::Base
+    #     enumerate_by :name
+    #     
+    #     bootstrap(
+    #       {:id => 1, :name => 'red'},
+    #       {:id => 2, :name => 'blue'},
+    #       {:id => 3, :name => 'green'}
+    #     )
+    #   end
+    #   
+    #   class Car < ActiveRecord::Base
+    #     belongs_to :color
+    #   end
+    # 
+    # == Named scopes
+    # 
+    # A pair of named scopes are generated for each +belongs_to+ association
+    # that is identified by an enumeration.  In this case, the following
+    # named scopes get generated:
+    # * +with_color+ / +with_colors+ - Finds all cars with the given color(s)
+    # * +without_color+ / +without_colors+ - Finds all cars without the given color(s)
+    # 
+    # For example,
+    # 
+    #   Car.with_color('red')           # Cars with the color name "red"
+    #   Car.without_color('red')        # Cars without the color name "red"
+    #   Car.with_colors('red', 'blue')  # Cars with either the color names "red" or "blue"
+    # 
+    # == Association assignment
+    # 
+    # Normally, +belongs_to+ associations are assigned with either the actual
+    # record or through its primary key.  When used with enumerations, support
+    # is added for assigning these associations through the enumerators
+    # defined for the class.
+    # 
+    # For example,
+    # 
+    #   # With valid enumerator
+    #   car = Car.new         # => #<Car id: nil, color_id: nil>
+    #   car.color = 'red'
+    #   car.color_id          # => 1
+    #   car.color             # => #<Color id: 1, name: "red">
+    #   
+    #   # With invalid enumerator
+    #   car = Car.new         # => #<Car id: nil, color_id: nil>
+    #   car.color = 'invalid'
+    #   car.color_id          # => nil
+    #   car.color             # => nil
+    # 
+    # In the above example, the actual Color association is automatically
+    # looked up by finding the Color record identified by the enumerator the
+    # given enumerator ("red" in this case).
+    module Associations
+      def self.extended(base) #:nodoc:
+        class << base
+          alias_method_chain :belongs_to, :enumerations
+        end
+      end
+            
+      # Adds support for belongs_to and enumerations
+      def belongs_to_with_enumerations(association_id, options = {})
+        belongs_to_without_enumerations(association_id, options)
+        
+        # Override accessor if class is valid enumeration
+        reflection = reflections[association_id.to_sym]
+        if !reflection.options[:polymorphic] && (reflection.klass < ActiveRecord::Base) && reflection.klass.enumeration?
+          name = reflection.name
+          primary_key_name = reflection.primary_key_name
+          class_name = reflection.class_name
+          klass = reflection.klass
+          
+          # Inclusion scopes
+          %W(with_#{name} with_#{name.to_s.pluralize}).each do |scope_name|
+            named_scope scope_name.to_sym, lambda {|*enumerators| {
+              :conditions => {primary_key_name => klass.find_all_by_enumerator!(enumerators).map(&:id)}
+            }}
+          end
+          
+          # Exclusion scopes
+          %W(without_#{name} without_#{name.to_s.pluralize}).each do |scope_name|
+            named_scope scope_name.to_sym, lambda {|*enumerators| {
+              :conditions => ["#{primary_key_name} NOT IN (?)", klass.find_all_by_enumerator!(enumerators).map(&:id)]
+            }}
+          end
+          
+          # Hook in shortcut writer
+          define_method("#{name}_with_enumerators=") do |new_value|
+            send("#{name}_without_enumerators=", new_value.is_a?(klass) ? new_value : klass.find_by_enumerator(new_value))
+          end
+          alias_method_chain "#{name}=", :enumerators
+          
+          # Track the association
+          enumeration_associations[primary_key_name.to_s] = name.to_s
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  extend EnumerateBy::Extensions::Associations
+end

data/lib/enumerate_by/extensions/base_conditions.rb

@@ -0,0 +1,130 @@
+module EnumerateBy
+  module Extensions #:nodoc:
+    # Adds support for using enumerators in dynamic finders and conditions.
+    # For example suppose the following models are defined:
+    # 
+    #   class Color < ActiveRecord::Base
+    #     enumerate_by :name
+    #     
+    #     bootstrap(
+    #       {:id => 1, :name => 'red'},
+    #       {:id => 2, :name => 'blue'},
+    #       {:id => 3, :name => 'green'}
+    #     )
+    #   end
+    #   
+    #   class Car < ActiveRecord::Base
+    #     belongs_to :color
+    #   end
+    # 
+    # Normally, looking up all cars associated with a particular color
+    # requires either a join or knowing the id of the color upfront:
+    # 
+    #   Car.find(:all, :joins => :color, :conditions => {:colors => {:name => 'red}})
+    #   Car.find_by_color_id(1)
+    # 
+    # Instead of doing this manually, the color can be referenced directly
+    # via its enumerator like so:
+    # 
+    #   # With dynamic finders
+    #   Car.find_by_color('red')
+    #   
+    #   # With conditions
+    #   Car.all(:conditions => {:color => 'red'})
+    #   
+    #   # With updates
+    #   Car.update_all(:color => 'red')
+    # 
+    # In the above examples, +color+ is essentially treated like a normal
+    # attribute on the class, instead triggering the associated Color record
+    # to be looked up and replacing the condition with a +color_id+ condition.
+    # 
+    # *Note* that this does not add an additional join on the +colors+ table
+    # since the lookup of the color's id should be relatively fast when it's
+    # cached in-memory.
+    module BaseConditions
+      def self.extended(base) #:nodoc:
+        class << base
+          alias_method_chain :construct_attributes_from_arguments, :enumerations
+          alias_method_chain :sanitize_sql_hash_for_conditions, :enumerations
+          alias_method_chain :sanitize_sql_hash_for_assignment, :enumerations
+          alias_method_chain :all_attributes_exists?, :enumerations
+        end
+      end
+      
+      # Add support for dynamic finders
+      def construct_attributes_from_arguments_with_enumerations(attribute_names, arguments)
+        attributes = construct_attributes_from_arguments_without_enumerations(attribute_names, arguments)
+        attribute_names.each_with_index do |name, idx|
+          if options = enumerator_options_for(name, arguments[idx])
+            attributes.delete(name)
+            attributes.merge!(options)
+          end
+        end
+        
+        attributes
+      end
+      
+      # Sanitizes a hash of attribute/value pairs into SQL conditions for a WHERE clause.
+      def sanitize_sql_hash_for_conditions_with_enumerations(attrs, *args)
+        replace_enumerations_in_hash(attrs)
+        sanitize_sql_hash_for_conditions_without_enumerations(attrs, *args)
+      end
+      
+      # Sanitizes a hash of attribute/value pairs into SQL conditions for a SET clause.
+      def sanitize_sql_hash_for_assignment_with_enumerations(attrs, *args)
+        replace_enumerations_in_hash(attrs, false)
+        sanitize_sql_hash_for_assignment_without_enumerations(attrs, *args)
+      end
+      
+      # Make sure dynamic finders don't fail since it won't find the association
+      # name in its columns
+      def all_attributes_exists_with_enumerations?(attribute_names)
+        exists = all_attributes_exists_without_enumerations?(attribute_names)
+        exists ||= attribute_names.all? do |name|
+          column_methods_hash.include?(name.to_sym) || reflect_on_enumeration(name)
+        end
+      end
+      
+      private
+        # Finds all of the attributes that are enumerations and replaces them
+        # with the correct enumerator id
+        def replace_enumerations_in_hash(attrs, allow_multiple = true) #:nodoc:
+          attrs.each do |attr, value|
+            if options = enumerator_options_for(attr, value, allow_multiple)
+              attrs.delete(attr)
+              attrs.merge!(options)
+            end
+          end
+        end
+        
+        # Generates the enumerator lookup options for the given association
+        # name and enumerator value.  If the association is *not* for an
+        # enumeration, then this will return nil.
+        def enumerator_options_for(name, enumerator, allow_multiple = true)
+          if reflection = reflect_on_enumeration(name)
+            klass = reflection.klass
+            attribute = reflection.primary_key_name
+            id = if allow_multiple && enumerator.is_a?(Array)
+              enumerator.map {|enumerator| klass.find_by_enumerator!(enumerator).id}
+            else
+              klass.find_by_enumerator!(enumerator).id
+            end
+            
+            {attribute => id}
+          end
+        end
+        
+        # Attempts to find an association with the given name *and* represents
+        # an enumeration
+        def reflect_on_enumeration(name)
+          reflection = reflect_on_association(name.to_sym)
+          reflection if reflection && reflection.klass.enumeration?
+        end
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  extend EnumerateBy::Extensions::BaseConditions
+end