has_enumeration 0.1.0

data/Gemfile

@@ -0,0 +1,5 @@
+source 'http://rubygems.org'
+
+gem 'activerecord', '>= 3.0.0.rc'
+gem 'rspec', '>= 2.0.0.beta.19'
+gem 'cucumber', '>= 0.8.5'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+(The MIT License)
+
+Copyright (c) 2010 Greg Spurrier
+
+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.txt

@@ -0,0 +1,35 @@
+== Description
+This ActiveRecord plugin enables attributes to be declared as enumerations
+of symbols.
+
+== Example
+class TestObject < ActiveRecord::Base
+  # Integer attribute with explicit value mapping
+  has_enumeration :color, :red => 1, :green => 2, :blue => 3
+
+
+  # String attribute with implicit value mapping
+  # has_enumeration :color, [:red, :green, :blue]
+end
+
+# Value and predicates
+obj = TestObject.new
+obj.color.value                    # => nil
+obj.color = :red                   # => :red
+obj.color.value                    # => :red
+obj.color.red?                     # => true
+obj.color.green?                   # => false
+
+# Querying
+TestObject.where(:color => :red)
+
+== Getting the Latest Version
+The repository for has_enumeration is hosted at GitHub:
+  Web page:   http://github.com/gregspurrier/has_enumeration
+  Clone URL:  git://github.com/gregspurrier/has_enumeration.git
+
+== Supported Versions
+has_enumeration has been tested with:
+  - ActiveRecord 3.0.0rc
+  - Ruby 1.8.7-p299
+  - Ruby 1.9.2-head (revision 28788)

data/Rakefile

@@ -0,0 +1,17 @@
+require 'jeweler'
+
+Jeweler::Tasks.new do |gemspec|
+  gemspec.name = "has_enumeration"
+  gemspec.summary = "Support for symbol-based enumerations in ActiveRecord"
+  gemspec.description = <<-EOF
+    Extends ActiveRecord with the has_enumeration method that allows an
+    attribute to be declared as storing an enumeration.  The enumeration
+    is specified as a mapping between symbols and their underlying
+    representation in the database.  Predicates are provided for each
+    symbol in the enumeration and the symbols may be used in finder methods.
+  EOF
+  gemspec.email = "greg@rujubu.com"
+  gemspec.homepage = "http://github.com/gregspurrier/has_enumeration"
+  gemspec.author = "Greg Spurrier"
+end
+Jeweler::GemcutterTasks.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/features/explicitly_mapped_enumeration.feature

@@ -0,0 +1,51 @@
+Feature:
+
+  As a programmer using an ActiveRecord model with an integer column
+  representing an enumerated value
+  I want to be able to refer to the enumeration symbolically and have
+  predicates to test its value
+  So that I can write pretty, concise code.
+
+  Scenario Outline: set an enumerated value on an unsaved object
+    Given a model with an explicitly-mapped enumeration of red, green, and blue
+    And an unsaved instance of that model
+    When I assign a symbolic value <assigned> to the enumeration
+    Then it should have the assigned value as its value
+    And the red? predicate should be <red?>
+    And the green? predicate should be <green?>
+    And the blue? predicate should be <blue?>
+
+    Scenarios: setting various values
+      | assigned | red?  | green? | blue? |
+      | :red     | true  | false  | false |
+      | :green   | false | true   | false |
+      | :blue    | false | false  | true  |
+
+  Scenario Outline: set an enumerated value then save and reload
+    Given a model with an explicitly-mapped enumeration of red, green, and blue
+    And an unsaved instance of that model
+    When I assign a symbolic value <assigned> to the enumeration
+    And I save and reload the object
+    Then it should have the assigned value as its value
+    And the red? predicate should be <red?>
+    And the green? predicate should be <green?>
+    And the blue? predicate should be <blue?>
+
+    Scenarios: setting various values
+      | assigned | red?  | green? | blue? |
+      | :red     | true  | false  | false |
+      | :green   | false | true   | false |
+      | :blue    | false | false  | true  |
+
+  Scenario Outline: find objects with a specific enumerated value
+    Given a model with an explicitly-mapped enumeration of red, green, and blue
+    And a set of objects with a variety of values for the enumeration
+    When I query for objects with the value <value>
+    Then I should get all of the objects having that value
+    And I should not get any objects having other values
+
+    Scenarios: querying various values
+      | value  |
+      | :red   |
+      | :green |
+      | :blue  |

data/features/implicitly_mapped_enumeration.feature

@@ -0,0 +1,51 @@
+Feature:
+
+  As a programmer using an ActiveRecord model with a string column
+  representing an enumerated value
+  I want to be able to refer to the enumeration symbolically and have
+  predicates to test its value
+  So that I can write pretty, concise code.
+
+  Scenario Outline: set an enumerated value on an unsaved object
+    Given a model with an implicitly-mapped enumeration of red, green, and blue
+    And an unsaved instance of that model
+    When I assign a symbolic value <assigned> to the enumeration
+    Then it should have the assigned value as its value
+    And the red? predicate should be <red?>
+    And the green? predicate should be <green?>
+    And the blue? predicate should be <blue?>
+
+    Scenarios: setting various values
+      | assigned | red?  | green? | blue? |
+      | :red     | true  | false  | false |
+      | :green   | false | true   | false |
+      | :blue    | false | false  | true  |
+
+  Scenario Outline: set an enumerated value then save and reload
+    Given a model with an implicitly-mapped enumeration of red, green, and blue
+    And an unsaved instance of that model
+    When I assign a symbolic value <assigned> to the enumeration
+    And I save and reload the object
+    Then it should have the assigned value as its value
+    And the red? predicate should be <red?>
+    And the green? predicate should be <green?>
+    And the blue? predicate should be <blue?>
+
+    Scenarios: setting various values
+      | assigned | red?  | green? | blue? |
+      | :red     | true  | false  | false |
+      | :green   | false | true   | false |
+      | :blue    | false | false  | true  |
+
+  Scenario Outline: find objects with a specific enumerated value
+    Given a model with an implicitly-mapped enumeration of red, green, and blue
+    And a set of objects with a variety of values for the enumeration
+    When I query for objects with the value <value>
+    Then I should get all of the objects having that value
+    And I should not get any objects having other values
+
+    Scenarios: querying various values
+      | value  |
+      | :red   |
+      | :green |
+      | :blue  |

data/features/step_definitions/has_enumeration_steps.rb

@@ -0,0 +1,58 @@
+Given /^a model with an explicitly-mapped enumeration of red, green, and blue$/ do
+  @model_class = ExplicitlyMappedModel
+end
+
+Given /^a model with an implicitly-mapped enumeration of red, green, and blue$/ do
+  @model_class = ImplicitlyMappedModel
+end
+
+Given /^an unsaved instance of that model$/ do
+  @object = @model_class.new
+end
+
+When /^I assign a symbolic value :([a-z_]+) to the enumeration$/ do |value|
+  @assigned = value.to_sym
+  @object.color = @assigned
+end
+
+When /^I save and reload the object$/ do
+  @object.save!
+  @object = @model_class.find(@object.id)
+end
+
+Then /^it should have the assigned value as its value$/ do
+  @object.color.value.should == @assigned
+end
+
+Then /^the ([a-z_]+\?) predicate should be (true|false)$/ do |predicate, value|
+  if value == 'true'
+    expected_value = true
+  else
+    expected_value = false
+  end
+  @object.color.send(predicate).should == expected_value  
+end
+
+
+Given /^a set of objects with a variety of values for the enumeration$/ do
+  @model_class.delete_all
+  2.times do
+    [:red, :green, :blue].each do |color|
+      @model_class.create!(:color => color)
+    end
+  end
+  @all_objects = @model_class.all(:order => :id)
+end
+
+When /^I query for objects with the value :([a-z_]+)$/ do |value|
+  @desired_color = value.to_sym
+  @results = @model_class.where(:color => @desired_color).order(:id)
+end
+
+Then /^I should get all of the objects having that value$/ do
+  @results.should == @all_objects.select {|x| x.color.value == @desired_color}
+end
+
+Then /^I should not get any objects having other values$/ do
+  @results.reject {|x| x.color.value == @desired_color}.should be_empty
+end

data/features/support/env.rb

@@ -0,0 +1,17 @@
+$LOAD_PATH << File.expand_path('../../../lib', __FILE__)
+require 'has_enumeration'
+
+ActiveRecord::Base.establish_connection(
+  :adapter => 'sqlite3',
+  :database => File.expand_path('../database', __FILE__)
+)
+
+class CreateTables < ActiveRecord::Migration
+  create_table :explicitly_mapped_models, :force => true do |t|
+    t.integer :color
+  end
+
+  create_table :implicitly_mapped_models, :force => true do |t|
+    t.string :color
+  end
+end

data/features/support/explicitly_mapped_model.rb

@@ -0,0 +1,3 @@
+class ExplicitlyMappedModel < ActiveRecord::Base
+  has_enumeration :color, :red => 1, :green => 2, :blue => 3
+end

data/features/support/implicitly_mapped_model.rb

@@ -0,0 +1,3 @@
+class ImplicitlyMappedModel < ActiveRecord::Base
+  has_enumeration :color, [:red, :green, :blue]
+end

data/lib/has_enumeration/aggregate_conditions_override.rb

@@ -0,0 +1,16 @@
+module HasEnumeration
+  module AggregateConditionsOverride
+    # Override the aggregate hash conditions behavior to coerce has_enumeration
+    # attributes that show up in finder options as symbols into instances of
+    # the aggregate class before hash expansion.
+    def expand_hash_conditions_for_aggregates(attrs)
+      expanded_attrs = attrs.dup
+      attr_enumeration_mapping_classes.each do |attr, klass|
+        if expanded_attrs[attr].is_a?(Symbol)
+          expanded_attrs[attr] = klass.from_sym(expanded_attrs[attr])
+        end
+      end
+      super(expanded_attrs)
+    end
+  end
+end

data/lib/has_enumeration/class_methods.rb

@@ -0,0 +1,67 @@
+module HasEnumeration
+  module ClassMethods
+    def has_enumeration(attribute, mapping)
+      unless mapping.is_a?(Hash)
+        # Recast the mapping as a symbol -> string hash
+        mapping_hash = {}
+        mapping.each {|m| mapping_hash[m] = m.to_s}
+        mapping = mapping_hash
+      end
+
+      # ActiveRecord's composed_of method will do most of the work for us.
+      # All we have to do is cons up a class that implements the bidirectional
+      # mapping described by the provided hash.
+      klass = create_enumeration_mapping_class(mapping)
+      attr_enumeration_mapping_classes[attribute] = klass
+
+      # Bind the class to a name within the scope of this class
+      attribute_name = attribute.to_s
+      mapping_class_name = attribute_name.camelize
+      const_set(mapping_class_name, klass)
+      scoped_class_name = [self.name, mapping_class_name].join('::')
+
+      composed_of(attribute,
+        :class_name => scoped_class_name,
+        :mapping => [attribute_name, 'raw_value'],
+        :converter => :from_sym
+      )
+
+      # Install our aggregate condition handling override, but only once
+      unless @aggregate_conditions_override_installed
+        extend HasEnumeration::AggregateConditionsOverride
+        @aggregate_conditions_override_installed = true
+      end
+    end
+
+  private
+    def attr_enumeration_mapping_classes
+      @attr_enumeration_mapping_classes ||= {}
+    end
+
+    def create_enumeration_mapping_class(mapping)
+      inverted_mapping = mapping.invert
+      Class.new do
+        attr_reader :raw_value, :value
+
+        define_method :initialize do |raw_value|
+          @raw_value = raw_value
+          @value = inverted_mapping[raw_value]
+        end
+
+        mapping.keys.each do |sym|
+          predicate = "#{sym}?".to_sym
+          value = mapping[sym]
+          define_method predicate do
+            @raw_value == value 
+          end
+        end
+
+        (class <<self;self;end).class_eval do
+          define_method :from_sym do |sym|
+            new(mapping[sym])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/has_enumeration.rb

@@ -0,0 +1,7 @@
+require 'active_record'
+
+require 'has_enumeration/class_methods'
+require 'has_enumeration/aggregate_conditions_override'
+
+# Install our class methods.
+ActiveRecord::Base.extend(HasEnumeration::ClassMethods)

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: has_enumeration
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Greg Spurrier
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-09 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: "    Extends ActiveRecord with the has_enumeration method that allows an\n    attribute to be declared as storing an enumeration.  The enumeration\n    is specified as a mapping between symbols and their underlying\n    representation in the database.  Predicates are provided for each\n    symbol in the enumeration and the symbols may be used in finder methods.\n"
+email: greg@rujubu.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.txt
+files: 
+- Gemfile
+- LICENSE.txt
+- README.txt
+- Rakefile
+- VERSION
+- features/explicitly_mapped_enumeration.feature
+- features/implicitly_mapped_enumeration.feature
+- features/step_definitions/has_enumeration_steps.rb
+- features/support/env.rb
+- features/support/explicitly_mapped_model.rb
+- features/support/implicitly_mapped_model.rb
+- lib/has_enumeration.rb
+- lib/has_enumeration/aggregate_conditions_override.rb
+- lib/has_enumeration/class_methods.rb
+has_rdoc: true
+homepage: http://github.com/gregspurrier/has_enumeration
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Support for symbol-based enumerations in ActiveRecord
+test_files: []
+