enumerate_by 0.4.0

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)
+        replace_enumerations_in_hash(attrs)
+        sanitize_sql_hash_for_conditions_without_enumerations(attrs)
+      end
+      
+      # Sanitizes a hash of attribute/value pairs into SQL conditions for a SET clause.
+      def sanitize_sql_hash_for_assignment_with_enumerations(attrs)
+        replace_enumerations_in_hash(attrs, false)
+        sanitize_sql_hash_for_assignment_without_enumerations(attrs)
+      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

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/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