enumerate_by 0.4.0

data/CHANGELOG.rdoc

@@ -0,0 +1,101 @@
+== master
+
+== 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,88 @@
+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.0'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Adds support for declaring an ActiveRecord class as an enumeration'
+  
+  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
+  
+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.rb

@@ -0,0 +1,366 @@
+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!
+        delete_all(['id NOT IN (?)', records.map {|record| record[:id]}])
+        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 = !existing.include?(attributes[:id]) ? new(attributes) : begin
+            record = existing[attributes[:id]]
+            record.attributes = attributes
+            record
+          end
+          record.id = attributes[:id]
+          
+          # Only update defaults if they aren't already specified
+          defaults.each {|attribute, value| record[attribute] = value unless record.send("#{attribute}?")} if defaults
+          
+          # Force failed saves to stop execution
+          record.save!
+          record
+        end
+        
+        records
+      end
+    end
+    
+    # Quickly synchronizes the given records with the existing ones.  This
+    # disables certain features of ActiveRecord in order to provide a speed
+    # boost, including:
+    # * Callbacks
+    # * Validations
+    # * Timestamps
+    # * Dirty attributes
+    # 
+    # This produces a noticeable performance increase when bootstrapping more
+    # than several hundred records.
+    # 
+    # See EnumerateBy::Bootstrapped#bootstrap for information about usage.
+    def fast_bootstrap(*records)
+      features = {:callbacks => %w(create create_or_update valid?), :dirty => %w(write_attribute), :validation => %w(save save!)}
+      features.each do |feature, methods|
+        methods.each do |method|
+          method, punctuation = method.sub(/([?!=])$/, ''), $1
+          alias_method "#{method}_without_bootstrap#{punctuation}", "#{method}#{punctuation}"
+          alias_method "#{method}#{punctuation}", "#{method}_without_#{feature}#{punctuation}"
+        end
+      end
+      original_record_timestamps = self.record_timestamps
+      self.record_timestamps = false
+      
+      bootstrap(*records)
+    ensure
+      features.each do |feature, methods|
+        methods.each do |method|
+          method, punctuation = method.sub(/([?!=])$/, ''), $1
+          alias_method "#{method}_without_#{feature}#{punctuation}", "#{method}#{punctuation}"
+          alias_method "#{method}#{punctuation}", "#{method}_without_bootstrap#{punctuation}"
+        end
+      end
+      self.record_timestamps = original_record_timestamps
+    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