simple_enum 1.6.9 → 2.0.0.rc1

data/lib/simple_enum.rb

@@ -3,299 +3,42 @@
 # but instead on integer columns.
 #
 # Author:: Lukas Westermann
-# Copyright:: Copyright (c) 2009 Lukas Westermann (Zurich, Switzerland)
-# Licence:: MIT-Licence (http://www.opensource.org/licenses/mit-license.php)
+# Copyright:: Copyright (c) 2009-2014 Lukas Westermann (Zurich, Switzerland)
+# License:: MIT-Licence (http://www.opensource.org/licenses/mit-license.php)
 #
 # See the +as_enum+ documentation for more details.
 
-# because we depend on i18n and activesupport
-require 'i18n'
 require 'active_support'
 
-require 'simple_enum/enum_hash'
-require 'simple_enum/validation'
-
-require 'active_support/deprecation'
+require 'simple_enum/version'
+require 'simple_enum/attribute'
+require 'simple_enum/translation'
 
 # Base module which gets included in <tt>ActiveRecord::Base</tt>. See documentation
 # of +SimpleEnum::ClassMethods+ for more details.
 module SimpleEnum
+  mattr_accessor :with
+  @@with = [:attribute, :dirty, :scope]
 
-  class << self
-
-    # Provides configurability to SimpleEnum, allows to override some defaults which are
-    # defined for all uses of +as_enum+. Most options from +as_enum+ are available, such as:
-    # * <tt>:prefix</tt> - Define a prefix, which is prefixed to the shortcut methods (e.g. <tt><symbol>!</tt> and
-    #   <tt><symbol>?</tt>), if it's set to <tt>true</tt> the enumeration name is used as a prefix, else a custom
-    #   prefix (symbol or string) (default is <tt>nil</tt> => no prefix)
-    # * <tt>:slim</tt> - If set to <tt>true</tt> no shortcut methods for all enumeration values are being generated, if
-    #   set to <tt>:class</tt> only class-level shortcut methods are disabled (default is <tt>nil</tt> => they are generated)
-    # * <tt>:upcase</tt> - If set to +true+ the <tt>Klass.foos</tt> is named <tt>Klass.FOOS</tt>, why? To better suite some
-    #   coding-styles (default is +false+ => downcase)
-    # * <tt>:whiny</tt> - Boolean value which if set to <tt>true</tt> will throw an <tt>ArgumentError</tt>
-    #   if an invalid value is passed to the setter (e.g. a value for which no enumeration exists). if set to
-    #   <tt>false</tt> no exception is thrown and the internal value is set to <tt>nil</tt> (default is <tt>true</tt>)
-    # * <tt>:dirty</tt> - Boolean value which if set to <tt>true</tt> generates <tt>..._was</tt> and <tt>..._changed?</tt>
-    #   methods for the enum, which delegate to the internal column.
-    # * <tt>:strings</tt> - Boolean value which if set to <tt>true</tt> defaults array values as strings instead of integers.
-    def default_options
-      @default_options ||= {
-        :whiny => true,
-        :upcase => false
-      }
-    end
-
-    def included(base) #:nodoc:
-      base.send :class_attribute, :simple_enum_definitions, :instance_writer => false, :instance_reader => false
-      base.send :extend, ClassMethods
-    end
-  end
-
-  module ClassMethods
-
-    # Provides ability to create simple enumerations based on hashes or arrays, backed
-    # by integer columns (but not limited to integer columns).
-    #
-    # Columns are supposed to be suffixed by <tt>_cd</tt>, if not, use <tt>:column => 'the_column_name'</tt>,
-    # so some example migrations:
-    #
-    #   add_column :users, :gender_cd, :integer
-    #   add_column :users, :status, :integer # and a custom column...
-    #
-    # and then in your model:
-    #
-    #   class User < ActiveRecord::Base
-    #     as_enum :gender, [:male, :female]
-    #   end
-    #
-    #   # or use a hash:
-    #
-    #   class User < ActiveRecord::Base
-    #     as_enum :user_status, { :active => 1, :inactive => 0, :archived => 2, :deleted => 3 }, :column => 'status'
-    #   end
-    #
-    # Now it's possible to access the enumeration and the internally stored value like:
-    #
-    #   john_doe = User.new
-    #   john_doe.gender          # => nil
-    #   john_doe.gender = :male
-    #   john_doe.gender          # => :male
-    #   john_doe.gender_cd       # => 0
-    #
-    # And to make life a tad easier: a few shortcut methods to work with the enumeration are also created.
-    #
-    #   john_doe.male?           # => true
-    #   john_doe.female?         # => false
-    #   john_doe.female!         # => :female (set's gender to :female => gender_cd = 1)
-    #   john_doe.male?           # => false
-    #
-    # Sometimes it's required to access the db-backed values, like e.g. in a query:
-    #
-    #   User.genders             # =>  { :male => 0, :female => 1}, values hash
-    #   User.genders(:male)      # => 0, value access (via hash)
-    #   User.female              # => 1, direct access
-    #   User.find :all, :conditions => { :gender_cd => User.female }  # => [...], list with all women
-    #
-    # To access the key/value assocations in a helper like the select helper or similar use:
-    #
-    #   <%= select(:user, :gender, User.genders.keys)
-    #
-    # The generated shortcut methods (like <tt>male?</tt> or <tt>female!</tt> etc.) can also be prefixed
-    # using the <tt>:prefix</tt> option. If the value is <tt>true</tt>, the shortcut methods are prefixed
-    # with the name of the enumeration.
-    #
-    #   class User < ActiveRecord::Base
-    #     as_enum :gender, [:male, :female], :prefix => true
-    #   end
-    #
-    #   jane_doe = User.new
-    #   jane_doe.gender = :female   # this is still as-is
-    #   jane_doe.gender_cd          # => 1, and so it this
-    #
-    #   jane_doe.gender_female?     # => true (instead of jane_doe.female?)
-    #
-    # It is also possible to supply a custom prefix.
-    #
-    #   class Item < ActiveRecord::Base
-    #     as_enum :status, [:inactive, :active, :deleted], :prefix => :state
-    #   end
-    #
-    #   item = Item.new(:status => :active)
-    #   item.state_inactive?       # => false
-    #   Item.state_deleted         # => 2
-    #   Item.status(:deleted)      # => 2, same as above...
-    #
-    # To disable the generation of the shortcut methods for all enumeration values, add <tt>:slim => true</tt> to
-    # the options.
-    #
-    #   class Address < ActiveRecord::Base
-    #     as_enum :canton, {:aargau => 'ag', ..., :wallis => 'vs', :zug => 'zg', :zurich => 'zh'}, :slim => true
-    #   end
-    #
-    #   home = Address.new(:canton => :zurich, :street => 'Bahnhofstrasse 1', ...)
-    #   home.canton       # => :zurich
-    #   home.canton_cd    # => 'zh'
-    #   home.aargau!      # throws NoMethodError: undefined method `aargau!'
-    #   Address.aargau    # throws NoMethodError: undefined method `aargau`
-    #
-    # This is especially useful if there are (too) many enumeration values, or these shortcut methods
-    # are not required.
-    #
-    # === Configuration options:
-    # * <tt>:column</tt> - Specifies a custom column name, instead of the default suffixed <tt>_cd</tt> column
-    # * <tt>:prefix</tt> - Define a prefix, which is prefixed to the shortcut methods (e.g. <tt><symbol>!</tt> and
-    #   <tt><symbol>?</tt>), if it's set to <tt>true</tt> the enumeration name is used as a prefix, else a custom
-    #   prefix (symbol or string) (default is <tt>nil</tt> => no prefix)
-    # * <tt>:slim</tt> - If set to <tt>true</tt> no shortcut methods for all enumeration values are being generated, if
-    #   set to <tt>:class</tt> only class-level shortcut methods are disabled (default is <tt>nil</tt> => they are generated)
-    # * <tt>:upcase</tt> - If set to +true+ the <tt>Klass.foos</tt> is named <tt>Klass.FOOS</tt>, why? To better suite some
-    #   coding-styles (default is +false+ => downcase)
-    # * <tt>:whiny</tt> - Boolean value which if set to <tt>true</tt> will throw an <tt>ArgumentError</tt>
-    #   if an invalid value is passed to the setter (e.g. a value for which no enumeration exists). if set to
-    #   <tt>false</tt> no exception is thrown and the internal value is set to <tt>nil</tt> (default is <tt>true</tt>)
-    # * <tt>:dirty</tt> - Boolean value which if set to <tt>true</tt> generates <tt>..._was</tt> and <tt>..._changed?</tt>
-    #   methods for the enum, which delegate to the internal column (default is <tt>false</tt>)
-    # * <tt>:strings</tt> - Boolean value which if set to <tt>true</tt> stores array values as strings instead of it's index.
-    # * <tt>:field</tt> - Also allowed as valid key, for Mongoid integration + default options, see simple_enum#27.
-    #
-    def as_enum(enum_cd, values, options = {})
-      options = SimpleEnum.default_options.merge({ :column => "#{enum_cd}_cd" }).merge(options)
-      options.assert_valid_keys(:column, :whiny, :prefix, :slim, :upcase, :dirty, :strings, :field)
-
-      metaclass = (class << self; self; end)
-
-      # convert array to hash
-      values = SimpleEnum::EnumHash.new(values, options[:strings])
-      values_inverted = values.invert
-
-      # store info away
-      self.enum_definitions[enum_cd] = self.enum_definitions[options[:column]] = { :name => enum_cd, :column => options[:column], :options => options }
-
-      # raise error if enum_cd == column
-      raise ArgumentError, "[simple_enum] use different names for #{enum_cd}'s name and column name." if enum_cd.to_s == options[:column].to_s
-
-      # generate getter
-      define_method("#{enum_cd}") do
-        id = send(options[:column])
-        values_inverted[id]
-      end
-
-      # generate setter
-      define_method("#{enum_cd}=") do |new_value|
-        return send("#{options[:column]}=", nil) if new_value.blank?
-
-        new_value = new_value.to_s if options[:strings]
-        real = nil
-        if values.contains?(new_value)
-          real = values[EnumHash.symbolize(new_value)]
-          real = new_value if real.nil? && values_inverted[new_value].present?
-        end
-
-        raise ArgumentError, "Invalid enumeration value: #{new_value}" if options[:whiny] && !real
-        send("#{options[:column]}=", real)
-      end
-
-      # generate checker
-      define_method("#{enum_cd}?") do |*args|
-        current = send(enum_cd)
-        return current.to_s == args.first.to_s if args.length > 0
+  mattr_accessor :accessor
+  @@accessor = :default
 
-        !!current
-      end
+  mattr_accessor :builder
+  @@builder = :default
 
-      # support dirty attributes by delegating to column, currently opt-in
-      if options[:dirty]
-        define_method("#{enum_cd}_changed?") do
-          self.send("#{options[:column]}_changed?")
-        end
+  mattr_accessor :suffix
+  @@suffix = "_cd"
 
-        define_method("#{enum_cd}_was") do
-          values_inverted[self.send("#{options[:column]}_was")]
-        end
-      end
+  mattr_accessor :field
+  @@field = {}
 
-      # allow access to defined values hash, e.g. in a select helper or finder method.
-      attr_name = enum_cd.to_s.pluralize
-      enum_attr = :"#{attr_name.downcase}_enum_hash"
-
-      define_method("human_#{enum_cd}") do
-        self.class.human_enum_name(attr_name, self.send(enum_cd)) unless self.send(enum_cd).nil?
-      end
-
-      # generate find_by enum singleton
-      (class << self; self end).send(:define_method, "find_by_#{enum_cd}") do |*args|
-        send("find_by_#{options[:column]}", args)
-      end
-
-      class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
-        class_attribute #{enum_attr.inspect}, :instance_writer => false, :instance_reader => false
-
-        def self.#{attr_name}(*args)
-          return #{enum_attr} if args.first.nil?
-          return #{enum_attr}[args.first] if args.size == 1
-          args.inject([]) { |ary, sym| ary << #{enum_attr}[sym]; ary }
-        end
-
-        def self.#{attr_name}_for_select(attr = :key, &block)
-          self.#{attr_name}.map do |k,v|
-            [block_given? ? yield(k,v) : self.human_enum_name(#{attr_name.inspect}, k), attr == :value ? v : k]
-          end
-        end
-      RUBY
-
-      # write values
-      self.send "#{enum_attr}=", values
-
-      # only create if :slim is not defined
-      if options[:slim] != true
-        # create both, boolean operations and *bang* operations for each
-        # enum "value"
-        prefix = options[:prefix] && "#{options[:prefix] == true ? enum_cd : options[:prefix]}_"
-
-        values.each do |k,code|
-          sym = EnumHash.symbolize(k)
-
-          define_method("#{prefix}#{sym}?") do
-            current = send(options[:column])
-            code == current
-          end
-          define_method("#{prefix}#{sym}!") do
-            send("#{options[:column]}=", code)
-            sym
-          end
-
-          # allow class access to each value
-          unless options[:slim] === :class
-            metaclass.send(:define_method, "#{prefix}#{sym}", Proc.new { |*args| args.first ? k : code })
-          end
-        end
-      end
-    end
-
-    def human_enum_name(enum, key, options = {})
-      defaults = lookup_ancestors.map do |klass|
-        :"#{self.i18n_scope}.enums.#{klass.model_name.i18n_key}.#{enum}.#{key}"
-      end
-
-      defaults << :"enums.#{self.model_name.i18n_key}.#{enum}.#{key}"
-      defaults << :"enums.#{enum}.#{key}"
-      defaults << options.delete(:default) if options[:default]
-      defaults << key.to_s.humanize
-
-      options.reverse_merge! :count => 1, :default => defaults
-      I18n.translate(defaults.shift, options)
-    end
-
-    def enum_definitions
-      self.simple_enum_definitions ||= {}
-    end
+  def self.configure
+    yield(self)
   end
 end
 
 # include in AR
 ActiveSupport.on_load(:active_record) do
-  ActiveRecord::Base.send(:include, SimpleEnum)
+  ActiveRecord::Base.send(:extend, SimpleEnum::Attribute)
+  ActiveRecord::Base.send(:extend, SimpleEnum::Translation)
 end
-
-# setup i18n load path...
-I18n.load_path << File.join(File.dirname(__FILE__), '..', 'locales', 'en.yml')

data/simple_enum.gemspec

@@ -8,23 +8,23 @@ Gem::Specification.new do |s|
   s.summary     = "Simple enum-like field support for models."
   s.description = "Provides enum-like fields for ActiveRecord, ActiveModel and Mongoid models."
 
-  s.required_ruby_version     = ">= 1.8.7"
-  s.required_rubygems_version = ">= 1.3.6"
+  s.required_ruby_version     = ">= 1.9.3"
+  s.required_rubygems_version = ">= 2.0.0"
 
   s.authors  = ["Lukas Westermann"]
   s.email    = ["lukas.westermann@gmail.com"]
   s.homepage = "http://lwe.github.com/simple_enum/"
 
-  s.files            = %w{.gitignore Rakefile Gemfile README.rdoc LICENSE simple_enum.gemspec} + Dir['**/*.{rb,yml}']
-  s.test_files       = s.files.grep(%r{^(test|spec|locales)/})
+  s.files            = %w{.gitignore Rakefile Gemfile README.md LICENSE simple_enum.gemspec} + Dir['**/*.{rb,yml}']
+  s.test_files       = s.files.grep(%r{^(test|spec)/})
   s.require_paths    = %w{lib}
 
   s.license          = 'MIT'
 
-  s.add_dependency "activesupport", '>= 3.0.0'
+  s.add_dependency 'activesupport', '>= 4.0.0'
 
-  s.add_development_dependency 'rake', '>= 0.9.2'
-  s.add_development_dependency 'minitest', '~> 2.0'
-  s.add_development_dependency 'activerecord', '>= 3.0.0'
-  s.add_development_dependency 'mongoid', '~> 2.0'
+  s.add_development_dependency 'rake', '>= 10.1.0'
+  s.add_development_dependency 'activerecord', '>= 4.0.0'
+  s.add_development_dependency 'mongoid', '>= 4.0.0.beta1'
+  s.add_development_dependency 'rspec', '~> 2.14'
 end

data/spec/simple_enum/accessors_spec.rb

@@ -0,0 +1,212 @@
+require 'spec_helper'
+
+describe SimpleEnum::Accessors do
+  let(:enum) { SimpleEnum::Enum.new(:gender, "male" => 0, "female" => 1) }
+  fake_model(:klass)
+  let(:object) { klass.new }
+
+  context '.accessor' do
+    it 'returns Accessor instance' do
+      expect(described_class.accessor(:gender, enum)).to be_a(described_class::Accessor)
+    end
+
+    it 'returns a WhinyAccessor instance if accessor: :whiny' do
+      expect(described_class.accessor(:gender, enum, accessor: :whiny)).to be_a(described_class::WhinyAccessor)
+    end
+
+    it 'sets source to "gender" if source: :gender' do
+      expect(described_class.accessor(:gender, enum, source: :gender).source).to eq 'gender'
+    end
+  end
+
+  context 'Accessor' do
+    subject { described_class::Accessor.new(:gender, enum) }
+
+    context '#name' do
+      it 'returns the enum name as string' do
+        expect(subject.name).to eq 'gender'
+      end
+    end
+
+    context '#to_s' do
+      it 'returns the name' do
+        expect(subject.to_s).to eq 'gender'
+      end
+    end
+
+    context '#prefix' do
+      it 'returns empty string when prefix is nil' do
+        expect(described_class::Accessor.new(:gender, enum).prefix).to eq ''
+      end
+
+      it 'returns gender_ when prefix is true' do
+        expect(described_class::Accessor.new(:gender, enum, nil, true).prefix).to eq 'gender_'
+      end
+
+      it 'returns other_ when prefix is "other"' do
+        expect(described_class::Accessor.new(:gender, hash, nil, 'other').prefix).to eq 'other_'
+      end
+    end
+
+    context '#source' do
+      it 'returns gender_cd when source is nil' do
+        expect(described_class::Accessor.new(:gender, hash, nil).source).to eq 'gender_cd'
+      end
+
+      it 'returns "some_column" when source is set to :some_column' do
+        expect(described_class::Accessor.new(:gender, hash, :some_column).source).to eq 'some_column'
+      end
+
+      it 'returns "gender" when source is set to "gender"' do
+        expect(described_class::Accessor.new(:gender, hash, 'gender').source).to eq 'gender'
+      end
+    end
+
+    context '#read' do
+      shared_examples_for 'reading an enum' do
+        it 'returns nil then gender_cd is nil' do
+          expect(subject.read(object)).to be_nil
+        end
+
+        it 'returns :male when gender_cd is 0' do
+          expect(subject.read(klass.new(0))).to eq :male
+        end
+
+        it 'returns :female when gender_cd is 1' do
+          expect(subject.read(klass.new(1))).to eq :female
+        end
+      end
+
+      it_behaves_like 'reading an enum'
+
+      context 'with name == source' do
+        subject { described_class::Accessor.new(:gender_cd, enum, :gender_cd) }
+        it_behaves_like 'reading an enum'
+      end
+    end
+
+    context '#write' do
+      shared_examples_for 'writing an enum' do
+        it 'writes nil to object' do
+          object = klass.new(0)
+          expect(subject.write(object, nil)).to be_nil
+          expect(object.gender_cd).to be_nil
+        end
+
+        it 'writes 1 to object with :female' do
+          expect(subject.write(object, :female)).to eq :female
+          expect(object.gender_cd).to eq 1
+        end
+
+        it 'writes 0 to object with "male"' do
+          expect(subject.write(object, 'male')).to eq 'male'
+          expect(object.gender_cd).to eq 0
+        end
+
+        it 'writes 1 to object with 1' do
+          expect(subject.write(object, 1)).to eq 1
+          expect(object.gender_cd).to eq 1
+        end
+
+        it 'writes nil to object with :other' do
+          object = klass.new(1)
+          expect(subject.write(object, :other)).to be_nil
+          expect(object.gender_cd).to be_nil
+        end
+      end
+
+      it_behaves_like 'writing an enum'
+
+      context 'with name == source' do
+        subject { described_class::Accessor.new(:gender_cd, enum, :gender_cd) }
+        it_behaves_like 'writing an enum'
+      end
+    end
+
+    context '#selected?' do
+      it 'returns false when gender_cd is nil' do
+        expect(subject.selected?(object)).to be_false
+        expect(subject.selected?(object, :male)).to be_false
+      end
+
+      it 'returns true when gender_cd is != nil' do
+        expect(subject.selected?(klass.new(0))).to be_true
+        expect(subject.selected?(klass.new(1))).to be_true
+      end
+
+      it 'returns true when gender_cd is 0 and :male is passed' do
+        expect(subject.selected?(klass.new(0), :male)).to be_true
+      end
+
+      it 'returns false when gender_cd is 0 and :female is passed' do
+        expect(subject.selected?(klass.new(0), :female)).to be_false
+      end
+
+      it 'returns false when gender_cd is 1 and :other is passed' do
+        expect(subject.selected?(klass.new(0), :other)).to be_false
+      end
+    end
+
+    context '#changed?' do
+      it 'delegates to attribute_changed?' do
+        expect(object).to receive(:attribute_changed?).with('gender_cd') { true }
+        expect(subject.changed?(object)).to be_true
+      end
+    end
+
+    context 'was' do
+      it 'delegates to attribute_was and resolves symbol' do
+        expect(object).to receive(:attribute_was).with('gender_cd') { 1 }
+        expect(subject.was(object)).to eq :female
+      end
+    end
+  end
+
+  context 'IgnoreAccessor' do
+    subject { described_class::IgnoreAccessor.new(:gender, enum) }
+
+    it 'sets gender_cd to 0 with symbol' do
+      expect(subject.write(object, :male)).to_not be_false
+      expect(object.gender_cd).to eq 0
+    end
+
+    it 'sets gender_cd to 1 via value (1)' do
+      expect(subject.write(object, 1)).to_not be_false
+      expect(object.gender_cd).to eq 1
+    end
+
+    it 'sets gender_cd to nil' do
+      expect(subject.write(object, nil)).to be_false
+      expect(object.gender_cd).to be_nil
+    end
+
+    it 'keeps existing value when unknown value is passed' do
+      object.gender_cd = 1
+      expect(subject.write(object, :other)).to be_false
+      expect(object.gender_cd).to eq 1
+    end
+  end
+
+  context 'WhinyAccessor' do
+    subject { described_class::WhinyAccessor.new(:gender, enum) }
+
+    it 'raises no error when setting existing key' do
+      expect { subject.write(object, :male) }.to_not raise_error
+      expect(object.gender_cd).to eq 0
+    end
+
+    it 'raises no error when setting with existing value' do
+      expect { subject.write(object, 1) }.to_not raise_error
+      expect(object.gender_cd).to eq 1
+    end
+
+    it 'raises no error when setting to nil' do
+      expect { subject.write(object, nil) }.to_not raise_error
+      expect(object.gender_cd).to be_nil
+    end
+
+    it 'raises ArgumentError when setting invalid key' do
+      expect { subject.write(object, :other) }.to raise_error(ArgumentError)
+    end
+  end
+end