lwe-simple_enum 0.3.0

data/lib/simple_enum/array_support.rb

@@ -0,0 +1,15 @@
+module SimpleEnum
+  module ArraySupport
+    
+    # Magically convert an array to a hash, has some neat features
+    # for active record models and similar.
+    #
+    # TODO: add more documentation; allow block to be passed to customize key/value pairs
+    def to_hash_magic
+      v = enum_with_index.to_a unless first.is_a?(ActiveRecord::Base) or first.is_a?(Array)
+      v = map { |e| [e, e.id] } if first.is_a?(ActiveRecord::Base)
+      v ||= self
+      Hash[*v.flatten]
+    end
+  end
+end

data/lib/simple_enum/enum_hash.rb

@@ -0,0 +1,36 @@
+module SimpleEnum
+  
+  # Internal hash class, used to handle the enumerations et al.
+  # Works like to original +Hash+ class, but with some added value,
+  # like access to 
+  #
+  # 
+  class EnumHash < ::Hash
+    def initialize(hsh)
+      hsh = hsh.to_hash_magic unless hsh.is_a?(Hash)
+      
+      @reverse_sym_lookup = {}
+      @sym_value_lookup = {}
+      
+      hsh.each do |k,v|
+        sym = k.to_enum_sym
+        self[k] = v
+        @reverse_sym_lookup[sym] = k
+        @sym_value_lookup[sym] = v
+      end
+    end
+    
+    def default(k = nil)
+      @sym_value_lookup[k.to_enum_sym] if k
+    end
+        
+    def method_missing(symbol, *args)
+      if @sym_value_lookup.has_key?(symbol.to_enum_sym)
+        return @reverse_sym_lookup[symbol.to_enum_sym] if args.first
+        self[symbol]
+      else
+        super
+      end
+    end
+  end
+end

data/lib/simple_enum/object_support.rb

@@ -0,0 +1,37 @@
+module SimpleEnum
+  module ObjectSupport
+    
+    # Convert object to symbol for use in symbolized enum
+    # methods. Return value is supposed to be a symbol,
+    # though strings should work as well.
+    #
+    # The default behaviour is to try +to_sym+ first, then
+    # checks if a field named +name+ exists or finally falls
+    # back to +to_param+ method as provided by ActiveSupport.
+    #
+    # It's perfectly for subclasses to override this method,
+    # to provide custom +to_enum_sym+ behaviour, e.g. if
+    # the symbolized value is in e.g. +title+:
+    #
+    #    class FormOfAddress < ActiveRecord::Base
+    #      attr_accessor :title
+    #      def to_enum_sym; title; end
+    #    end
+    #
+    # *Note*: to provide better looking methods values for +name+
+    # are <tt>parametereize('_')</tt>'d, so it might be a good idea to do
+    # the same thing in a custom +to_enum_sym+ method, like (for the
+    # example above):
+    #
+    #    def to_enum_sym; title.parameterize('_').to_sym; end
+    #
+    # *TODO*: The current implementation does not handle nil values very
+    # gracefully, so if +name+ returns +nil+, it should be handled
+    # a bit better I suppose...
+    def to_enum_sym
+      return to_sym if respond_to?(:to_sym)
+      return name.to_s.parameterize('_').to_sym if respond_to?(:name)
+      to_param.to_sym unless blank? # fallback, unless empty...
+    end
+  end
+end

data/lib/simple_enum/validation.rb

@@ -0,0 +1,37 @@
+module SimpleEnum
+  module Validation
+    
+    # Validates an +as_enum+ field based on the value of it's column.
+    #
+    # Model:
+    #    class User < ActiveRecord::Base
+    #      as_enum :gender, [ :male, :female ]
+    #      validates_as_enum :gender
+    #    end
+    #
+    # View:
+    #    <%= select(:user, :gender, User.genders.keys) %>
+    #
+    # Configuration options:
+    # * <tt>:message</tt> - A custom error message (default: is <tt>[:activerecord, :errors, :messages, :invalid_enum]</tt>).
+    # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+    # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+    #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
+    #   method, proc or string should return or evaluate to a true or false value.
+    # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+    #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
+    #   method, proc or string should return or evaluate to a true or false value.
+    def validates_as_enum(*attr_names)
+      configuration = { :on => :save }
+      configuration.update(attr_names.extract_options!)      
+      attr_names.map! { |e| enum_definitions[e][:column] } # map to column name
+      
+      validates_each(attr_names, configuration) do |record, attr_name, value|
+        enum_def = enum_definitions[attr_name]
+        unless send(enum_def[:name].to_s.pluralize).values.include?(value)
+          record.errors.add(enum_def[:name], :invalid_enum, :default => configuration[:message], :value => value)
+        end
+      end
+    end    
+  end
+end

data/lib/simple_enum/version.rb

@@ -0,0 +1,14 @@
+module SimpleEnum
+  module Version #:nodoc:
+    MAJOR = 0
+    MINOR = 5
+    TINY = 0
+    
+    STRING = [MAJOR, MINOR, TINY].join('.').freeze
+    
+    def self.to_s; STRING; end
+  end
+  
+  NAME = "simple_enum".freeze
+  ABOUT = "#{NAME} #{Version}".freeze
+end

data/locales/en.yml

@@ -0,0 +1,6 @@
+# english translation
+en:
+  activerecord:
+    errors:
+      messages:
+        invalid_enum: invalid option supplied.

data/simple_enum.gemspec

@@ -0,0 +1,72 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{simple_enum}
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Lukas Westermann"]
+  s.date = %q{2009-07-07}
+  s.email = %q{lukas.westermann@gmail.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENCE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION.yml",
+     "init.rb",
+     "lib/simple_enum.rb",
+     "lib/simple_enum/array_support.rb",
+     "lib/simple_enum/enum_hash.rb",
+     "lib/simple_enum/object_support.rb",
+     "lib/simple_enum/validation.rb",
+     "lib/simple_enum/version.rb",
+     "locales/en.yml",
+     "simple_enum.gemspec",
+     "test/array_conversions_test.rb",
+     "test/class_methods_test.rb",
+     "test/enum_hash_test.rb",
+     "test/finders_test.rb",
+     "test/models.rb",
+     "test/object_backed_test.rb",
+     "test/object_support_test.rb",
+     "test/prefixes_test.rb",
+     "test/se_array_support_test.rb",
+     "test/simple_enum_test.rb",
+     "test/test_helper.rb",
+     "test/without_shortcuts_test.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/lwe/simple_enum}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.2}
+  s.summary = %q{Simple enum-like field support for ActiveRecord (including validations and i18n)}
+  s.test_files = [
+    "test/array_conversions_test.rb",
+     "test/class_methods_test.rb",
+     "test/enum_hash_test.rb",
+     "test/finders_test.rb",
+     "test/models.rb",
+     "test/object_backed_test.rb",
+     "test/object_support_test.rb",
+     "test/prefixes_test.rb",
+     "test/se_array_support_test.rb",
+     "test/simple_enum_test.rb",
+     "test/test_helper.rb",
+     "test/without_shortcuts_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/test/array_conversions_test.rb

@@ -0,0 +1,22 @@
+require 'test_helper'
+
+class ArrayConversionsTest < ActiveSupport::TestCase  
+  def setup
+    reload_db :genders => true
+  end
+  
+  test "that conversion of Gender.find(:all).map {...} to enumeration values as symbols works the same as [:male,:female]" do
+    with_enum = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'
+      as_enum :gender, Gender.find(:all).map { |g| [g.name.to_sym, g.id] }
+    end
+    
+    assert_equal 0, with_enum.male
+    assert_equal 1, with_enum.female
+    assert_equal 1, with_enum.genders(:female)
+    
+    jane = with_enum.new :gender => :female
+    assert_equal :female, jane.gender
+    assert_equal 1, jane.gender_cd    
+  end
+end

data/test/class_methods_test.rb

@@ -0,0 +1,108 @@
+require 'test_helper'
+
+class ClassMethodsTest < ActiveSupport::TestCase  
+  def setup
+    reload_db
+  end
+
+  test "that Klass.genders[:sym] == Klass.genders(:sym)" do
+    assert_equal 0, Dummy.genders(:male)
+    assert_equal Dummy.genders(:male), Dummy.genders[:male]
+    assert_nil Dummy.genders(:inexistent)
+    assert_nil Dummy.genders[:inexistent]
+  end
+  
+  test "that inst.values_for_... is deprecated (by trapping Kernel\#warn)" do
+    # ensure that warn() is trapped
+    trapped_warn_dummy = Class.new(Dummy) do
+      @@LAST_WARNING = nil
+      def warn(msg); @@LAST_WARNING = msg; end;
+      def self.last_warning; @@LAST_WARNING; end      
+    end
+    
+    g = trapped_warn_dummy.new
+    g.values_for_gender
+    
+    assert_match /\ADEPRECATION WARNING.*values_for_gender.*genders/, trapped_warn_dummy.last_warning
+  end
+  
+  test "generation of value shortcuts on class" do
+    g = Dummy.new
+    
+    assert_equal 0, Dummy.male
+    assert_equal 1, Dummy.female
+    assert_equal 'alpha', Dummy.alpha
+    assert_respond_to Dummy, :male
+    assert_respond_to Dummy, :female
+    assert_respond_to Dummy, :beta
+    assert_respond_to Dummy, :foobar            
+  end
+  
+  test "that no Klass.shortcut are created if :slim => true" do
+    with_slim = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'
+      as_enum :gender, [:male, :female], :slim => true
+    end
+
+    assert !with_slim.respond_to?(:male)
+    assert !with_slim.respond_to?(:female)    
+    assert_respond_to with_slim, :genders
+  end
+  
+  test "that no Klass.shortcut's are created if :slim => :class, though instance shortcuts are" do
+    with_slim_class = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'
+      as_enum :gender, [:male, :female], :slim => :class
+    end
+
+    jane = with_slim_class.new
+    
+    assert_respond_to jane, :male!
+    assert_respond_to jane, :female!
+    assert !with_slim_class.respond_to?(:male)
+    assert !with_slim_class.respond_to?(:female)    
+    assert_respond_to with_slim_class, :genders
+    assert_same 0, with_slim_class.genders.male
+    assert_same 1, with_slim_class.genders[:female]
+  end
+  
+  test "that Klass.shortcut respect :prefix => true and are prefixed by \#{enum_cd}" do
+    with_prefix = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'
+      as_enum :gender, [:male, :female], :prefix => true
+    end
+    
+    assert !with_prefix.respond_to?(:male)
+    assert !with_prefix.respond_to?(:female)    
+    assert_respond_to with_prefix, :gender_male
+    assert_respond_to with_prefix, :gender_female
+    assert_equal 0, with_prefix.gender_male
+    assert_respond_to with_prefix, :genders
+  end
+  
+  test "to ensure that Klass.shortcut also work with custom prefixes" do
+    with_custom_prefix = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'
+      as_enum :gender, [:male, :female], :prefix => :g
+    end
+    
+    assert !with_custom_prefix.respond_to?(:male)
+    assert !with_custom_prefix.respond_to?(:female)    
+    assert !with_custom_prefix.respond_to?(:gender_female)        
+    assert_respond_to with_custom_prefix, :g_male
+    assert_respond_to with_custom_prefix, :g_female
+    assert_equal 1, with_custom_prefix.g_female    
+    assert_respond_to with_custom_prefix, :genders    
+  end
+  
+  test "new :upcase option for those guys picky with coding guidelines etc." do
+    with_upcase = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'
+      as_enum :gender, [:male, :female], :upcase => true
+    end
+    
+    assert_respond_to with_upcase, :GENDERS
+    assert_same 0, with_upcase.GENDERS.male
+    assert_same 1, with_upcase.GENDERS[:female]
+  end
+end

data/test/enum_hash_test.rb

@@ -0,0 +1,33 @@
+require 'test_helper'
+require 'simple_enum/enum_hash'
+
+class EnumHashTest < ActiveSupport::TestCase  
+  
+  test "create new EnumHash instance from array of symbols" do
+    genders = SimpleEnum::EnumHash.new [:male, :female]
+    
+    assert_same 0, genders[:male]
+    assert_same 1, genders[:female]
+    assert_same 0, genders.male
+    assert_same :female, genders.female(true)
+  end
+
+  test "create new EnumHash instance from Hash" do
+    status = SimpleEnum::EnumHash.new :inactive => 0, :active => 1, :archived => 99
+    
+    assert_same 0, status.inactive
+    assert_same 1, status[:active]
+  end
+  
+  test "create new EnumHash instance from ActiveRecord results" do
+    reload_db :genders => true
+    genders = SimpleEnum::EnumHash.new Gender.find(:all)
+    
+    male = Gender.find(0)
+    
+    assert_same 0, genders[male]
+    assert_same genders[male], genders[:male]
+    assert_same 1, genders.female
+    assert_equal male, genders.send(:male, true)
+  end
+end

data/test/finders_test.rb

@@ -0,0 +1,41 @@
+require 'test_helper'
+
+class FindersTest < ActiveSupport::TestCase  
+  def setup
+    reload_db
+  end
+
+  test "find all where :gender = :female" do
+    girls = Dummy.find :all, :conditions => { :gender_cd => Dummy.genders[:female] }, :order => 'name ASC'
+    
+    assert_equal 2, girls.length
+    
+    assert_equal 'Anna', girls.first.name
+    assert_equal :female, girls.first.gender
+    assert_equal true, girls.first.female?
+  end
+  
+  test "find all where :word is 'gamma'" do
+    gammas = Dummy.find :all, :conditions => { :word_cd => Dummy.words(:gamma) }
+    
+    assert_equal 1, gammas.length
+    assert_equal 'Chris', gammas.first.name
+    assert_equal true, gammas.first.male?
+    assert_equal 'gamma', gammas.first.word_cd
+    assert_equal :gamma, gammas.first.word
+  end
+  
+  test "find with string conditions for all :didum = :foo" do
+    foos = Dummy.find :all, :conditions => ['other = ?', Dummy.didums(:foo)]
+    
+    assert_equal 1, foos.length
+    assert_equal false, foos.first.foobar?
+  end
+  
+  test "find using insecure inline string conditions" do
+    men = Dummy.find :all, :conditions => "gender_cd = #{Dummy.genders(:male)}"
+    
+    assert_equal 1, men.length
+    assert_equal true, men.first.male?
+  end  
+end

data/test/models.rb

@@ -0,0 +1,8 @@
+class Dummy < ActiveRecord::Base
+  as_enum :gender, [:male, :female]
+  as_enum :word, { :alpha => 'alpha', :beta => 'beta', :gamma => 'gamma'}
+  as_enum :didum, [ :foo, :bar, :foobar ], :column => 'other'  
+end
+
+class Gender < ActiveRecord::Base
+end

data/test/object_backed_test.rb

@@ -0,0 +1,67 @@
+require 'test_helper'
+
+class ObjectBackedTest < ActiveSupport::TestCase  
+  def setup
+    reload_db :genders => true    
+  end
+
+  test "how working with object backed columns work..." do
+    # simple object -> not db backed instance
+    simple_obj = Class.new do
+      attr_accessor :name
+      def initialize(name)
+        @name = name
+      end  
+    end
+    
+    # create new class by using simple_obj
+    with_object = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'      
+      as_enum :gender, { simple_obj.new('Male') => 0, simple_obj.new('Female') => 1 }      
+    end
+    
+    d = with_object.find_by_name('Anna')
+    
+    assert_same simple_obj, d.gender.class
+    assert_equal 'Female', d.gender.name
+    assert_same true, d.female?
+    assert_same false, d.male?
+    assert_same 0, with_object.male    
+  end
+  
+  test "db backed objects, using method described in 'Advanced Rails Recipes - Recipe 61: Look Up Constant Data Efficiently'" do
+    # "cache" as defined in ARR#61
+    genders = Gender.find(:all)
+    # works without mapping... .map { |g| [g, g.id] }
+    
+    # use cached array of values
+    with_db_obj = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'
+      as_enum :gender, genders
+    end
+    
+    d = with_db_obj.find_by_name('Bella');
+    
+    assert_respond_to with_db_obj, :female
+    assert_respond_to with_db_obj, :male
+    assert_equal 0, with_db_obj.male
+  end
+  
+  test "that accessing keys and values of each enumeration value works as expected" do
+    genders = Gender.find(:all, :order => :id)
+    
+    male = genders.first
+    female = genders.last
+    
+    with_db_obj = Class.new(ActiveRecord::Base) do
+      set_table_name 'dummies'
+      as_enum :gender, genders
+    end
+    
+    assert_same male.id, with_db_obj.male
+    assert_same male, with_db_obj.male(true)
+    
+    assert_same :male, Dummy.male(true)
+    assert_same 0, Dummy.male
+  end
+end