has_enumeration 0.5.0 → 1.0.0

data/Gemfile

@@ -3,12 +3,12 @@ source 'http://rubygems.org'
 if  ENV['AR_VERSION'] == '2.3'
   gem 'activerecord', '~> 2.3.8'
 else
-  gem 'activerecord', '= 3.0.0'
+  gem 'activerecord', '~> 3.0.1'
   gem 'meta_where'
 end
 
-gem 'rspec', '~> 2.0.0.beta.19'
-gem 'cucumber', '~> 0.8.5'
+gem 'rspec', '~> 2.0.1'
+gem 'cucumber', '~> 0.9.3'
 
 platforms :ruby do
   gem 'sqlite3-ruby', :require => 'sqlite3'

data/Gemfile.lock

@@ -1,52 +1,56 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activemodel (3.0.0)
-      activesupport (= 3.0.0)
+    activemodel (3.0.1)
+      activesupport (= 3.0.1)
       builder (~> 2.1.2)
       i18n (~> 0.4.1)
-    activerecord (3.0.0)
-      activemodel (= 3.0.0)
-      activesupport (= 3.0.0)
+    activerecord (3.0.1)
+      activemodel (= 3.0.1)
+      activesupport (= 3.0.1)
       arel (~> 1.0.0)
       tzinfo (~> 0.3.23)
     activerecord-jdbc-adapter (0.9.7-java)
     activerecord-jdbcsqlite3-adapter (0.9.7-java)
       activerecord-jdbc-adapter (= 0.9.7)
       jdbc-sqlite3 (>= 3.6.3.054)
-    activesupport (3.0.0)
+    activesupport (3.0.1)
     arel (1.0.1)
       activesupport (~> 3.0.0)
     builder (2.1.2)
-    cucumber (0.8.5)
+    cucumber (0.9.3)
       builder (~> 2.1.2)
       diff-lcs (~> 1.1.2)
-      gherkin (~> 2.1.4)
-      json_pure (~> 1.4.3)
-      term-ansicolor (~> 1.0.4)
+      gherkin (~> 2.2.9)
+      json (~> 1.4.6)
+      term-ansicolor (~> 1.0.5)
     diff-lcs (1.1.2)
-    gherkin (2.1.5)
-      trollop (~> 1.16.2)
-    gherkin (2.1.5-java)
-      trollop (~> 1.16.2)
-    i18n (0.4.1)
-    jdbc-sqlite3 (3.6.3.054)
-    json_pure (1.4.6)
-    meta_where (0.9.2)
-      activerecord (~> 3.0.0.rc2)
-      activesupport (~> 3.0.0.rc2)
-      arel (~> 1.0.0.rc1)
-    rspec (2.0.0.beta.20)
-      rspec-core (= 2.0.0.beta.20)
-      rspec-expectations (= 2.0.0.beta.20)
-      rspec-mocks (= 2.0.0.beta.20)
-    rspec-core (2.0.0.beta.20)
-    rspec-expectations (2.0.0.beta.20)
+    gherkin (2.2.9)
+      json (~> 1.4.6)
+      term-ansicolor (~> 1.0.5)
+    gherkin (2.2.9-java)
+      json (~> 1.4.6)
+      term-ansicolor (~> 1.0.5)
+    i18n (0.4.2)
+    jdbc-sqlite3 (3.6.14.2.056-java)
+    json (1.4.6)
+    json (1.4.6-java)
+    meta_where (0.9.6)
+      activerecord (~> 3.0.0)
+      activesupport (~> 3.0.0)
+      arel (~> 1.0.1)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
       diff-lcs (>= 1.1.2)
-    rspec-mocks (2.0.0.beta.20)
-    sqlite3-ruby (1.3.1)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+    sqlite3-ruby (1.3.2)
     term-ansicolor (1.0.5)
-    trollop (1.16.2)
     tzinfo (0.3.23)
 
 PLATFORMS
@@ -54,10 +58,10 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  activerecord (= 3.0.0)
+  activerecord (~> 3.0.1)
   activerecord-jdbcsqlite3-adapter (~> 0.9.7)
-  cucumber (~> 0.8.5)
+  cucumber (~> 0.9.3)
   jdbc-sqlite3
   meta_where
-  rspec (~> 2.0.0.beta.19)
+  rspec (~> 2.0.1)
   sqlite3-ruby

data/HISTORY.txt

@@ -1,3 +1,12 @@
+Version 1.0.0:
+- Added #to_sym for generated enumeration class.  #value is deprecated.
+- Raises ArgumentError when assigning, or querying, with a symbol that is
+  not part of the enumeration
+- A value of nil in underlying attribute results in a nil value for the
+  enumeration
+- Assigning nil to the enumeration results in a value of nil for the underlying
+  attribute
+
 Version 0.5.0:
 - Default name of underlying attribute can be overridden with the :attribute
   option

data/README.md

@@ -0,0 +1,125 @@
+# has_enumeration
+## Overview
+`has_enumeration` adds support for enumerated types to ActiveRecord. The values
+of an enumerated attribute are represented as symbols regardless of the
+attribute's underlying representation in the database. Predicates
+(e.g. `car.color.red?`) are provided for each value of the enumerated type.
+
+## Defining Enumerated Attributes
+Enumerated attributes are declared in the model's class definition with the
+`has_enumeration` class method.  For example:
+
+    class Car < ActiveRecord::Base
+      has_enumeration :color, [:red, :green, :blue]
+    end
+
+The above definition assumes that the `color` attribute is stored as a string
+and that its values in the database match those obtained by calling `to_s` on
+their corresponding symbols. I.e., :red is stored as 'red'.
+
+If the underlying column is not a string or its values do not match the string
+version of the enumeration's symbols, then the mapping between symbols and their
+underlying values may be provided as a hash:
+
+    class Car < ActiveRecord::Base
+      has_enumeration :color, :red => 1, :green => 2, :blue => 3
+    end
+
+By default, the underlying attribute is assumed to have the same name as the
+enumeration. If this is not the case, the name of the underlying attibute may
+be provided with the `:attribute` option:
+
+    class Car < ActiveRecord::Base
+      has_enumeration :color, {:red => 1, :green => 2, :blue => 3},
+        :attribute => :hue
+    end
+
+## Using Enumerated Attributes
+### Assignment
+Enumerated attributes are assigned using symbols:
+
+    car = Car.new(:color => :red)
+    car.color = :blue
+
+The symbols are coerced into an instance of a nested class (`Car::Color` in
+this example) that is created by `has_enumeration`. If for some reason you
+need to avoid the type coercion, you can assign a value of that class directly:
+
+    car.color = Car::Color.from_sym(:green)
+
+### Querying
+When constructing queries referencing the enumerated attribute, use the symbol
+as its value:
+
+    Car.find(:all, :conditions => {:color => :red})
+
+`has_enumeration` supports Rails 3 and is aware of the model's underlying Arel
+representation:
+
+    Car.where(:color => :red)
+    Car.where(Car.arel_table[:color].not_in([:red, :green]))
+
+If you are using MetaWhere, `has_enumeration` plays nicely with it:
+
+    # This example requires the meta_where:
+    Car.where(:color.not_in => [:red, :green])
+
+### Testing Values
+The primary means of interacting with enumerated attributes is through the
+predicate methods that are automatically generated for each value in the
+enumeration:
+
+    car = Car.new(:color => :red)
+    car.color.red?
+    # => true
+    car.color.green?
+    # => false
+
+If the value of the attribute is needed as a symbol, e.g., for direct
+comparison, it can be retrieved with `to_sym`:
+
+    car.color.to_sym
+    # => :red
+
+## Installation
+`has_enumeration` is packaged as a gem:
+
+    gem install has_enumeration
+
+### Rails 3
+To use `has_enumeration` with Rails 3, simply add it to your application's
+Gemfile:
+
+    gem 'has_enumeration'
+
+### Rails 2.x
+To use `has_enumeration` with Rails 2, add it to your application's
+environment.rb file:
+
+    config.gem 'has_enumeration'
+
+## Supported Configurations
+`has_enumeration` has been tested with the following versions of ActiveRecord:
+
+* 2.3.10
+* 3.0.1
+
+and the following Ruby implementations:
+
+* 1.8.7-p302
+* 1.9.2-p0
+* JRuby 1.5.3
+* Rubinius 1.1.0
+
+
+## Getting the Latest
+`has_enumeration` is hosted on github at
+[http://github.com/gregspurrier/has_enumeration](http://github.com/gregspurrier/has_enumeration).
+
+You can make a local clone of the repository with the following command:
+
+    git clone git://github.com/gregspurrier/has_enumeration.git
+
+## License
+`has_enumeration` is Copyright 2010 by Greg Spurrier. It is released under
+the MIT License. Please see LICENSE.txt for details.

data/Rakefile

@@ -1,6 +1,9 @@
 require 'rubygems'
 require 'cucumber'
 require 'cucumber/rake/task'
+require 'rspec'
+require 'rspec/core/rake_task'
+
 
 begin
   require 'jeweler'
@@ -15,7 +18,8 @@ in the database.  Predicates are provided for each symbol in the enumeration
 and the symbols may be used in finder methods.  When using ActiveRecord 3,
 the symbols may also be used when interacting with the underlying Arel attribute
 for the enumeration.  has_enumeration has been tested with Ruby 1.8.7,
-Ruby 1.9.2, JRuby 1.5.3, ActiveRecord 2.3.9, and ActiveRecord 3.0.0.
+Ruby 1.9.2, JRuby 1.5.3, Rubinius 1.1.0, ActiveRecord 2.3.10, and ActiveRecord
+3.0.1.
 EOF
     gemspec.email = "greg@rujubu.com"
     gemspec.homepage = "http://github.com/gregspurrier/has_enumeration"
@@ -43,3 +47,6 @@ namespace :features do
     t.cucumber_opts = feature_files
   end
 end
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new('spec')

data/VERSION

@@ -1 +1 @@
-0.5.0
+1.0.0

data/features/step_definitions/has_enumeration_steps.rb

@@ -25,7 +25,7 @@ When /^I save and reload the object$/ do
 end
 
 Then /^it should have the assigned value as its value$/ do
-  @object.color.value.should == @assigned
+  @object.color.to_sym.should == @assigned
 end
 
 Then /^the ([a-z_]+\?) predicate should be (true|false)$/ do |predicate, value|
@@ -65,9 +65,9 @@ When /^I query for objects with the value :([a-z_]+) via MetaWhere$/ do |value|
 end
 
 Then /^I should get all of the objects having that value$/ do
-  @results.should == @all_objects.select {|x| x.color.value == @desired_color}
+  @results.should == @all_objects.select {|x| x.color.to_sym == @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
+  @results.reject {|x| x.color.to_sym == @desired_color}.should be_empty
 end

data/lib/has_enumeration/arel/table_extensions.rb

@@ -32,6 +32,11 @@ module HasEnumeration
         (class <<arel_attr;self;end).class_eval do
           define_method :map_enumeration_arg do |arg|
             if arg.is_a?(Symbol)
+              unless mapping.has_key?(arg)
+                raise ArgumentError.new(
+                  "#{arg.inspect} is not one of {#{mapping.keys.map(&:inspect).sort.join(', ')}}"
+                )
+              end
               mapping[arg]
             elsif arg.is_a?(Array)
               arg.map {|a| map_enumeration_arg(a)}

data/lib/has_enumeration/class_methods.rb

@@ -1,5 +1,26 @@
 module HasEnumeration
   module ClassMethods
+    # Declares an enumerated attribute called +enumeration+ consisting of
+    # the symbols defined in +mapping+.
+    #
+    # When the database representation of the attribute is a string, +mapping+
+    # can be an array of symbols. The string representation of the symbol
+    # will be stored in the databased.  E.g.:
+    #
+    #   has_enumeration :color, [:red, :green, :blue]
+    #
+    # When the database representation of the attribute is not a string, or
+    # if its values do not match up with the string versions of its symbols,
+    # an hash mapping symbols to their underlying values may be used:
+    #
+    #   has_enumeration :color, :red => 1, :green => 2, :blue => 3
+    #
+    # By default, has_enumeration assumes that the column in the database
+    # has the same name as the enumeration.  If this is not the case, the
+    # column can be specified with the :attribute option:
+    #
+    #   has_enumeration :color, [:red, :green, :blue], :attribute => :hue
+    #
     def has_enumeration(enumeration, mapping, options = {})
       unless mapping.is_a?(Hash)
         # Recast the mapping as a symbol -> string hash
@@ -25,7 +46,8 @@ module HasEnumeration
       composed_of(enumeration,
         :class_name => scoped_class_name,
         :mapping => [attribute.to_s, 'raw_value'],
-        :converter => :from_sym
+        :converter => :from_sym,
+        :allow_nil => true
       )
 
       if ActiveRecord::VERSION::MAJOR >= 3
@@ -49,13 +71,22 @@ module HasEnumeration
     def create_enumeration_mapping_class(mapping)
       inverted_mapping = mapping.invert
       Class.new do
-        attr_reader :raw_value, :value
+        attr_reader :raw_value
 
         define_method :initialize do |raw_value|
           @raw_value = raw_value
           @value = inverted_mapping[raw_value]
         end
 
+        define_method :to_sym do
+          @value
+        end
+
+        define_method :value do
+          puts "#{self.class.name}#value is deprecated. Use #to_sym instead. (#{caller[0]})"
+          to_sym
+        end
+
         mapping.keys.each do |sym|
           predicate = "#{sym}?".to_sym
           value = mapping[sym]
@@ -66,6 +97,11 @@ module HasEnumeration
 
         (class <<self;self;end).class_eval do
           define_method :from_sym do |sym|
+            unless mapping.has_key?(sym)
+              raise ArgumentError.new(
+                "#{sym.inspect} is not one of {#{mapping.keys.map(&:inspect).sort.join(', ')}}"
+              )
+            end
             new(mapping[sym])
           end
         end

data/spec/has_enumeration/has_enumeration_spec.rb

@@ -0,0 +1,67 @@
+require File.expand_path('../spec_helper', File.dirname(__FILE__))
+
+describe HasEnumeration, 'with invalid values' do
+  before(:each) do
+    @model = ExplicitlyMappedModel.new
+  end
+
+  it 'raises an exception when assigned an invalid value' do
+    lambda do
+      @model.color = :beige
+    end.should raise_error(ArgumentError, ':beige is not one of {:blue, :green, :red}')
+  end
+
+  if ActiveRecord::VERSION::MAJOR >= 3
+    context 'with ActiveRecord 3.x' do
+      it 'raises an exception when finding with an invalid value' do
+        lambda do
+          ExplicitlyMappedModel.where(:color => :beige).all
+        end.should raise_error(ArgumentError, ':beige is not one of {:blue, :green, :red}')
+      end
+
+      it 'raises an exception when finding with an invalid value via meta_where' do
+        lambda do
+          ExplicitlyMappedModel.where(:color.not_eq => :beige).all
+        end.should raise_error(ArgumentError, ':beige is not one of {:blue, :green, :red}')
+      end
+    end
+  else
+    context 'With ActiveRecord 2.x' do
+      it 'raises an exception when finding with an invalid value' do
+        lambda do
+          ExplicitlyMappedModel.find(:all, :conditions => {:color => :beige})
+        end.should raise_error(ArgumentError, ':beige is not one of {:blue, :green, :red}')
+      end
+    end
+  end
+end
+
+describe HasEnumeration, 'with an uninitialied value' do
+  context 'in a newly-created object' do
+    it 'returns nil for the value of the enumeration' do
+      ExplicitlyMappedModel.new.color.should be_nil
+    end
+  end
+
+  context 'in an existing object' do
+    it 'returns nil for the value of the enumeration' do
+      object = ExplicitlyMappedModel.find(ExplicitlyMappedModel.create!.id)
+      object.color.should be_nil
+    end
+  end
+end
+
+describe HasEnumeration, 'assignment of nil' do
+  it 'sets the enumeration to nil' do
+    object = ExplicitlyMappedModel.new(:color => :red)
+    object.color = nil
+    object.color.should be_nil
+  end
+
+  it 'persists across a trip to the database' do
+    object = ExplicitlyMappedModel.create!(:color => :red)
+    object.color = nil
+    object.save!
+    ExplicitlyMappedModel.find(object.id).color.should be_nil
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+ENV['AR_VERSION'] ||= '3.0'
+
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec'
+
+require File.expand_path('../lib/has_enumeration', File.dirname(__FILE__))
+require File.expand_path('../features/support/explicitly_mapped_model', File.dirname(__FILE__))
+
+ActiveRecord::Base.establish_connection(
+  :adapter => defined?(JRUBY_VERSION) ? 'jdbcsqlite3': 'sqlite3',
+  :database => File.expand_path('../database', __FILE__)
+)
+
+if ActiveRecord::VERSION::MAJOR >= 3
+  require 'meta_where'
+end
+
+class CreateTables < ActiveRecord::Migration
+  create_table :explicitly_mapped_models, :force => true do |t|
+    t.integer :color
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: has_enumeration
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 23
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 5
   - 0
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Greg Spurrier
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-05 00:00:00 -07:00
+date: 2010-11-07 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -27,7 +27,8 @@ description: |
   and the symbols may be used in finder methods.  When using ActiveRecord 3,
   the symbols may also be used when interacting with the underlying Arel attribute
   for the enumeration.  has_enumeration has been tested with Ruby 1.8.7,
-  Ruby 1.9.2, JRuby 1.5.3, ActiveRecord 2.3.9, and ActiveRecord 3.0.0.
+  Ruby 1.9.2, JRuby 1.5.3, Rubinius 1.1.0, ActiveRecord 2.3.10, and ActiveRecord
+  3.0.1.
 
 email: greg@rujubu.com
 executables: []
@@ -36,16 +37,14 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE.txt
-- README.txt
-- TODO
+- README.md
 files: 
 - Gemfile
 - Gemfile.lock
 - HISTORY.txt
 - LICENSE.txt
-- README.txt
+- README.md
 - Rakefile
-- TODO
 - VERSION
 - features/arel_attributes.feature
 - features/explicitly_mapped_enumeration.feature
@@ -61,6 +60,8 @@ files:
 - lib/has_enumeration/aggregate_conditions_override.rb
 - lib/has_enumeration/arel/table_extensions.rb
 - lib/has_enumeration/class_methods.rb
+- spec/has_enumeration/has_enumeration_spec.rb
+- spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/gregspurrier/has_enumeration
 licenses: []
@@ -95,5 +96,6 @@ rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Support for symbol-based enumerations in ActiveRecord
-test_files: []
-
+test_files: 
+- spec/has_enumeration/has_enumeration_spec.rb
+- spec/spec_helper.rb

data/README.txt

@@ -1,53 +0,0 @@
-== 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]
-
-  # Attribute with a name other than the enumeration's name
-  # has_enumeration :color, {:red => 1, :green => 2, :blue => 3},
-  #   :attribute => :hue
-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)
-
-# Querying with arel predicates (ActiveRecord 3 only)
-attr = TestObject.arel_table[:color]
-TestObject.where(attr.not_in([:red, :green]))
-
-# Querying with MetaWhere (ActiveRecord 3 only, with MetaWhere gem)
-TestObject.where(:color.not_in => [:red, :green])
-
-== Installation
-gem install has_enumeration
-
-== 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 all combinations for the following:
-
-  Rubies:
-    - 1.8.7-p302
-    - 1.9.2-p0
-    - JRuby 1.5.3
-  ActiveRecord:
-    - 2.3.9
-    - 3.0.0

data/TODO

@@ -1,5 +0,0 @@
-Prior to 1.0.0:
-- Raise exception when assigning an invalid value (?)
-- Configurable support for nil
-- rdoc documentation for has_enumeration
-- Rake task to automate testing the supported Rubies and ActiveRecord versions