enum_accessor 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6b8947f56d293a6a55ae10dcdc009bfa6b2cfbd4
-  data.tar.gz: 75825ca40a5002cd3c1506b77df310aa6cb9138b
+  metadata.gz: 4447e24f3730702d1e8941a42376605fa905064d
+  data.tar.gz: 9adf5320bb7fe9c8f1e8f719c54146fe8fade703
 SHA512:
-  metadata.gz: c41df44791461e8d1471a7d8a6567f3677cda98cb0b2a4226108cfc31adcb3feed3f894e6b0347a3881de61674149c478b40b4f320a3124a55d2d3df70e60a99
-  data.tar.gz: ff9bfc17e13950b8bb5844d625d4e8c1912221c0c46423250f569a4a5c0e438e0a39b27875e03c64e06d02852b2e2d3d985dc8b7d1d7814ff7bfda66de96fb2f
+  metadata.gz: 30990654b79c136e12443358a3fae8470d91e0966affe68b8d93a9f65df7cbfd372c4f6c4100345aa7597f7521d03221d991a80a5ea3485077b81f5417063434
+  data.tar.gz: a308687d6221dab4b912d65e28be73266d9fdb90e0cc6b2591a4a2c47a00dc27537288e728688422030e2ef8dfaed0e681fc70eb09cd081368db8ba836a6416a

data/README.md

@@ -2,6 +2,13 @@
 
 EnumAccessor lets you define enum for attributes, and store them as integer in the database.
 
+It is very similar to [Official Rails 4.1 Implementation](http://edgeguides.rubyonrails.org/4_1_release_notes.html#active-record-enums), but EnumAccessor offers quite a few advantages:
+
+* Safe predicate methods (`user.status_active?` instead of `user.active?`)
+* Validation
+* Scope
+* Translation
+
 Compatible with ActiveRecord 3 or later.
 
 ## Usage
@@ -16,7 +23,7 @@ Define `enum_accessor` in a model class.
 
 ```ruby
 class User < ActiveRecord::Base
-  enum_accessor :gender, [ :female, :male ]
+  enum_accessor :gender, [:female, :male]
 end
 ```
 
@@ -24,16 +31,16 @@ And now you have a set of methods and constants.
 
 ```ruby
 user = User.new
-user.gender             # => :female
-user.gender_male?       # => false
+user.gender = 'female'  # Takes String or Symbol
+user.gender             # => "female"
+user.gender_female?     # => true
 user.gender_raw         # => 0
 
 user.gender = :male
-user.gender_male?       # => true
+user.gender_female?     # => false
 user.gender_raw         # => 1
 
-User.genders            # => { :female => 0, :male => 1 }
-User::GENDERS           # => { "female" => 0, "male" => 1 }
+User.genders.dict       # => { 'female' => 0, 'male' => 1 }
 ```
 
 Notice that zero-based numbering is used as database values.
@@ -42,11 +49,11 @@ Your migration should look like this.
 
 ```ruby
 create_table :users do |t|
-  t.integer :gender, :default => 0
+  t.integer :gender, default: 0
 end
 ```
 
-Optionally, it would be a good idea to add `:limit => 1` on the column for even better space efficiency when the enum set is small.
+Optionally, it would be a good idea to add `limit: 1` on the column for even better space efficiency when the enum set is small.
 
 ## Manual coding
 
@@ -63,21 +70,27 @@ enum_accessor :status, ok: 200, not_found: 404, internal_server_error: 500
 For querying purpose, use `User.genders` method to retrieve internal integer values.
 
 ```ruby
-User.where(gender: User.genders(:female))
+User.where_gender(:female)
+```
+
+Also takes multiple values.
+
+```ruby
+User.where_status(:active, :pending)
 ```
 
 ## Validations
 
-You can pass custom validation options to `validates_inclusion_of`.
+You can pass `validates: true` to enable validation.
 
 ```ruby
-enum_accessor :status, [ :on, :off ], validation_options: { message: "incorrect status" }
+enum_accessor :status, [:on, :off], validates: true
 ```
 
-Or skip validation entirely.
+You can also pass validation options.
 
 ```ruby
-enum_accessor :status, [ :on, :off ], validate: false
+enum_accessor :status, [:on, :off], validates: { allow_nil: true }
 ```
 
 ## Translation
@@ -98,40 +111,31 @@ and now `human_*` methods return a translated string. It defaults to `humanize`
 
 ```ruby
 I18n.locale = :ja
-user.human_gender     # => '女'
-User.human_genders    # => { :female => '女', :male => '男' }
+user.human_gender       # => '女'
+User.genders.human_dict # => { 'female' => '女', 'male' => '男' }
 
 I18n.locale = :en
-user.human_gender     # => 'Female'
-User.human_genders    # => { :female => 'Female', :male => 'Male' }
+user.human_gender       # => 'Female'
+User.genders.human_dict # => { 'female' => 'Female', 'male' => 'Male' }
 ```
 
 ## Changelog
 
+- v1.0.0:
+  - Drop support for Ruby 1.8
+  - Now getter method returns a String rather than a Symbol
+  - Do not validate by default
+  - Added `where_gender(:female)` scope
+  - Removed the `_raw=` setter as it is now aware of the argument type
+  - Removed constants (e.g. `User::GENDERS`) and now use the class attribute to save the definition
 - v0.3.0: Add support for `find_or_create_by`
 
-## Why enum keys are internally stored as strings rather than symbols?
-
-Because `params[:gender].to_sym` is dangerous. It could lead to problems like memory leak, slow symbol table lookup, or even DoS attack. If a user sends random strings for the parameter, it generates uncontrollable number of symbols, which can never be garbage collected, and eventually causes `symbol table overflow (RuntimeError)`, eating up gigabytes of memory.
-
-For the same reason, `ActiveSupport::HashWithIndifferentAccess` (which is used for `params`) keeps hash keys as string internally.
-
-https://github.com/rails/rails/blob/master/activesupport/lib/active_support/hash_with_indifferent_access.rb
-
 ## Other solutions
 
-There are tons of similar gems out there. Then why did I bother creating another one myself rather than sending pull requests to one of them? Because each one of them has incompatible design policies than EnumAccessor.
+There are tons of similar gems out there. Then why did I bother creating another one myself rather than sending pull requests to one of them? Because most of them define enum values as top-level predicate methods, which can cause method conflict. (`user.active?` vs `user.status_active?`)
 
+* [Official Rails 4.1 Implementation](http://edgeguides.rubyonrails.org/4_1_release_notes.html#active-record-enums)
 * [simple_enum](https://github.com/lwe/simple_enum)
-  * Pretty close to EnumAccessor feature-wise but requires `*_cd` suffix for the database column, which makes AR scopes ugly.
-  * Enum values are defined as top-level predicate methods, which could conflict with existing methods. Also you can't define multiple enums to the same model. In some use cases, predicate methods are not necessary and you just want to be on the safe side.
-* [enumerated_attribute](https://github.com/jeffp/enumerated_attribute)
-  * Top-level predicate methods. Many additional methods are coupled with a specific usage assumption.
-* [enum_field](https://github.com/jamesgolick/enum_field)
-  * Top-level predicate methods.
-* [coded_options](https://github.com/jasondew/coded_options)
-* [active_enum](https://github.com/adzap/active_enum)
-* [classy_enum](https://github.com/beerlington/classy_enum)
 * [enumerize](https://github.com/brainspec/enumerize)
 
 Also, EnumAccessor has one of the simplest code base, so that you can easily hack on.

data/lib/enum_accessor.rb

@@ -6,94 +6,101 @@ module EnumAccessor
   extend ActiveSupport::Concern
 
   module ClassMethods
-    def enum_accessor(field, enums, options={})
-      # Normalize arguments
-      field = field.to_s
-      case enums
-      when Array
-        enums = Hash[enums.map.with_index{|v,i| [v.to_s, i] }]
-      when Hash
-        enums = Hash[enums.map{|k,v| [k.to_s, v] }]
-      else
-        raise ArgumentError.new('enum_accessor takes Array or Hash as the second argument')
-      end
-
-      const_name = field.pluralize.upcase
-      const_set(const_name, enums) unless const_defined?(const_name)
-      const = const_get(const_name)
-
-      symbolized_enums = Hash[enums.map{|k,v| [k.to_sym, v] }]
+    def enum_accessor(column, keys, options={})
+      definition = :"#{column}_enum_accessor"
+      class_attribute definition # will set instance accessor as well
+      send "#{definition}=", Definition.new(column, keys, self)
 
       # Getter
-      define_method(field) do
-        symbolized_enums.key(read_attribute(field))
+      define_method(column) do
+        send(definition).dict.key(read_attribute(column))
       end
 
       # Setter
-      define_method("#{field}=") do |arg|
+      define_method("#{column}=") do |arg|
         case arg
         when String, Symbol
-          write_attribute field, const[arg.to_s]
-        when Integer
-          write_attribute field, arg
+          write_attribute column, send(definition).dict[arg]
+        when Integer, NilClass
+          write_attribute column, arg
         end
       end
 
       # Raw-value getter
-      define_method("#{field}_raw") do
-        read_attribute field
+      define_method("#{column}_raw") do
+        read_attribute(column)
       end
 
-      # Raw-value setter
-      define_method("#{field}_raw=") do |arg|
-        write_attribute field, Integer(arg)
+      # Predicate
+      send(definition).dict.each do |key, int|
+        define_method("#{column}_#{key}?") do
+          read_attribute(column) == int
+        end
       end
 
-      # Checker
-      symbolized_enums.keys.each do |key|
-        method_name = key.to_s.downcase.gsub(/[-\s]/, '_')
-        define_method("#{field}_#{method_name}?") do
-          self.send(field) == key
-        end
+      # Human-friendly print
+      define_method("human_#{column}") do
+        self.class.send "human_#{column}", send(column)
       end
 
-      # Class method
-      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
-        def self.#{field.pluralize}(symbol = nil)
-          return #{symbolized_enums} if symbol.nil?
-          return #{symbolized_enums}[symbol]
-        end
+      # Class methods
+      define_singleton_method column.to_s.pluralize do
+        send(definition)
+      end
 
-        def self.human_#{field.pluralize}(symbol = nil)
-          humanized_enums = Hash[#{symbolized_enums}.map{|k,v| [k, human_enum_accessor(:#{field}, k)] }]
-          return humanized_enums if symbol.nil?
-          return humanized_enums[symbol]
+      # Human-friendly print on class level
+      # Mimics ActiveModel::Translation.human_attribute_name
+      define_singleton_method "human_#{column}" do |key, options={}|
+        defaults = lookup_ancestors.map do |klass|
+          :"#{self.i18n_scope}.enum_accessor.#{klass.model_name.i18n_key}.#{column}.#{key}"
         end
-      EOS
+        defaults << :"enum_accessor.#{self.model_name.i18n_key}.#{column}.#{key}"
+        defaults << :"enum_accessor.#{column}.#{key}"
+        defaults << options.delete(:default) if options[:default]
+        defaults << key.to_s.humanize
 
-      # Human-friendly print
-      define_method("human_#{field}") do
-        self.class.human_enum_accessor(field, self.send(field))
+        options.reverse_merge! count: 1, default: defaults
+        I18n.translate(defaults.shift, options)
+      end
+
+      # Scopes
+      define_singleton_method "where_#{column}" do |*args|
+        integers = args.map{|arg| send(definition).dict[arg] }.compact
+        where(column => integers)
       end
 
       # Validation
-      unless options[:validate] == false
-        validates_inclusion_of field, { :in => symbolized_enums.keys }.merge(options[:validation_options] || {})
+      if options.has_key?(:validate) or options.has_key?(:validation_options)
+        raise ArgumentError, 'validation options are updated. please refer to the documentation.'
+      end
+      if options[:validates]
+        validation_options = options[:validates].is_a?(Hash) ? options[:validates] : {}
+        validates column, { inclusion: { in: send(definition).dict.keys } }.merge(validation_options)
       end
     end
 
-    # Mimics ActiveModel::Translation.human_attribute_name
-    def human_enum_accessor(field, key, options = {})
-      defaults = lookup_ancestors.map do |klass|
-        :"#{self.i18n_scope}.enum_accessor.#{klass.model_name.i18n_key}.#{field}.#{key}"
+    class Definition
+      attr_accessor :dict
+
+      def initialize(column, keys, klass)
+        dict = case keys
+        when Array
+          Hash[keys.map.with_index{|i,index| [i, index] }]
+        when Hash
+          keys
+        else
+          raise ArgumentError.new('enum_accessor takes Array or Hash as the second argument')
+        end
+
+        @column = column
+        @klass = klass
+        @dict = dict.with_indifferent_access.freeze
       end
-      defaults << :"enum_accessor.#{self.model_name.i18n_key}.#{field}.#{key}"
-      defaults << :"enum_accessor.#{field}.#{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)
+      def human_dict
+        # Don't memoize - I18n.locale can change
+        Hash[@dict.keys.map{|key| [key, @klass.send("human_#{@column}", key)] }].with_indifferent_access
+      end
     end
   end
 end

data/lib/enum_accessor/version.rb

@@ -1,3 +1,3 @@
 module EnumAccessor
-  VERSION = '0.3.0'
+  VERSION = '1.0.0'
 end

data/spec/enum_accessor_spec.rb

@@ -7,7 +7,7 @@ ActiveRecord::Base.connection.create_table :users, force: true do |t|
 end
 
 class User < ActiveRecord::Base
-  enum_accessor :gender, [ :female, :male ]
+  enum_accessor :gender, [:female, :male]
 end
 
 describe EnumAccessor do
@@ -15,66 +15,103 @@ describe EnumAccessor do
     @user = User.new
   end
 
+  after do
+    User.delete_all
+  end
+
   it 'adds checker' do
     expect(@user.gender_female?).to eq(true)
     expect(@user.gender_male?).to eq(false)
   end
 
   it 'adds getter' do
-    expect(@user.gender).to eq(:female)
+    expect(@user.gender).to eq('female')
   end
 
   it 'adds setter' do
     @user.gender = :male
     expect(@user.gender_male?).to eq(true)
+
+    @user.gender = nil
+    expect(@user.gender.nil?).to eq(true)
   end
 
   it 'adds raw value getter' do
     expect(@user.gender_raw).to eq(0)
   end
 
-  it 'adds raw value setter' do
-    @user.gender_raw = 1
-    expect(@user.gender_male?).to eq(true)
-  end
-
   it 'adds humanized methods' do
     I18n.locale = :ja
     expect(User.human_attribute_name(:gender)).to eq('性別')
     expect(@user.human_gender).to eq('女')
-    expect(User.human_genders(:female)).to eq('女')
-    expect(User.human_genders).to eq({ :female => '女', :male => '男' })
+    expect(User.genders.human_dict[:female]).to eq('女')
+    expect(User.genders.human_dict).to eq({ 'female' => '女', 'male' => '男' })
 
     I18n.locale = :en
     expect(User.human_attribute_name(:gender)).to eq('Gender')
     expect(@user.human_gender).to eq('Female')
-    expect(User.human_genders(:female)).to eq('Female')
-    expect(User.human_genders).to eq({ :female => 'Female', :male => 'Male' })
+    expect(User.genders.human_dict[:female]).to eq('Female')
+    expect(User.genders.human_dict).to eq({ 'female' => 'Female', 'male' => 'Male' })
   end
 
-  it 'defines internal constant' do
-    expect(User::GENDERS).to eq({ "female" => 0, "male" => 1 })
+  it 'adds class methods' do
+    expect(User.genders.dict).to eq({ 'female' => 0, 'male' => 1 })
+    expect(User.genders.dict[:female]).to eq(0)
   end
 
-  it 'adds class methods' do
-    expect(User.genders).to eq({ :female => 0, :male => 1 })
-    expect(User.genders[:female]).to eq(0)
-    expect(User.genders(:female)).to eq(0)
+  it 'supports manual coding' do
+    class UserManualCoding < ActiveRecord::Base
+      self.table_name = :users
+      enum_accessor :gender, female: 100, male: 200
+    end
+
+    user = UserManualCoding.new
+    user.gender = :male
+    expect(user.gender_male?).to eq(true)
+    expect(user.gender_raw).to eq(200)
   end
 
   it 'adds validation' do
-    @user.gender = 'bogus'
-    expect(@user.valid?).to be_falsey
-
-    @user.gender = 'male'
-    expect(@user.valid?).to be_truthy
+    class UserValidate < ActiveRecord::Base
+      self.table_name = :users
+      enum_accessor :gender, [:female, :male], validates: true
+    end
+
+    class UserValidateAllowNil < ActiveRecord::Base
+      self.table_name = :users
+      enum_accessor :gender, [:female, :male], validates: { allow_nil: true }
+    end
+
+    user = UserValidate.new
+    user.gender = 'male'
+    expect(user.valid?).to be_truthy
+    user.gender = nil
+    expect(user.valid?).to be_falsey
+    user.gender = 'bogus' # Becomes nil
+    expect(user.valid?).to be_falsey
+
+    user = UserValidateAllowNil.new
+    user.gender = 'male'
+    expect(user.valid?).to be_truthy
+    user.gender = nil
+    expect(user.valid?).to be_truthy
+    user.gender = 'bogus' # Becomes nil
+    expect(user.valid?).to be_truthy
   end
 
   it 'supports find_or_create_by' do
     # `find_or_create_by` uses where-based raw value for find,
     # then passes the raw value to the setter method for create.
     expect {
-      User.find_or_create_by(gender: User.genders(:female))
+      User.find_or_create_by(gender: User.genders.dict[:female])
     }.to change{ User.count }.by(1)
   end
+
+  it 'supports scope' do
+    user = User.create!(gender: :female)
+
+    expect(User.where_gender(:female).count).to eq(1)
+    expect(User.where_gender(:male, :female).count).to eq(1)
+    expect(User.where_gender(:male).count).to eq(0)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enum_accessor
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Kenn Ejima
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-20 00:00:00.000000000 Z
+date: 2014-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport