enumerated_field 0.0.1 → 0.0.3

data/README.md

@@ -0,0 +1,94 @@
+EnumeratedField is a library that provides some nice methods when a string column is used like an enumeration, meaning there is a list of allowable values for the string column. Typically you want the display value as seen by the end user to differ from the stored value, allowing you to easily change the display value at anytime without migrating data, and this little gem helps you with that.
+
+## Usage
+
+    enum_field(field_name, choices, options = {})
+
+Available options are:
+
+* `:validate`, whether to validate that the value is in the given list
+  of choices. Defaults to true.
+* `:allow_nil`, whether a nil value passes validation. Defaults to
+  false.
+* `:allow_blank`, whether a blank (nil, "") value passes validation.
+  Defaults to false.
+
+The default validation uses ActiveModel's inclusion validations. If using on a
+class without ActiveModel use `:validate => false` to disable
+these.
+
+## Example
+
+    class Hike < ActiveRecord::Base
+      include EnumeratedField
+
+      # default form
+      enum_field :duration, [
+        ['Short', 'short'],
+        ['Really, really long', 'long']
+      ]
+      # disable default validation
+      enum_field :trail, [
+        ['Pacific Crest Trail', 'pct'],
+        ['Continental Divide Trail', 'cdt'],
+        ['Superior Hiking Trail', 'sht']
+      ], :validate => false
+    end
+
+    > hike = Hike.create(:trail => 'pct', :duration => 'long')
+
+### Confirm Values
+
+    > hike.trail_sht?
+    => false
+
+    > hike.trail_pct?
+    => true
+
+    > hike.duration_long?
+    => true
+
+    > hike.duration_short?
+    => false
+
+### Display Selected Value
+
+    > hike.trail_display
+    => "Pacific Crest Trail"
+
+    > hike.duration_display
+    => "Really, really long"
+
+### Validation
+
+    > hike.valid?
+    => true
+
+    > hike.duration = 'forever'
+    > hike.valid?
+    => false
+
+### List Available Values
+
+    > hike.trail_values # useful to provide to options_for_select when constructing forms
+    => [['Pacific Crest Trail', 'pct'], ['Continental Divide Trail', 'cdt'], ['Superior Hiking Trail', 'sht']]
+    > Hike.trail_values # or get it from the class instead of the instance, if you like
+    => [['Pacific Crest Trail', 'pct'], ['Continental Divide Trail', 'cdt'], ['Superior Hiking Trail', 'sht']]
+
+### Use Constants for Keys
+
+    > Hike::TRAIL_PCT
+    => :pct
+    > Hike::TRAIL_SHT
+    => :sht
+
+These methods are all prefixed with the field name by design, which allows multiple fields on a model to exist which potentially have the same values.
+
+## TESTS
+
+Run tests with `bundle exec rake test` (or just `rake test` if you're
+daring).
+
+## TODO
+
+* Provide any support needed for defining columns on MySQL databases as enum columns instead of string columns.

data/Rakefile

@@ -1,2 +1,10 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.test_files = FileList['test/*_test.rb']
+  test.verbose = true
+  # test.warning = true
+end

data/enumerated_field.gemspec

@@ -18,4 +18,11 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
+
+  s.add_dependency('activemodel')
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'turn'
+  s.add_development_dependency 'shoulda'
 end

data/lib/enumerated_field/version.rb

@@ -1,3 +1,3 @@
 module EnumeratedField
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/lib/enumerated_field.rb

@@ -9,14 +9,20 @@ module EnumeratedField
     # ex. enum_field(:league, [['National Football League', :nfl], ['Major League Baseball', :mlb]])
     # field_name typically corresponds to the database column name
     # values_array is a double array (not a hash to preserve order for when order matters.. ie select options)    
-    def enum_field(field_name, values_array)
+    def enum_field(field_name, values_array, options = {})
       values_hash = {}
       values_array.each { |value, key| values_hash[key] = value }
-      
-      class_eval do
+      default_options = {
+        :validate => true,
+        :allow_nil => false,
+        :allow_blank => false,
+      }
+      options = default_options.merge(options)
 
-        # returns the values_array for this field, useful for providing to 
-        # options_for_select when constructing forms
+      # returns the values_array for this field, useful for providing to
+      # options_for_select when constructing forms
+      enumerated_class = class << self; self; end
+      enumerated_class.instance_eval do
         define_method("#{field_name}_values") do |*options|
           options = options.first || {}
           if options[:first_option]
@@ -25,6 +31,23 @@ module EnumeratedField
             values_array
           end
         end
+      end
+
+      class_eval do
+
+        unless options[:validate] == false
+          validates field_name, :inclusion => values_hash.keys,
+            :allow_nil => options[:allow_nil], :allow_blank => options[:allow_blank]
+        end
+
+        values_hash.each do |key, value|
+          const_name = "#{field_name}_#{key}".upcase.gsub(/[^\w_]/, "_").to_sym
+          const_set(const_name, key)
+        end
+
+        define_method("#{field_name}_values") do |*options|
+          self.class.send("#{field_name}_values", *options)
+        end
 
         # returns display value for the current value of the field
         define_method("#{field_name}_display") do
@@ -35,7 +58,7 @@ module EnumeratedField
         define_method("#{field_name}_display_for") do |key|
           values_hash[key]
         end
-        
+
         define_method("#{field_name}_value_for") do |key|
           values_hash.invert[key]
         end
@@ -51,6 +74,6 @@ module EnumeratedField
     end
 
   end
-  
+
 end
 

data/test/enumerated_field_test.rb

@@ -5,50 +5,127 @@ class Apple
 
   attr_accessor :color, :kind
   
-  enum_field :color, [['Red', :red], ['Green', :green]]
-  enum_field :kind, [['Fuji Apple', :fuji], ['Delicious Red Apple', :delicious]]
+  enum_field :color, [['Red', :red], ['Green', :green]], :validate => false
+  enum_field :kind, [['Fuji Apple', :fuji], ['Delicious Red Apple', :delicious]], :validate => false
 
   def initialize(color, kind)
     self.color = color
     self.kind = kind
   end
-  
+
 end
 
-class EnumeratedFieldTest < Test::Unit::TestCase
+class Banana
+  include EnumeratedField
+  include ActiveModel::Validations
 
-  def test_color_display
-    apple = Apple.new(:red, :fuji)
-    assert apple.color_display, 'Red'
-  end
+  attr_accessor :brand
+  attr_accessor :color
+  attr_accessor :tastiness
 
-  def test_color_display_for
-    apple = Apple.new(:red, :fuji)
-    assert apple.color_display_for(:green), 'Green'    
-  end
+  enum_field :brand, [["Chiquita", :chiquita], ["Del Monte", :delmonte]]
+  enum_field :color, [["Awesome Yellow", :yellow], ["Icky Green", :green]], :allow_nil => true
+  # stressing the constantizing of the keys
+  enum_field :tastiness, [
+    ["Great", "great!"],
+    ["Good", "it's good"],
+    ["Bad", "hate-hate"],
+  ], :validate => false
 
-  def test_two_enum_fields_in_one_class
-    apple = Apple.new(:green, :delicious)
-    assert apple.color_display, 'Green'
-    assert apple.kind_display, 'Delicious Red Apple'
+  def initialize(brand, color)
+    self.brand = brand
+    self.color = color
   end
+end
 
-  def test_question_methods
-    apple = Apple.new(:green, :delicious)
-    assert apple.color_green?
-    assert !apple.color_red?
-    assert apple.kind_delicious?
-    assert !apple.kind_fuji?
-  end
+class EnumeratedFieldTest < Test::Unit::TestCase
+
+  context 'EnumeratedField class' do
+
+    should 'have the color_values method' do
+      assert_equal Apple.color_values.length, 2
+    end
+
+    should 'have 2 values without first option' do
+      assert_equal Apple.color_values.length, 2
+    end
+
+    should 'have 3 values with first option' do
+      assert_equal Apple.color_values(:first_option => "Select Color").length, 3
+    end
 
-  def test_values_without_first_option
-    apple = Apple.new(:red, :fuji)
-    assert apple.color_values.length, 2
+    should 'create contstants for the field keys' do
+      assert_equal :chiquita, Banana::BRAND_CHIQUITA
+      assert_equal :delmonte, Banana::BRAND_DELMONTE
+    end
+
+    should 'create underscored constants from field keys which contain invalid constant name characters' do
+      assert_equal "great!", Banana::TASTINESS_GREAT_
+      assert_equal "it's good", Banana::TASTINESS_IT_S_GOOD
+      assert_equal "hate-hate", Banana::TASTINESS_HATE_HATE
+    end
   end
 
-  def test_values_with_first_option
-    apple = Apple.new(:red, :fuji)
-    assert apple.color_values(:first_option => "Select Color").length, 3
+  context 'EnumeratedField instance' do
+
+    setup do
+      @red_apple = Apple.new(:red, :fuji)
+      @green_apple = Apple.new(:green, :delicious)
+    end
+
+    should 'have color_display method' do
+      assert_equal @red_apple.color_display, 'Red'
+    end
+
+    should 'show Green for color_display of green' do
+      assert_equal @red_apple.color_display_for(:green), 'Green'
+    end
+
+    should 'have two enum fields in one class' do
+      assert_equal @green_apple.color_display, 'Green'
+      assert_equal @green_apple.kind_display, 'Delicious Red Apple'
+    end
+
+    should 'have valid question methods' do
+      assert @green_apple.color_green?
+      assert !@green_apple.color_red?
+      assert @green_apple.kind_delicious?
+      assert !@green_apple.kind_fuji?
+    end
+
+    should 'have 2 values without first option' do
+      assert_equal @red_apple.color_values.length, 2
+    end
+
+    should 'have 3 values with first option' do
+      assert_equal @red_apple.color_values(:first_option => "Select Color").length, 3
+    end
+
   end
 
-end
+  context 'Validation' do
+    should 'occur by default' do
+      # valid choice
+      banana = Banana.new(:chiquita, :green)
+      assert banana.valid?
+
+      # invalid choice
+      bad_banana = Banana.new(:penzoil, :orange)
+      assert !bad_banana.valid?
+      assert_equal ["is not included in the list"], bad_banana.errors[:brand]
+      assert_equal ["is not included in the list"], bad_banana.errors[:color]
+
+      # invalid choice (brand doesn't allow nil, color does)
+      nil_banana = Banana.new(nil, nil)
+      assert !nil_banana.valid?
+      assert_equal ["is not included in the list"], nil_banana.errors[:brand]
+      assert_equal [], nil_banana.errors[:color]
+    end
+
+    should 'not occur if passed :validate => false' do
+      # no validations, accepts any choice
+      apple = Apple.new(:orange, :macintosh)
+      assert !apple.respond_to?(:valid)
+    end
+  end
+end

data/test/test_helper.rb

@@ -1,2 +1,5 @@
-require "test/unit"
-require "lib/enumerated_field"
+require 'test/unit'
+require 'turn'
+require 'shoulda'
+require 'lib/enumerated_field'
+require "active_model"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: enumerated_field
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Luke Ludwig
@@ -15,10 +15,79 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-21 00:00:00 -05:00
+date: 2011-07-20 00:00:00 -05:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: activemodel
+  type: :runtime
+  prerelease: false
+  requirement: *id001
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: rake
+  type: :development
+  prerelease: false
+  requirement: *id002
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: bundler
+  type: :development
+  prerelease: false
+  requirement: *id003
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: turn
+  type: :development
+  prerelease: false
+  requirement: *id004
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: shoulda
+  type: :development
+  prerelease: false
+  requirement: *id005
 description: EnumeratedField is a library that provides some nice methods when a string column is used like an enumeration, meaning there is a list of allowable values for the string column.
 email: 
 - luke.ludwig@tstmedia.com
@@ -31,7 +100,7 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
-- README
+- README.md
 - Rakefile
 - enumerated_field.gemspec
 - lib/enumerated_field.rb

data/README

@@ -1,37 +0,0 @@
-EnumeratedField is a library that provides some nice methods when a string column is used like an enumeration, meaning there is a list of allowable values for the string column. Typically you want the display value as seen by the end user to differ from the stored value, allowing you to easily change the display value at anytime without migrating data, and this little gem helps you with that.
-
-Example Usage:
-This example demonstrates usage within an ActiveRecord::Base object, however this gem does not depend on ActiveRecord.
-
-class Hike < ActiveRecord::Base
-   
-  include EnumeratedField
-  
-  enum_field :trail, [['Pacific Crest Trail', 'pct'],
-                      ['Continental Divide Trail', 'cdt'],
-                      ['Superior Hiking Trail', 'sht']]
-
-end
-
-> hike = Hike.create(:trail => 'pct')
-
-> hike.trail_sht?
-=> false
-
-> hike.trail_pct?
-=> true
-
-> hike.trail_display
-=> "Pacific Crest Trail"
-
-> hike.trail_values   # useful to provide to options_for_select when constructing forms
-=> [['Pacific Crest Trail', 'pct'], ['Continental Divide Trail', 'cdt'], ['Superior Hiking Trail', 'sht']]
-
-
-These methods are all prefixed with the field name by design, which allows multiple fields on a model to exist which potentially have the same values.
-
-Run tests by:  ruby test/enumerated_field_test.rb
-
-TODO:
-* Provide option to enum_field to setup validation methods that validate the value of the field against the allowed values.
-* Provide any support needed for defining columns on MySQL databases as enum columns instead of string columns.