simple_enum 1.6.9 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 18d5bbe70d30e114c220f17681c172597163bfd0
-  data.tar.gz: e9ae250d080b7f6efa78928005df4b9f36ca9ffb
+  metadata.gz: 665f3d1039443aa384654770a39563ac3d784060
+  data.tar.gz: 44d521782b6390f95dc6b11f3d1c2f6bb570c811
 SHA512:
-  metadata.gz: 9150ad6487da910c1b6319030102a2e8504f0775e995f2e4cc8ca09e6198e91176e08d6fa8b9aca468aa0de43cdb5a4168d7b802c0ca159d2a98b860810666a7
-  data.tar.gz: 14577d002d9996148f4e321624ecaba8cf705de2ff8162f06c5aca7940b620dfbf1cda88c3c182aa10eed11ce8257d129e4cc4f870a77f123c0b996a86f97205
+  metadata.gz: 200d1e0d6e1367f7f7c66ccd3380452052b3b16547e461d6050d163e1bd7416c4413139284cf4971c1d18439f6ac816a70571fc2b116ab9bbfe52c753bb7fe50
+  data.tar.gz: 0d1238c44c50cd1b2b98d74d68d97a3e9bf4d265b35f9360cd4da59bcaace4eaa2529fa5874a614d3565b5ea5702841499864f6864ea1e1bca424fe7af81625c

data/Gemfile

@@ -9,3 +9,6 @@ gem 'mongo', '~> 1.9.0', :platform => :jruby
 gem 'activerecord-jdbcsqlite3-adapter', :platform => :jruby
 gem 'sqlite3', :platform => :ruby
 gem 'bson_ext', :platform => :ruby
+
+# Code coverage on CI only
+gem "codeclimate-test-reporter", group: :test, require: nil

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2013 Lukas Westermann (Zurich, Switzerland)
+Copyright (c) 2014 Lukas Westermann (Zurich, Switzerland)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,248 @@
+SimpleEnum
+==========
+
+[![Build Status](https://travis-ci.org/lwe/simple_enum.svg)](https://travis-ci.org/lwe/simple_enum)
+[![Code Climate](https://codeclimate.com/github/lwe/simple_enum.png)](https://codeclimate.com/github/lwe/simple_enum)
+
+Unobtrusive enum-like fields for ActiveRecord and Ruby, brings enums functionality
+to ActiveRecord and Mongoid models (built for Rails 4+).
+
+Since version 2.0, simple_enum is no longer compatible with Rails 3.x or Ruby 1.8,
+use version 1.6 instead: https://github.com/lwe/simple_enum/tree/legacy-1.x
+
+*Note*: a recent search on github for `enum` turned out, that there are many,
+many similar solutions. In fact starting with Rails 4.1, there's `ActiveRecord::Enum`
+which provides **some** of the functionality, but is IMHO pretty limited and too
+strict in the defaults it provides.
+
+ActiveRecord Quick start
+------------------------
+
+Add this to a model:
+
+```ruby
+class User < ActiveRecord::Base
+  as_enum :gender, female: 1, male: 0
+end
+```
+
+Then create the required `gender_cd` column using migrations:
+
+```ruby
+class AddGenderColumnToUser < ActiveRecord::Migration
+  def self.up
+    add_column :users, :gender_cd, :integer
+  end
+
+  def self.down
+    remove_column :users, :gender_cd
+  end
+end
+```
+
+Mongoid Quick start
+-------------------
+
+Due to the dependency on ActiveModel 4.x, the Mongoid integration is only
+available for mongoid 4.0.0 (which is at beta1 at the moment). If you intend
+to use simple_enum with another version of mongoid, use version 1.6 instead.
+
+Load mongoid support in the `Gemfile`:
+
+```ruby
+gem 'simple_enum', '2.0.0.rc1' , require: 'simple_enum/mongoid'
+```
+
+Add this to a model:
+
+```ruby
+class User
+  include Mongoid::Document
+  include SimpleEnum::Mongoid
+
+  as_enum :gender, female: 1, male: 0
+end
+```
+
+The primary difference between AR and mongoid is, that additionaly a field is
+added to mongoid automatically, the field can be customized by setting `field:`
+option, or disabled by setting `field: false`.
+
+Working with enums
+------------------
+
+Now it's possible to pull some neat tricks on the new column, yet the original
+db column (`gender_cd`) is still intact and not touched by anything.
+
+```ruby
+jane = User.new
+jane.gender = :female
+jane.female?   # => true
+jane.male?     # => false
+jane.gender    # => :female
+jane.gender_cd # => 1
+```
+
+Easily switch to another value using the bang methods, this does not save
+the record, only switch the value.
+
+```ruby
+joe = User.new
+joe.male!     # => :male
+joe.gender    # => :male
+joe.gender_cd # => 0
+```
+
+Accessing actual enum values is possible at the class level:
+
+```ruby
+User.genders            # => #<SimpleEnum::Enum:0x0....>
+User.genders[:male]     # => 0
+User.female             # => #<ActiveRecord::Relation:0x0.....> (WHERE gender_cd = 1)
+```
+
+### Wait, there's more!
+
+- Too tired of always adding the integer values? Try:
+
+  ```ruby
+  class User < ActiveRecord::Base
+    as_enum :status, %i{deleted active disabled}
+    # translates to: { deleted: 0, active: 1, disabled: 2 }
+  end
+  ```
+
+  **Disclaimer**: if you _ever_ decide to reorder this array, beaware that any
+  previous mapping is lost. So it's recommended to create mappings (that might
+  change) using hashes instead of arrays. For stuff like gender it might be
+  probably perfectly fine to use arrays though.
+- You can store as string values instead of integer values if your database column
+  has the type `string` or `text`:
+
+  ```ruby
+  class User < ActiveRecord::Base
+    as_enum :status, [:deleted, :active, :disabled], map: :string
+  end
+
+  User.create!(status: :active) #=> #<User id: 1, status_cd: "active">
+  ```
+- Want to use `SimpleEnum` in an ActiveModel, or other class, just add:
+
+  ```ruby
+  class MyModel
+    extend SimpleEnum::Attribute
+    attr_accessor :gender_cd
+    as_enum :gender, [:male, :female]
+  end
+  ```
+- Maybe you've columns named differently than the proposed `{column}_cd` naming scheme, feel free to use any column name
+  by providing an option:
+
+  ```ruby
+  class User < ActiveRecord::Base
+    as_enum :gender, [:male, :female], source: :sex
+  end
+  ```
+
+  Starting with 2.0 it's possible to use the same source name as column name.
+- By default ActiveRecord dirty methods are generated:
+
+  ```ruby
+  user = User.male.first
+  user.gender = :female
+  user.gender_was
+  # => :male
+  ```
+- Need to provide custom options for the mongoid field, or skip the automatically generated field?
+
+  ```ruby
+  # skip field generation
+  field :gender_cd # <- create field manually (!)
+  as_enum :gender, [:male, :female], field: false
+
+  # custom field options (directly passed to Mongoid::Document#field)
+  as_enum :gender, [:male, :female], field: { :type => Integer, :default => 1 }
+  ```
+- To validate enum values simply make use of a `validates :gender, presence: true` validation.
+  If an invalid value is assigned, the gender is set to `nil` by default.
+- If the shortcut methods (like `female?`, `female!` or `User.male`) conflict with something in your class, it's possible to
+  define a prefix:
+
+        class User < ActiveRecord::Base
+          as_enum :gender, %w{male female}, prefix: true
+        end
+
+        jane = User.new gender: :female
+        jane.gender_female? # => true
+        User.gender_female  # => <ActiveRecord::Relation...WHERE gender_cd = 1.>
+
+  The `:prefix` option not only takes a boolean value as an argument, but instead can also be supplied a custom
+  prefix, so with `prefix: 'foo'` all shortcut methods would look like: `foo_<symbol>`
+- To define which methods are generated it's possible to set `with:` option, by
+  default `with:` is set to `[:attribute, :dirty, :scope]`.
+
+  1. `:attribute` - generates the `male?` and `male!` accessor methods
+  2. `:dirty` - adds the `gender_was` and `gender_changed?` dirty methods
+  3. `:scope` - adds the class level scopes, **if** the `scope` method is present
+
+- By default the value is set to `nil` when the user sets an invalid value,
+  this behavior can be changed by setting the `accessor:` option. At the moment
+  there are three different behaviors:
+
+  1. `:default` - which sets the value simply to `nil`
+  2. `:whiny` - raises an ArgumentError when trying to set an invalid value
+  3. `:ignore` - keeps the existing value
+
+  ```ruby
+  class User < ActiveRecord::Base
+    as_enum :gender, %w{male female}, accessor: :whiny
+  end
+  User.new(gender: "dunno") # => raises ArgumentError
+  ```
+
+  See `lib/simple_enum/accessors/*` for more.
+
+- To define any option globally, e.g. never generating dirty methods, create
+  an initializer and add:
+
+  ```ruby
+  # See lib/simple_enum.rb for other options
+  SimpleEnum.with = [:accessor, :scope]
+  ```
+
+## Best practices
+
+Do not use values named after existing, or well known method names, like `new`, `create` etc.
+
+```ruby
+# BAD, conflicts with Rails ActiveRecord Methods (!)
+as_enum :handle, [:new, :create, :update]
+
+# GOOD, prefixes all methods
+as_enum :handle, [:new, :create, :update], :prefix => true
+```
+
+Searching for certain values by using the finder methods:
+
+```ruby
+User.female # => returns an ActiveRecord::Relation
+```
+
+Contributors
+------------
+
+* @dmitry - bugfixes and other improvements
+* @tarsolya - implemented all the ruby 1.9 and rails 3 goodness!
+* @dbalatero - rails 2.3.5 bugfix & validator fixes
+* @johnthethird - feature for <tt>_for_select</tt> to return the values
+* @sinsiliux - ruby 1.9 fixes and removed AR dependency
+* @sled - mongoid support
+* @abrom - <tt>find_by_...</tt> method
+* @mhuggins - translations fixes
+* @patbenatar - for helping move towards 2.0 (scopes et all)
+* and all others: https://github.com/lwe/simple_enum/graphs/contributors thanks
+
+License & Copyright
+-------------------
+
+Copyright (c) 2011-2014 by Lukas Westermann, Licensed under MIT Licence (see LICENSE file)

data/Rakefile

@@ -5,30 +5,13 @@ require 'rake/testtask'
 Bundler::GemHelper.install_tasks
 
 desc 'Default: run all unit tests for both ActiveRecord & Mongoid.'
-task :default => :test
+task :default => :spec
 
-namespace :test do
-  Rake::TestTask.new(:units) do |t|
-    t.libs << "test"
-    t.test_files = Dir['test/*_test.rb']
-    t.verbose = true
-  end
-
-  desc 'Run all unit tests for ActiveRecord'
-  task :activerecord do |t|
-    ENV['SIMPLE_ENUM_TEST_ORM'] = 'active_record'
-    Rake::Task['test:units'].execute
-  end
-
-  desc 'Run all unit tests for Mongoid'
-  task :mongoid do |t|
-    ENV['SIMPLE_ENUM_TEST_ORM'] = 'mongoid'
-    Rake::Task['test:units'].execute
-  end
+desc 'Run rspec test suite'
+task :spec do
+  sh 'bundle exec rspec spec/'
 end
 
-task :test => [:'test:activerecord', :'test:mongoid']
-
 # Mongodb
 directory "tmp/mongodb.data"
 desc 'Run mongodb in tmp/'

data/lib/simple_enum/accessors/accessor.rb

@@ -0,0 +1,55 @@
+module SimpleEnum
+  module Accessors
+    class Accessor
+      attr_reader :name, :enum, :source
+
+      def initialize(name, enum, source = nil, prefix = nil)
+        @name = name.to_s
+        @enum = enum
+        @source = source.to_s.presence || "#{name}#{SimpleEnum.suffix}"
+        @prefix = prefix
+      end
+
+      def prefix
+        @cached_prefix ||= @prefix && "#{@prefix == true ? name : @prefix}_" || ""
+      end
+
+      def read(object)
+        enum.key(read_before_type_cast(object))
+      end
+
+      def write(object, key)
+        write_after_type_cast(object, enum[key]) && key
+      end
+
+      def selected?(object, key = nil)
+        current = read_before_type_cast(object)
+        return current && current == enum[key] if key
+        current
+      end
+
+      def changed?(object)
+        object.attribute_changed?(source)
+      end
+
+      def was(object)
+        enum.key(object.attribute_was(source))
+      end
+
+      def to_s
+        name
+      end
+
+      private
+
+      def read_before_type_cast(object)
+        source == name ? object[source] : object.send(source)
+      end
+
+      def write_after_type_cast(object, value)
+        source == name ? object[source] = value : object.send("#{source}=", value)
+        value
+      end
+    end
+  end
+end

data/lib/simple_enum/accessors/ignore_accessor.rb

@@ -0,0 +1,11 @@
+require 'simple_enum/accessors/accessor'
+
+module SimpleEnum
+  module Accessors
+    class IgnoreAccessor < Accessor
+      def write(object, key)
+        super if !key || enum.include?(key)
+      end
+    end
+  end
+end

data/lib/simple_enum/accessors/whiny_accessor.rb

@@ -0,0 +1,12 @@
+require 'simple_enum/accessors/accessor'
+
+module SimpleEnum
+  module Accessors
+    class WhinyAccessor < Accessor
+      def write(object, key)
+        raise ArgumentError, "#{key} is not a valid enum value for #{enum}" if key && !enum.include?(key)
+        super
+      end
+    end
+  end
+end

data/lib/simple_enum/accessors.rb

@@ -0,0 +1,18 @@
+require 'simple_enum/accessors/accessor'
+require 'simple_enum/accessors/ignore_accessor'
+require 'simple_enum/accessors/whiny_accessor'
+
+module SimpleEnum
+  module Accessors
+    ACCESSORS = {
+      ignore: IgnoreAccessor,
+      whiny:  WhinyAccessor
+    }
+
+    def self.accessor(name, enum, options = {})
+      access = options.fetch(:accessor, SimpleEnum.accessor)
+      klass = ACCESSORS[access] || Accessor
+      klass.new(name, enum, options[:source], options[:prefix])
+    end
+  end
+end

data/lib/simple_enum/attribute.rb

@@ -0,0 +1,77 @@
+require 'active_support/core_ext/array'
+
+require 'simple_enum/enum'
+require 'simple_enum/hasher'
+require 'simple_enum/accessors'
+
+module SimpleEnum
+
+  # SimpleEnum::Attribute is the base class to be included in objects to get
+  # the #as_enum functionality. All the including class needs to provide is
+  # a setter and getter for `source`, by default the `source` is `<enum>_cd`.
+  # This is similar to how relations work in Rails, the idea is not taint the
+  # original method.
+  #
+  module Attribute
+    def as_enum(name, values, options = {})
+      options.assert_valid_keys(:source, :prefix, :with, :accessor, :map)
+
+      hash     = SimpleEnum::Hasher.map(values, options)
+      enum     = SimpleEnum::Enum.new(name, hash)
+      accessor = SimpleEnum::Accessors.accessor(name, enum, options)
+
+      generate_enum_class_accessors_for(enum, accessor)
+      generate_enum_instance_accessors_for(enum, accessor)
+
+      Array.wrap(options.fetch(:with, SimpleEnum.with)).each do |feature|
+        send "generate_enum_#{feature}_methods_for", enum, accessor
+      end
+
+      enum
+    end
+
+    private
+
+    def simple_enum_module
+      @simple_enum_module ||= Module.new.tap { |mod| include mod }
+    end
+
+    def generate_enum_class_accessors_for(enum, accessor)
+      name = accessor.name.pluralize
+      singleton_class.send(:define_method, name) { enum }
+      singleton_class.send(:define_method, "#{name}_accessor") { accessor }
+    end
+
+    def generate_enum_instance_accessors_for(enum, accessor)
+      simple_enum_module.module_eval do
+        define_method("#{accessor}")  { accessor.read(self) }
+        define_method("#{accessor}=") { |value| accessor.write(self, value) }
+      end
+    end
+
+    def generate_enum_dirty_methods_for(enum, accessor)
+      simple_enum_module.module_eval do
+        define_method("#{accessor}_changed?") { accessor.changed?(self) }
+        define_method("#{accessor}_was")      { accessor.was(self) }
+      end
+    end
+
+    def generate_enum_attribute_methods_for(enum, accessor)
+      simple_enum_module.module_eval do
+        define_method("#{accessor}?") { |value = nil| accessor.selected?(self, value) }
+        enum.each_pair do |key, value|
+          define_method("#{accessor.prefix}#{key}?") { accessor.selected?(self, key) }
+          define_method("#{accessor.prefix}#{key}!") { accessor.write(self, key) }
+        end
+      end
+    end
+
+    def generate_enum_scope_methods_for(enum, accessor)
+      return unless respond_to?(:scope)
+
+      enum.each_pair do |key, value|
+        scope "#{accessor.prefix}#{key}", -> { where(accessor.source => value) }
+      end
+    end
+  end
+end

data/lib/simple_enum/enum.rb

@@ -0,0 +1,37 @@
+require 'active_support/core_ext/string'
+
+module SimpleEnum
+  class Enum
+    attr_reader :name, :hash
+
+    def initialize(name, hash)
+      @name = name.to_s
+      @hash = hash
+    end
+
+    def include?(key)
+      hash.key?(key.to_s) || hash.value?(key)
+    end
+
+    def key(value)
+      key = hash.key(value)
+      key.to_sym if key
+    end
+
+    def value(key)
+      value = hash[key.to_s]
+      value = key if hash.value?(key)
+      value
+    end
+    alias_method :[], :value
+
+    def each_pair(&block)
+      hash.each_pair(&block)
+    end
+    alias_method :each, :each_pair
+
+    def to_s
+      name
+    end
+  end
+end

data/lib/simple_enum/hasher.rb

@@ -0,0 +1,26 @@
+module SimpleEnum
+  module Hasher
+    DefaultHasher = ->(values) {
+      Hash.new.tap do |enum_hash|
+        pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
+        pairs.each { |name, value| enum_hash[name.to_s] = value }
+      end
+    }
+
+    StringHasher = ->(values) {
+      Hash.new.tap do |enum_hash|
+        values.each { |name, *args| enum_hash[name.to_s] = name.to_s }
+      end
+    }
+
+    HASHERS = {
+      string: StringHasher
+    }
+
+    def self.map(values, options = {})
+      mapper = options.fetch(:map, SimpleEnum.builder)
+      mapper = HASHERS[mapper] || DefaultHasher unless mapper.respond_to?(:call)
+      mapper.call(values).freeze
+    end
+  end
+end

data/lib/simple_enum/mongoid.rb

@@ -23,29 +23,25 @@ module SimpleEnum
   #   as_enum :gender, [:female, :male], :field => { :type => Integer }
   #
   module Mongoid
-    extend ActiveSupport::Concern
-
-    included do
-      # create class level methods
-      class_attribute :simple_enum_definitions, :instance_writer => false, :instance_reader => false
+    def self.included(base)
+      base.extend SimpleEnum::Attribute
+      base.extend SimpleEnum::Translation
+      base.extend SimpleEnum::Mongoid::ClassMethods
     end
 
     module ClassMethods
-      include SimpleEnum::ClassMethods
-
       # Wrap method chain to create mongoid field and additional
       # column options
-      def as_enum_with_mongoid(enum_cd, values, options = {})
-        options = SimpleEnum.default_options.merge({ :column => "#{enum_cd}_cd" }).deep_merge(options)
-
-        # forward custom field options
+      def as_enum(name, values, options = {})
+        source = options[:source].to_s.presence || "#{name}#{SimpleEnum.suffix}"
         field_options = options.delete(:field)
-        field(options[:column], field_options.is_a?(Hash) ? field_options : {}) unless field_options === false
+        unless field_options === false
+          field_options ||= SimpleEnum.field
+          field(source, field_options) if field_options
+        end
 
-        # call original as_enum method
-        as_enum_without_mongoid(enum_cd, values, options)
+        super
       end
-      alias_method_chain :as_enum, :mongoid
     end
   end
 end

data/lib/simple_enum/translation.rb

@@ -0,0 +1,17 @@
+module SimpleEnum
+  module Translation
+    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
+  end
+end

data/lib/simple_enum/version.rb

@@ -1,5 +1,5 @@
 module SimpleEnum
 
-  # +SimpleEnum+ version string.
-  VERSION = "1.6.9"
+  # The current `SimpleEnum` version.
+  VERSION = "2.0.0.rc1"
 end