enumerize 0.3.0 → 2.3.1

data/README.md

@@ -1,6 +1,6 @@
-# Enumerize [![TravisCI](https://secure.travis-ci.org/brainspec/enumerize.png?branch=master)](http://travis-ci.org/brainspec/enumerize) [![Gemnasium](https://gemnasium.com/brainspec/enumerize.png)](https://gemnasium.com/brainspec/enumerize)
+# Enumerize [![TravisCI](https://secure.travis-ci.org/brainspec/enumerize.svg?branch=master)](http://travis-ci.org/brainspec/enumerize) [![Gemnasium](https://gemnasium.com/brainspec/enumerize.svg)](https://gemnasium.com/brainspec/enumerize)
 
-Enumerated attributes with I18n and ActiveRecord/Mongoid support
+Enumerated attributes with I18n and ActiveRecord/Mongoid/MongoMapper/Sequel support
 
 ## Installation
 
@@ -16,27 +16,57 @@ Or install it yourself as:
 
     $ gem install enumerize
 
+## Supported Versions
+- Ruby 2.2+
+- Rails 4.2+
+
 ## Usage
 
 Basic:
 
 ```ruby
 class User
-  include Enumerize
+  extend Enumerize
 
-  enumerize :sex, :in => [:male, :female]
+  enumerize :sex, in: [:male, :female]
 end
 ```
 
+Note that enumerized values are just identificators so if you want to use multi-word, etc. values you should use `I18n` feature.
+
+
 ActiveRecord:
 
+```ruby
+class CreateUsers < ActiveRecord::Migration
+  def change
+    create_table :users do |t|
+      t.string :sex
+      t.string :role
+
+      t.timestamps
+    end
+  end
+end
+
+class User < ActiveRecord::Base
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female], default: lambda { |user| SexIdentifier.sex_for_name(user.name).to_sym }
+
+  enumerize :role, in: [:user, :admin], default: :user
+end
+```
+
+:warning: By default, `enumerize` adds `inclusion` validation to the model. You can skip validations by passing `skip_validations` option. :warning:
+
 ```ruby
 class User < ActiveRecord::Base
-  include Enumerize
+  extend Enumerize
 
-  enumerize :sex, :in => [:male, :female]
+  enumerize :sex, in: [:male, :female], skip_validations: lambda { |user| user.new_record? }
 
-  enumerize :role, :in => [:user, :admin], :default => :user
+  enumerize :role, in: [:user, :admin], skip_validations: true
 end
 ```
 
@@ -45,10 +75,22 @@ Mongoid:
 ```ruby
 class User
   include Mongoid::Document
-  include Enumerize
+  extend Enumerize
 
   field :role
-  enumerize :role, :in => [:user, :admin], :default => :user
+  enumerize :role, in: [:user, :admin], default: :user
+end
+```
+
+MongoMapper:
+
+```ruby
+class User
+  include MongoMapper::Document
+  extend Enumerize
+
+  key :role
+  enumerize :role, in: [:user, :admin], default: :user
 end
 ```
 
@@ -63,14 +105,48 @@ en:
         female: "Female"
 ```
 
-or if you use `sex` attribute across several models you can use this:
+or if you use `sex` attribute across several models you can use `defaults` scope:
 
 ```ruby
 en:
   enumerize:
-    sex:
-      male: "Male"
-      female: "Female"
+    defaults:
+      sex:
+        male: "Male"
+        female: "Female"
+```
+
+You can also pass `i18n_scope` option to specify scope (or array of scopes) storing the translations.
+
+
+```ruby
+class Person
+  extend Enumerize
+  extend ActiveModel::Naming
+
+  enumerize :sex, in: %w[male female], i18n_scope: "sex"
+  enumerize :color, in: %w[black white], i18n_scope: ["various.colors", "colors"]
+end
+
+# localization file
+en:
+  sex:
+    male: "Male"
+    female: "Female"
+  various:
+    colors:
+      black: "Black"
+  colors:
+    white: "White"
+```
+
+Note that if you want to use I18n feature with plain Ruby object don't forget to extend it with `ActiveModel::Naming`:
+
+```ruby
+class User
+  extend Enumerize
+  extend ActiveModel::Naming
+end
 ```
 
 get attribute value:
@@ -85,7 +161,7 @@ get all values for enumerized attribute:
 User.sex.values # or User.enumerized_attributes[:sex].values
 ```
 
-use it with forms:
+use it with forms (it supports `:only` and `:except` options):
 
 ```erb
 <%= form_for @user do |f| %>
@@ -101,13 +177,49 @@ user.sex.male? #=> true
 user.sex.female? #=> false
 ```
 
+Predicate methods:
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: %w(male female), predicates: true
+end
+
+user = User.new
+
+user.male?   # => false
+user.female? # => false
+
+user.sex = 'male'
+
+user.male?   # => true
+user.female? # => false
+```
+:warning: If `enumerize` is used with Mongoid, it's not recommended to use `"writer"` as a field value since `writer?` is defined by Mongoid. [See more](https://github.com/brainspec/enumerize/issues/235). :warning:
+
+Using prefix:
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: %w(male female), predicates: { prefix: true }
+end
+
+user = User.new
+user.sex = 'female'
+user.sex_female? # => true
+```
+Use `:only` and `:except` options to specify what values create predicate methods for.
+
 To make some attributes shared across different classes it's possible to define them in a separate module and then include it into classes:
 
 ```ruby
 module PersonEnumerations
-  include Enumerize
+  extend Enumerize
 
-  enumerize :sex, :in => %w[male female]
+  enumerize :sex, in: %w[male female]
 end
 
 class Person
@@ -123,7 +235,99 @@ It's also possible to store enumerized attribute value using custom values (e.g.
 
 ```ruby
 class User < ActiveRecord::Base
-  enumerize :role, :in => {:user => 1, :admin => 2}
+  extend Enumerize
+
+  enumerize :role, in: {:user => 1, :admin => 2}
+end
+
+user = User.new
+user.role = :user
+user.role #=> 'user'
+user.role_value #=> 1
+
+User.role.find_value(:user).value #=> 1
+User.role.find_value(:admin).value #=> 2
+```
+
+ActiveRecord scopes:
+
+```ruby
+class User < ActiveRecord::Base
+  extend Enumerize
+  enumerize :sex, :in => [:male, :female], scope: true
+  enumerize :status, :in => { active: 1, blocked: 2 }, scope: :having_status
+end
+
+User.with_sex(:female)
+# SELECT "users".* FROM "users" WHERE "users"."sex" IN ('female')
+
+User.without_sex(:male)
+# SELECT "users".* FROM "users" WHERE "users"."sex" NOT IN ('male')
+
+User.having_status(:blocked).with_sex(:male, :female)
+# SELECT "users".* FROM "users" WHERE "users"."status" IN (2) AND "users"."sex" IN ('male', 'female')
+```
+
+Shallow scopes:
+
+Adds named scopes to the class directly
+
+```ruby
+class User < ActiveRecord::Base
+  extend Enumerize
+  enumerize :sex, :in => [:male, :female], scope: :shallow
+  enumerize :status, :in => { active: 1, blocked: 2 }, scope: :shallow
+end
+
+User.male
+# SELECT "users".* FROM "users" WHERE "users"."sex" = 'male'
+
+User.active
+# SELECT "users".* FROM "users" WHERE "users"."status" = 1
+```
+
+:warning: It is not possible to define a scope when using the `:multiple` option. :warning:
+
+Array-like attributes with plain ruby objects:
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :interests, in: [:music, :sports], multiple: true
+end
+
+user = User.new
+user.interests << :music
+user.interests << :sports
+```
+
+and with ActiveRecord:
+
+```ruby
+class User < ActiveRecord::Base
+  extend Enumerize
+
+  serialize :interests, Array
+  enumerize :interests, in: [:music, :sports], multiple: true
+end
+```
+
+get an array of all text values:
+
+```ruby
+@user.interests.texts # shortcut for @user.interests.map(&:text)
+```
+
+Also, the reader method can be overridden, referencing the enumerized attribute value using `super`:
+
+```ruby
+def sex
+  if current_user.admin?
+    "Super#{super}"
+  else
+    super
+  end
 end
 ```
 
@@ -145,6 +349,8 @@ and if you want it as radio buttons:
 <% end %>
 ```
 
+Please note that Enumerize overwrites the I18n keys of SimpleForm collections. The enumerized keys are used instead of the SimpleForm ones for inputs concerning enumerized attributes. If you don't want this just pass `:collection` option to the `input` call.
+
 ### Formtastic
 
 If you are using Formtastic gem you also don't need to specify input type (`:select` by default) and collection:
@@ -163,6 +369,188 @@ and if you want it as radio buttons:
 <% end %>
 ```
 
+### RSpec
+
+Also you can use builtin RSpec matcher:
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female]
+end
+
+describe User do
+  it { should enumerize(:sex) }
+
+  # or with RSpec 3 expect syntax
+  it { is_expected.to enumerize(:sex) }
+end
+```
+
+#### Qualifiers
+
+##### in
+
+Use `in` to test usage of the `:in` option.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female]
+end
+
+describe User do
+  it { should enumerize(:sex).in(:male, :female) }
+end
+```
+
+You can test enumerized attribute value using custom values with the `in`
+qualifier.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: { male: 0, female: 1 }
+end
+
+describe User do
+  it { should enumerize(:sex).in(male: 0, female: 1) }
+end
+```
+
+##### with_default
+
+Use `with_default` to test usage of the `:default` option.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female], default: :female
+end
+
+describe User do
+  it { should enumerize(:sex).in(:male, :female).with_default(:female) }
+end
+```
+
+##### with_i18n_scope
+
+Use `with_i18n_scope` to test usage of the `:i18n_scope` option.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female], i18n_scope: 'sex'
+end
+
+describe User do
+  it { should enumerize(:sex).in(:male, :female).with_i18n_scope('sex') }
+end
+```
+
+##### with_predicates
+
+Use `with_predicates` to test usage of the `:predicates` option.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female], predicates: true
+end
+
+describe User do
+  it { should enumerize(:sex).in(:male, :female).with_predicates(true) }
+end
+```
+
+You can text prefixed predicates with the `with_predicates` qualifiers.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female], predicates: { prefix: true }
+end
+
+describe User do
+  it { should enumerize(:sex).in(:male, :female).with_predicates(prefix: true) }
+end
+```
+
+##### with_scope
+
+Use `with_scope` to test usage of the `:scope` option.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female], scope: true
+end
+
+describe User do
+  it { should enumerize(:sex).in(:male, :female).with_scope(true) }
+end
+```
+
+You can text custom scope with the `with_scope` qualifiers.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female], scope: :having_sex
+end
+
+describe User do
+  it { should enumerize(:sex).in(:male, :female).with_scope(scope: :having_sex) }
+end
+```
+
+##### with_multiple
+
+Use `with_multiple` to test usage of the `:multiple` option.
+
+```ruby
+class User
+  extend Enumerize
+
+  enumerize :sex, in: [:male, :female], multiple: true
+end
+
+describe User do
+  it { should enumerize(:sex).in(:male, :female).with_multiple(true) }
+end
+```
+
+### Minitest with Shoulda
+
+You can use the RSpec matcher with shoulda in your tests by adding two lines in your `test_helper.rb` inside `class ActiveSupport::TestCase` definition:
+
+```ruby
+class ActiveSupport::TestCase
+  ActiveRecord::Migration.check_pending!
+
+  require 'enumerize/integrations/rspec'
+  extend Enumerize::Integrations::RSpec
+
+  ...
+end
+```
+
+### Other Integrations
+
+Enumerize integrates with the following automatically:
+
+* [RailsAdmin](https://github.com/sferik/rails_admin/)
+
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,11 +1,17 @@
 #!/usr/bin/env rake
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 
 require 'rake/testtask'
+require 'rspec/core/rake_task'
+
 Rake::TestTask.new do |t|
   t.libs << 'test'
   t.pattern = 'test/*_test.rb'
   t.verbose = true
 end
 
-task :default => :test
+RSpec::Core::RakeTask.new
+
+task :default => [:test, :spec]

data/enumerize.gemspec

@@ -4,8 +4,9 @@ require File.expand_path('../lib/enumerize/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["Sergey Nartimov"]
   gem.email         = "team@brainspec.com"
-  gem.description   = %q{Enumerated attributes with I18n and ActiveRecord/Mongoid support}
-  gem.summary       = %q{Enumerated attributes with I18n and ActiveRecord/Mongoid support}
+  gem.licenses      = ['MIT']
+  gem.description   = %q{Enumerated attributes with I18n and ActiveRecord/Mongoid/MongoMapper support}
+  gem.summary       = %q{Enumerated attributes with I18n and ActiveRecord/Mongoid/MongoMapper support}
   gem.homepage      = "https://github.com/brainspec/enumerize"
 
   gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
@@ -15,5 +16,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Enumerize::VERSION
 
-  gem.add_dependency('activesupport', '>= 3.1.3')
+  gem.required_ruby_version = '>= 1.9.3'
+
+  gem.add_dependency('activesupport', '>= 3.2')
 end

data/lib/enumerize/activemodel.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Enumerize
+  module ActiveModelAttributesSupport
+    def enumerize(name, options={})
+      super
+
+      _enumerize_module.dependent_eval do
+        if self.included_modules.include? ::ActiveModel::Attributes
+          include InstanceMethods
+
+          attribute name, Enumerize::ActiveModelAttributesSupport::Type.new(enumerized_attributes[name])
+        end
+      end
+    end
+
+    module InstanceMethods
+      # https://github.com/brainspec/enumerize/issues/74
+      def write_attribute(attr_name, value, *options)
+        if self.class.enumerized_attributes[attr_name]
+          _enumerized_values_for_validation[attr_name.to_s] = value
+        end
+
+        super
+      end
+    end
+
+    class Type < ActiveModel::Type::Value
+      def type
+        :enumerize
+      end
+
+      def initialize(attr)
+        @attr = attr
+      end
+
+      def serialize(value)
+        v = @attr.find_value(value)
+        v && v.value
+      end
+
+      def deserialize(value)
+        @attr.find_value(value)
+      end
+    end
+  end
+end