pluginaweek-enumerate_by 0.4.2

data/lib/enumerate_by/extensions/serializer.rb

@@ -0,0 +1,117 @@
+module EnumerateBy
+  module Extensions #:nodoc:
+    # Adds support for automatically converting enumeration attributes to the
+    # value represented by them.
+    # 
+    # == Examples
+    # 
+    # 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
+    # 
+    # Given the above, the enumerator for the car will be automatically
+    # used for serialization instead of the foreign key like so:
+    # 
+    #   car = Car.create(:color => 'red')  # => #<Car id: 1, color_id: 1>
+    #   car.to_xml  # => "<car><id type=\"integer\">1</id><color>red</color></car>"
+    #   car.to_json # => "{id: 1, color: \"red\"}"
+    # 
+    # == Conversion options
+    # 
+    # The actual conversion of enumeration associations can be controlled
+    # using the following options:
+    # 
+    #   car.to_json                           # => "{id: 1, color: \"red\"}"
+    #   car.to_json(:enumerations => false)   # => "{id: 1, color_id: 1}"
+    #   car.to_json(:only => [:color_id])     # => "{color_id: 1}"
+    #   car.to_json(:only => [:color])        # => "{color: \"red\"}"
+    #   car.to_json(:include => :color)       # => "{id: 1, color_id: 1, color: {id: 1, name: \"red\"}}"
+    # 
+    # As can be seen from above, enumeration attributes can either be treated
+    # as pseudo-attributes on the record or its actual association.
+    module Serializer
+      def self.included(base) #:nodoc:
+        base.class_eval do
+          alias_method_chain :serializable_attribute_names, :enumerations
+          alias_method_chain :serializable_record, :enumerations
+        end
+      end
+      
+      # Automatically converted enumeration attributes to their association
+      # names so that they *appear* as attributes
+      def serializable_attribute_names_with_enumerations
+        attribute_names = serializable_attribute_names_without_enumerations
+        
+        # Adjust the serializable attributes by converting primary keys for
+        # enumeration associations to their association name (where possible)
+        if convert_enumerations?
+          @only_attributes = Array(options[:only]).map(&:to_s)
+          @include_associations = Array(options[:include]).map(&:to_s)
+          
+          attribute_names.map! {|attribute| enumeration_association_for(attribute) || attribute}
+          attribute_names |= @record.class.enumeration_associations.values & @only_attributes
+          attribute_names.sort!
+          attribute_names -= options[:except].map(&:to_s) unless options[:only]
+        end
+        
+        attribute_names
+      end
+      
+      # Automatically casts enumerations to their public values
+      def serializable_record_with_enumerations
+        returning(serializable_record = serializable_record_without_enumerations) do
+          serializable_record.each do |attribute, value|
+            # Typecast to enumerator value
+            serializable_record[attribute] = value.enumerator if typecast_to_enumerator?(attribute, value)
+          end if convert_enumerations?
+        end
+      end
+      
+      private
+        # Should enumeration attributes be automatically converted based on
+        # the serialization configuration
+        def convert_enumerations?
+          options[:enumerations] != false
+        end
+        
+        # Should the given attribute be converted to the actual enumeration?
+        def convert_to_enumeration?(attribute)
+          !@only_attributes.include?(attribute)
+        end
+        
+        # Gets the association name for the given enumeration attribute, if
+        # one exists
+        def enumeration_association_for(attribute)
+          association = @record.class.enumeration_associations[attribute]
+          association if association && convert_to_enumeration?(attribute) && !include_enumeration?(association)
+        end
+        
+        # Is the given enumeration attribute being included as a whole record
+        # instead of just an individual attribute?
+        def include_enumeration?(association)
+          @include_associations.include?(association)
+        end
+        
+        # Should the given value be typecasted to its enumerator value?
+        def typecast_to_enumerator?(association, value)
+          value.is_a?(ActiveRecord::Base) && value.class.enumeration? && !include_enumeration?(association)
+        end
+    end
+  end
+end
+
+ActiveRecord::Serialization::Serializer.class_eval do
+  include EnumerateBy::Extensions::Serializer
+end

data/lib/enumerate_by/extensions/xml_serializer.rb

@@ -0,0 +1,41 @@
+module EnumerateBy
+  module Extensions #:nodoc:
+    module XmlSerializer #:nodoc:
+      # Adds support for xml serialization of enumeration associations as
+      # attributes
+      module Attribute
+        def self.included(base) #:nodoc:
+          base.class_eval do
+            alias_method_chain :compute_type, :enumerations
+            alias_method_chain :compute_value, :enumerations
+          end
+        end
+        
+        protected
+          # Enumerator types are always strings
+          def compute_type_with_enumerations
+            enumeration_association? ? :string : compute_type_without_enumerations
+          end
+          
+          # Gets the real value representing the enumerator
+          def compute_value_with_enumerations
+            if enumeration_association?
+              association = @record.send(name)
+              association.enumerator if association
+            else
+              compute_value_without_enumerations
+            end
+          end
+          
+          # Is this attribute defined by an enumeration association?
+          def enumeration_association?
+            @enumeration_association ||= @record.enumeration_associations.value?(name)
+          end
+      end
+    end
+  end
+end
+
+ActiveRecord::XmlSerializer::Attribute.class_eval do
+  include EnumerateBy::Extensions::XmlSerializer::Attribute
+end

data/lib/enumerate_by.rb

@@ -0,0 +1,395 @@
+require 'enumerate_by/extensions/associations'
+require 'enumerate_by/extensions/base_conditions'
+require 'enumerate_by/extensions/serializer'
+require 'enumerate_by/extensions/xml_serializer'
+
+# An enumeration defines a finite set of enumerators which (often) have no
+# numerical order.  This extension provides a general technique for using
+# ActiveRecord classes to define enumerations.
+module EnumerateBy
+  # Whether to enable enumeration caching (default is true)
+  mattr_accessor :perform_caching
+  self.perform_caching = true
+  
+  module MacroMethods
+    def self.extended(base) #:nodoc:
+      base.class_eval do
+        # Tracks which associations are backed by an enumeration
+        # {"foreign key" => "association name"}
+        class_inheritable_accessor :enumeration_associations
+        self.enumeration_associations = {}
+      end
+    end
+    
+    # Indicates that this class is an enumeration.
+    # 
+    # The default attribute used to enumerate the class is +name+.  You can
+    # override this by specifying a custom attribute that will be used to
+    # *uniquely* reference a record.
+    # 
+    # *Note* that a presence and uniqueness validation is automatically
+    # defined for the given attribute since all records must have this value
+    # in order to be properly enumerated.
+    # 
+    # Configuration options:
+    # * <tt>:cache</tt> - Whether to cache all finder queries for this
+    #   enumeration.  Default is true.
+    # 
+    # == Defining enumerators
+    # 
+    # The enumerators of the class uniquely identify each record in the
+    # table.  The enumerator value is based on the attribute described above.
+    # In scenarios where the records are managed in code (like colors,
+    # countries, states, etc.), records can be automatically synchronized
+    # via #bootstrap.
+    # 
+    # == Accessing records
+    # 
+    # The actual records for an enumeration can be accessed via shortcut
+    # helpers like so:
+    # 
+    #   Color['red']    # => #<Color id: 1, name: "red">
+    #   Color['green']  # => #<Color id: 2, name: "green">
+    # 
+    # When caching is enabled, these lookup queries are cached so that there
+    # is no performance hit.
+    # 
+    # == Associations
+    # 
+    # When using enumerations together with +belongs_to+ associations, the
+    # enumerator value can be used as a shortcut for assigning the
+    # association.
+    # 
+    # In addition, the enumerator value is automatically used during
+    # serialization (xml and json) of the associated record instead of the
+    # foreign key for the association.
+    # 
+    # For more information about how to use enumerations with associations,
+    # see EnumerateBy::Extensions::Associations and EnumerateBy::Extensions::Serializer.
+    # 
+    # === Finders
+    # 
+    # In order to be consistent by always using enumerators to reference
+    # records, a set of finder extensions are added to allow searching
+    # for records like so:
+    # 
+    #   class Car < ActiveRecord::Base
+    #     belongs_to :color
+    #   end
+    #   
+    #   Car.find_by_color('red')
+    #   Car.all(:conditions => {:color => 'red'})
+    # 
+    # For more information about finders, see EnumerateBy::Extensions::BaseConditions.
+    def enumerate_by(attribute = :name, options = {})
+      options.reverse_merge!(:cache => true)
+      options.assert_valid_keys(:cache)
+      
+      extend EnumerateBy::ClassMethods
+      extend EnumerateBy::Bootstrapped
+      include EnumerateBy::InstanceMethods
+      
+      # The attribute representing a record's enumerator
+      cattr_accessor :enumerator_attribute
+      self.enumerator_attribute = attribute
+      
+      # Whether to perform caching of enumerators within finder queries
+      cattr_accessor :perform_enumerator_caching
+      self.perform_enumerator_caching = options[:cache]
+      
+      # The cache store to use for queries (default is a memory store)
+      cattr_accessor :enumerator_cache_store
+      self.enumerator_cache_store = ActiveSupport::Cache::MemoryStore.new
+      
+      validates_presence_of attribute
+      validates_uniqueness_of attribute
+    end
+    
+    # Does this class define an enumeration?  Always false.
+    def enumeration?
+      false
+    end
+  end
+  
+  module ClassMethods
+    # Does this class define an enumeration?  Always true.
+    def enumeration?
+      true
+    end
+    
+    # Finds the record that is associated with the given enumerator.  The
+    # attribute that defines the enumerator is based on what was specified
+    # when calling +enumerate_by+.
+    # 
+    # For example,
+    # 
+    #   Color.find_by_enumerator('red')     # => #<Color id: 1, name: "red">
+    #   Color.find_by_enumerator('invalid') # => nil
+    def find_by_enumerator(enumerator)
+      first(:conditions => {enumerator_attribute => enumerator})
+    end
+    
+    # Finds the record that is associated with the given enumerator.  If no
+    # record is found, then an ActiveRecord::RecordNotFound exception is
+    # raised.
+    # 
+    # For example,
+    # 
+    #   Color['red']      # => #<Color id: 1, name: "red">
+    #   Color['invalid']  # => ActiveRecord::RecordNotFound: Couldn't find Color with name "red"
+    # 
+    # To avoid raising an exception on invalid enumerators, use +find_by_enumerator+.
+    def find_by_enumerator!(enumerator)
+      find_by_enumerator(enumerator) || raise(ActiveRecord::RecordNotFound, "Couldn't find #{name} with #{enumerator_attribute} #{enumerator.inspect}")
+    end
+    alias_method :[], :find_by_enumerator!
+    
+    # Finds records with the given enumerators.
+    # 
+    # For example,
+    # 
+    #   Color.find_all_by_enumerator('red', 'green')  # => [#<Color id: 1, name: "red">, #<Color id: 1, name: "green">]
+    #   Color.find_all_by_enumerator('invalid')       # => []
+    def find_all_by_enumerator(enumerators)
+      all(:conditions => {enumerator_attribute => enumerators})
+    end
+    
+    # Finds records with the given enumerators.  If no record is found for a
+    # particular enumerator, then an ActiveRecord::RecordNotFound exception
+    # is raised.
+    # 
+    # For Example,
+    # 
+    #   Color.find_all_by_enumerator!('red', 'green')   # => [#<Color id: 1, name: "red">, #<Color id: 1, name: "green">]
+    #   Color.find_all_by_enumerator!('invalid')        # => ActiveRecord::RecordNotFound: Couldn't find Color with name(s) "invalid"
+    # 
+    # To avoid raising an exception on invalid enumerators, use +find_all_by_enumerator+.
+    def find_all_by_enumerator!(enumerators)
+      records = find_all_by_enumerator(enumerators)
+      missing = [enumerators].flatten - records.map(&:enumerator)
+      missing.empty? ? records : raise(ActiveRecord::RecordNotFound, "Couldn't find #{name} with #{enumerator_attribute}(s) #{missing.map(&:inspect).to_sentence}")
+    end
+    
+    # Adds support for looking up results from the enumeration cache for
+    # before querying the database.
+    # 
+    # This allows for enumerations to permanently cache find queries, avoiding
+    # unnecessary lookups in the database.
+    [:find_by_sql, :exists?, :calculate].each do |method|
+      define_method(method) do |*args|
+        if EnumerateBy.perform_caching && perform_enumerator_caching
+          enumerator_cache_store.fetch([method] + args) { super }
+        else
+          super
+        end
+      end
+    end
+    
+    # Temporarily disables the enumeration cache (as well as the query cache)
+    # within the context of the given block if the enumeration is configured
+    # to allow caching.
+    def uncached
+      old = perform_enumerator_caching
+      self.perform_enumerator_caching = false
+      super
+    ensure
+      self.perform_enumerator_caching = old
+    end
+  end
+  
+  module Bootstrapped
+    # Synchronizes the given records with existing ones.  This ensures that
+    # only the correct and most up-to-date records exist in the database.
+    # The sync process is as follows:
+    # * Any existing record that doesn't match is deleted
+    # * Existing records with matches are updated based on the given attributes for that record
+    # * Records that don't exist are created
+    # 
+    # To create records that can be referenced elsewhere in the database, an
+    # id should always be specified.  Otherwise, records may change id each
+    # time they are bootstrapped.
+    # 
+    # == Examples
+    # 
+    #   class Color < ActiveRecord::Base
+    #     enumerate_by :name
+    #     
+    #     bootstrap(
+    #       {:id => 1, :name => 'red'},
+    #       {:id => 2, :name => 'blue'},
+    #       {:id => 3, :name => 'green'}
+    #     )
+    #   end
+    # 
+    # In the above model, the +colors+ table will be synchronized with the 3
+    # records passed into the +bootstrap+ helper.  Any existing records that
+    # do not match those 3 are deleted.  Otherwise, they are either created or
+    # updated with the attributes specified.
+    # 
+    # == Defaults
+    # 
+    # In addition to *always* synchronizing certain attributes, an additional
+    # +defaults+ option can be given to indicate that certain attributes
+    # should only be synchronized if they haven't been modified in the
+    # database.
+    # 
+    # For example,
+    # 
+    #   class Color < ActiveRecord::Base
+    #     enumerate_by :name
+    #     
+    #     bootstrap(
+    #       {:id => 1, :name => 'red', :defaults => {:html => '#f00'}},
+    #       {:id => 2, :name => 'blue', :defaults => {:html => '#0f0'}},
+    #       {:id => 3, :name => 'green', :defaults => {:html => '#00f'}}
+    #     )
+    #   end
+    # 
+    # In the above model, the +name+ attribute will always be updated on
+    # existing records in the database.  However, the +html+ attribute will
+    # only be synchronized if the attribute is nil in the database.
+    # Otherwise, any changes to that column remain there.
+    def bootstrap(*records)
+      uncached do
+        # Remove records that are no longer being used
+        records.flatten!
+        ids = records.map {|record| record[:id]}.compact
+        delete_all(ids.any? ? ['id NOT IN (?)', ids] : nil)
+        
+        # Find remaining existing records (to be updated)
+        existing = all.inject({}) {|existing, record| existing[record.id] = record; existing}
+        
+        records.map! do |attributes|
+          attributes.symbolize_keys!
+          defaults = attributes.delete(:defaults)
+          
+          # Update with new attributes
+          record =
+            if record = existing[attributes[:id]]
+              attributes.merge!(defaults.delete_if {|attribute, value| record.send("#{attribute}?")}) if defaults
+              record.attributes = attributes
+              record
+            else
+              attributes.merge!(defaults) if defaults
+              new(attributes)
+            end
+          record.id = attributes[:id]
+          
+          # Force failed saves to stop execution
+          record.save!
+          record
+        end
+        
+        records
+      end
+    end
+    
+    # Quickly synchronizes the given records with the existing ones.  This
+    # skips ActiveRecord altogether, interacting directly with the connection
+    # instead.  As a result, certain features are not available when being
+    # bootstrapped, including:
+    # * Callbacks
+    # * Validations
+    # * Transactions
+    # * Timestamps
+    # * Dirty attributes
+    # 
+    # Also note that records are created directly without creating instances
+    # of the model.  As a result, all of the attributes for the record must
+    # be specified.
+    # 
+    # This produces a significant performance increase when bootstrapping more
+    # than several hundred records.
+    # 
+    # See EnumerateBy::Bootstrapped#bootstrap for information about usage.
+    def fast_bootstrap(*records)
+      # Remove records that are no longer being used
+      records.flatten!
+      ids = records.map {|record| record[:id]}.compact
+      delete_all(ids.any? ? ['id NOT IN (?)', ids] : nil)
+      
+      # Find remaining existing records (to be updated)
+      quoted_table_name = self.quoted_table_name
+      existing = connection.select_all("SELECT * FROM #{quoted_table_name}").inject({}) {|existing, record| existing[record['id'].to_i] = record; existing}
+      
+      records.each do |attributes|
+        attributes.stringify_keys!
+        if defaults = attributes.delete('defaults')
+          defaults.stringify_keys!
+        end
+        
+        id = attributes['id']
+        if existing_attributes = existing[id]
+          # Record exists: Update attributes
+          attributes.delete('id')
+          attributes.merge!(defaults.delete_if {|attribute, value| !existing_attributes[attribute].nil?}) if defaults
+          update_all(attributes, :id => id)
+        else
+          # Record doesn't exist: create new one
+          attributes.merge!(defaults) if defaults
+          column_names = []
+          values = []
+          
+          attributes.each do |column_name, value|
+            column_names << connection.quote_column_name(column_name)
+            values << connection.quote(value, columns_hash[column_name])
+          end
+          
+          connection.insert(
+            "INSERT INTO #{quoted_table_name} (#{column_names * ', '}) VALUES(#{values * ', '})",
+            "#{name} Create", primary_key, id, sequence_name
+          )
+        end
+      end
+      
+      true
+    end
+  end
+  
+  module InstanceMethods
+    # Whether or not this record is equal to the given value. If the value is
+    # a String, then it is compared against the enumerator.  Otherwise,
+    # ActiveRecord's default equality comparator is used.
+    def ==(arg)
+      arg.is_a?(String) ? self == self.class.find_by_enumerator!(arg) : super
+    end
+    
+    # Determines whether this enumeration is in the given list.
+    # 
+    # For example,
+    # 
+    #   color = Color.find_by_name('red')   # => #<Color id: 1, name: "red">
+    #   color.in?('green')                  # => false
+    #   color.in?('red', 'green')           # => true
+    def in?(*list)
+      list.any? {|item| self === item}
+    end
+    
+    # A helper method for getting the current value of the enumerator
+    # attribute for this record.  For example, if this record's model is
+    # enumerated by the attribute +name+, then this will return the current
+    # value for +name+.
+    def enumerator
+      send(enumerator_attribute)
+    end
+    
+    # Stringifies the record typecasted to the enumerator value.
+    # 
+    # For example,
+    # 
+    #   color = Color.find_by_name('red')   # => #<Color id: 1, name: "red">
+    #   color.to_s                          # => "red"
+    def to_s
+      to_str
+    end
+    
+    # Add support for equality comparison with strings
+    def to_str
+      enumerator.to_s
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  extend EnumerateBy::MacroMethods
+end

data/test/app_root/app/models/car.rb

@@ -0,0 +1,4 @@
+class Car < ActiveRecord::Base
+  belongs_to :color
+  belongs_to :feature, :polymorphic => true
+end

data/test/app_root/app/models/color.rb

@@ -0,0 +1,3 @@
+class Color < ActiveRecord::Base
+  enumerate_by :name
+end

data/test/app_root/db/migrate/001_create_colors.rb

@@ -0,0 +1,12 @@
+class CreateColors < ActiveRecord::Migration
+  def self.up
+    create_table :colors do |t|
+      t.string :name, :null => false
+      t.string :html
+    end
+  end
+  
+  def self.down
+    drop_table :colors
+  end
+end

data/test/app_root/db/migrate/002_create_cars.rb

@@ -0,0 +1,13 @@
+class CreateCars < ActiveRecord::Migration
+  def self.up
+    create_table :cars do |t|
+      t.string :name
+      t.references :color
+      t.references :feature, :class_name => 'Color', :polymorphic => true
+    end
+  end
+  
+  def self.down
+    drop_table :cars
+  end
+end

data/test/factory.rb

@@ -0,0 +1,48 @@
+module Factory
+  # Build actions for the model
+  def self.build(model, &block)
+    name = model.to_s.underscore
+    
+    define_method("#{name}_attributes", block)
+    define_method("valid_#{name}_attributes") {|*args| valid_attributes_for(model, *args)}
+    define_method("new_#{name}")              {|*args| new_record(model, *args)}
+    define_method("create_#{name}")           {|*args| create_record(model, *args)}
+  end
+  
+  # Get valid attributes for the model
+  def valid_attributes_for(model, attributes = {})
+    name = model.to_s.underscore
+    send("#{name}_attributes", attributes)
+    attributes.stringify_keys!
+    attributes
+  end
+  
+  # Build an unsaved record
+  def new_record(model, *args)
+    attributes = valid_attributes_for(model, *args)
+    record = model.new(attributes)
+    attributes.each {|attr, value| record.send("#{attr}=", value) if model.accessible_attributes && !model.accessible_attributes.include?(attr) || model.protected_attributes && model.protected_attributes.include?(attr)}
+    record
+  end
+  
+  # Build and save/reload a record
+  def create_record(model, *args)
+    record = new_record(model, *args)
+    record.save!
+    record.reload
+    record
+  end
+  
+  build Car do |attributes|
+    attributes[:color] = create_color unless attributes.include?(:color)
+    attributes.reverse_merge!(
+      :name => 'Ford Mustang'
+    )
+  end
+  
+  build Color do |attributes|
+    attributes.reverse_merge!(
+      :name => 'red'
+    )
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,28 @@
+# Load the plugin testing framework
+$:.unshift("#{File.dirname(__FILE__)}/../../plugin_test_helper/lib")
+require 'rubygems'
+require 'plugin_test_helper'
+
+# Run the migrations
+ActiveRecord::Migrator.migrate("#{Rails.root}/db/migrate")
+
+# Mixin the factory helper
+require File.expand_path("#{File.dirname(__FILE__)}/factory")
+Test::Unit::TestCase.class_eval do
+  include Factory
+end
+
+# Add query counter
+ActiveRecord::Base.connection.class.class_eval do
+  IGNORED_SQL = [/^PRAGMA/, /^SELECT currval/, /^SELECT CAST/, /^SELECT @@IDENTITY/, /^SELECT @@ROWCOUNT/, /^SAVEPOINT/, /^ROLLBACK TO SAVEPOINT/, /^RELEASE SAVEPOINT/, /SHOW FIELDS/]
+  
+  def execute_with_query_record(sql, name = nil, &block)
+    $queries_executed ||= []
+    $queries_executed << sql unless IGNORED_SQL.any? { |r| sql =~ r }
+    execute_without_query_record(sql, name, &block)
+  end
+  
+  alias_method_chain :execute, :query_record
+end
+
+EnumerateBy.perform_caching = false