simple_enum 1.6.9 → 2.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 18d5bbe70d30e114c220f17681c172597163bfd0
-  data.tar.gz: e9ae250d080b7f6efa78928005df4b9f36ca9ffb
+  metadata.gz: ead9e5d2a63ed29727c934fa36cf37a544dacd65
+  data.tar.gz: 89da3f9fa8ee6e7ef19f028bed68167d8e592f55
 SHA512:
-  metadata.gz: 9150ad6487da910c1b6319030102a2e8504f0775e995f2e4cc8ca09e6198e91176e08d6fa8b9aca468aa0de43cdb5a4168d7b802c0ca159d2a98b860810666a7
-  data.tar.gz: 14577d002d9996148f4e321624ecaba8cf705de2ff8162f06c5aca7940b620dfbf1cda88c3c182aa10eed11ce8257d129e4cc4f870a77f123c0b996a86f97205
+  metadata.gz: 834dd3a7c5e92d44c0317ac88356af38a56fdc0581dd4b4101583dbb494f0fa1d027e88f2bd1d9d134783bab08171ff998d604d78db5ce3588cec24c301f4b1e
+  data.tar.gz: a4947957c71ddeb731981403288daea009f8e6b565657cf04a140de9201cf507e2f0c81490981b2d481f903035ac608572c89e3b62b8b4499d671775f4ffa6a9

data/.gitignore

@@ -6,4 +6,5 @@ pkg
 .*.sw?
 tmp
 Gemfile.lock
+gemfiles/*.lock
 :memory*

data/Gemfile

@@ -1,11 +1,14 @@
 source "http://rubygems.org"
 
-gemspec
+gem 'activesupport', '~> 5.0.0'
+gem 'activerecord', '~> 5.0.0'
 
-# Fix at 1.9.x, because 1.10 errors on jruby
-gem 'mongo', '~> 1.9.0', :platform => :jruby
+gemspec
 
 # some development deps
-gem 'activerecord-jdbcsqlite3-adapter', :platform => :jruby
-gem 'sqlite3', :platform => :ruby
-gem 'bson_ext', :platform => :ruby
+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) 2015 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,331 @@
+SimpleEnum
+==========
+
+[![Gem Version](https://badge.fury.io/rb/simple_enum.svg)](https://badge.fury.io/rb/simple_enum)
+[![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.svg)](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.3.0' , 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.genders.values_at(:male, :female)  # => [0, 1] (since 2.1.0)
+User.females                            # => #<ActiveRecord::Relation:0x0.....> (WHERE gender_cd = 1)
+```
+
+By default, scope names are generated as pluralized forms of the defined enum values e.g.
+
+```ruby
+class Booking < ActiveRecord::Base
+  as_enum :status, %i{active cancelled pending}
+end
+```
+
+would generate the following:
+```ruby
+Booking.actives     # => #<ActiveRecord::Relation:0x0.....> (WHERE status_cd = 1)
+Booking.cancelleds  # => #<ActiveRecord::Relation:0x0.....> (WHERE status_cd = 2)
+Booking.pendings    # => #<ActiveRecord::Relation:0x0.....> (WHERE status_cd = 3)
+```
+
+By setting `pluralize_scopes: false` will not generate pluralized versions of scopes e.g.
+
+```ruby
+class Booking < ActiveRecord::Base
+  as_enum :status, %i{active cancelled pending}, pluralize_scopes: false
+end
+```
+
+would generate the following:
+```ruby
+Booking.active     # => #<ActiveRecord::Relation:0x0.....> (WHERE status_cd = 1)
+Booking.cancelled  # => #<ActiveRecord::Relation:0x0.....> (WHERE status_cd = 2)
+Booking.pending    # => #<ActiveRecord::Relation:0x0.....> (WHERE status_cd = 3)
+```
+
+### 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, beware 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:
+  ```ruby
+  class User < ActiveRecord::Base
+    as_enum :gender, %w{male female}, prefix: true
+  end
+
+  jane = User.new gender: :female
+  jane.gender_female? # => true
+  User.gender_females  # => <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 = [:attribute, :scope]
+  ```
+
+### View Helpers
+
+Require translated enum values? See [SimpleEnum::ViewHelpers][VE.rb] for more
+details and functions. _Disclaimer_: these methods are release candidate quality
+so expect them to change in future versions of SimpleEnum.
+
+- Translate the current value in a view:
+
+  ```ruby
+  translate_enum user, :gender # => "Frau" # assuming :de and translations exist
+  te user, :gender # translate_enum is also aliased to te
+  ```
+
+  Provide translations in the i18n yaml file like:
+
+  ```ruby
+    de:
+      enums:
+        gender:
+          female: 'Frau'
+          male: 'Mann'
+  ```
+
+- Build a select tag with a translated dropdown and symbol as value:
+
+  ```ruby
+  select :user, :gender, enum_option_pairs(User, :gender)
+  ```
+
+- ...and one with the index as value:
+
+  ```ruby
+  select :user, :gender_cd, enum_option_pairs(User, :gender, true)
+  ```
+
+## Extensions
+
+`simple_enum` provides hooks to extend its functionality, starting with 2.3.0
+the following extensions can be used:
+
+- **Multi-select enum** support for SimpleEnum:
+  [simple_enum-multiple](https://github.com/bbtfr/simple_enum-multiple)
+- **Persistence values**, i.e. store values in the DB:
+  [simple_enum-persistence](https://github.com/bbtfr/simple_enum-persistence)
+- **Scopes**, scopes helper for ActiveRecord enum attributes:
+  [simple_enum-scopes](https://github.com/aovertus/simple_enum-scopes)
+
+## 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.females # => returns an ActiveRecord::Relation
+```
+
+Contributors
+------------
+
+- [@dmitry](https://github.com/dmitry) - bugfixes and other improvements
+- [@tarsolya](https://github.com/tarsolya) - implemented all the ruby 1.9 and rails 3 goodness!
+- [@dbalatero](https://github.com/dbalatero) - rails 2.3.5 bugfix & validator fixes
+- [@johnthethird](https://github.com/johnthethird) - feature for `_for_select` to return the values
+- @sinsiliux - ruby 1.9 fixes and removed AR dependency
+- [@sled](https://github.com/sled) - mongoid support
+- [@abrom](https://github.com/abrom) - `find_by_...` method
+- [@mhuggins](https://github.com/mhuggins) - translations fixes
+- [@patbenatar](https://github.com/patbenatar) - for helping move towards 2.0 (scopes et all)
+- [@abacha](https://github.com/abacha) - translation helpers, README fixes
+- [@bbtfr](https://github.com/bbtfr) - for support, ideas and pushing extensions
+- and all others: https://github.com/lwe/simple_enum/graphs/contributors thanks
+
+License & Copyright
+-------------------
+
+Copyright (c) 2011-2015 by Lukas Westermann, Licensed under MIT License (see LICENSE file)
+
+[VE.rb]: https://github.com/lwe/simple_enum/blob/master/lib/simple_enum/view_helpers.rb

data/Rakefile

@@ -5,30 +5,22 @@ require 'rake/testtask'
 Bundler::GemHelper.install_tasks
 
 desc 'Default: run all unit tests for both ActiveRecord & Mongoid.'
-task :default => :test
+task :default => :'spec:all'
 
-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 basic specs only (skips mongoid)'
+task :spec => :'spec:basic'
 
-  desc 'Run all unit tests for ActiveRecord'
-  task :activerecord do |t|
-    ENV['SIMPLE_ENUM_TEST_ORM'] = 'active_record'
-    Rake::Task['test:units'].execute
+namespace :spec do
+  desc 'Run all specs'
+  task :all do
+    sh 'bundle', 'exec', 'rspec', 'spec/'
   end
 
-  desc 'Run all unit tests for Mongoid'
-  task :mongoid do |t|
-    ENV['SIMPLE_ENUM_TEST_ORM'] = 'mongoid'
-    Rake::Task['test:units'].execute
+  task :basic do
+    sh 'bundle', 'exec', 'rspec', 'spec/', '-t', '~mongoid'
   end
 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,61 @@
+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.send(:attribute_changed?, source)
+      end
+
+      def was(object)
+        changes = object.send(:changed_attributes)
+        key = changes.fetch(source, read_before_type_cast(object))
+        enum.key(key) if key
+      end
+
+      def scope(relation, value)
+        relation.where(source => value)
+      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,28 @@
+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
+
+  # Public: Extension method to register a custom accessor.
+  #
+  # key - The Symbol of the accessor key, e.g. `:bitwise`
+  # clazz - The Class with the accessor implementation
+  #
+  # Returns nothing
+  def self.register_accessor(key, clazz)
+    Accessors::ACCESSORS[key] = clazz
+  end
+end

data/lib/simple_enum/attribute.rb

@@ -0,0 +1,109 @@
+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
+    # Registered registrator methods from extensions
+    EXTENSIONS = []
+
+    def as_enum(name, values, options = {})
+      options.assert_valid_keys(:source, :prefix, :with, :accessor, :map, :pluralize_scopes)
+
+      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)
+      generate_additional_enum_methods_for(enum, accessor, options)
+
+      EXTENSIONS.uniq.each do |extension|
+        send "generate_enum_#{extension}_extension_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) }
+        define_method("#{accessor}?") { |value = nil| accessor.selected?(self, value) }
+      end
+    end
+
+    def generate_additional_enum_methods_for(enum, accessor, options)
+      with_options = Array.wrap(options.fetch(:with, SimpleEnum.with))
+      scope_option, feature_options = with_options.partition { |option| option == :scope }
+
+      feature_options.each do |feature|
+        send "generate_enum_#{feature}_methods_for", enum, accessor
+      end
+
+      unless scope_option.empty?
+        pluralize_scopes = options.fetch(:pluralize_scopes, SimpleEnum.pluralize_scopes)
+        generate_enum_scope_methods_for(enum, accessor, pluralize_scopes)
+      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
+        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, pluralize_scopes)
+      return unless respond_to?(:scope)
+
+      enum.each_pair do |key, value|
+        scope_key = pluralize_scopes ? key.pluralize : key
+        scope "#{accessor.prefix}#{scope_key}", -> { accessor.scope(self, value) }
+      end
+    end
+  end
+
+  # Public: Register a generator method and add module as part of
+  # SimpleEnum::Attribute. The generator method is called after all default
+  # generators have been created, this allows to override/change existing methods.
+  #
+  # name - The Symbol with the name of the extension
+  # mod - The Module implementing `generate_enum_{name}_extension_for` method
+  #
+  # Returns nothing
+  def self.register_generator(name, mod)
+    Attribute.send :include, mod
+    Attribute::EXTENSIONS << name.to_s
+  end
+end