enumerize 2.4.0 → 2.5.0

data/README.md

@@ -2,6 +2,34 @@
 
 Enumerated attributes with I18n and ActiveRecord/Mongoid/MongoMapper/Sequel support
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Supported Versions](#supported-versions)
+- [Usage](#usage)
+- [Database support](#database-support)
+  - [ActiveRecord](#activerecord)
+  - [Mongoid](#mongoid)
+  - [MongoMapper](#mongomapper)
+- [I18n Support](#i18n-support)
+  - [I18n Helper Methods](#i18n-helper-methods)
+- [Boolean Helper Methods](#boolean-helper-methods)
+  - [Basic](#basic)
+  - [Predicate Methods](#predicate-methods)
+- [Optimzations and Tips](#optimzations-and-tips)
+  - [Extendable Module](#extendable-module)
+  - [Customizing Enumerize Value](#customizing-enumerize-value)
+  - [ActiveRecord scopes](#activerecord-scopes)
+  - [Array-like Attributes](#array-like-attributes)
+- [Forms](#forms)
+  - [SimpleForm](#simpleform)
+  - [Formtastic](#formtastic)
+- [Testing](#testing)
+  - [RSpec](#rspec)
+  - [Minitest with Shoulda](#minitest-with-shoulda)
+  - [Other Integrations](#other-integrations)
+- [Contributing](#contributing)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -17,7 +45,8 @@ Or install it yourself as:
     $ gem install enumerize
 
 ## Supported Versions
-- Ruby 2.5+
+
+- Ruby 2.6+
 - Rails 5.2+
 
 ## Usage
@@ -28,20 +57,23 @@ Basic:
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female]
+  enumerize :role, in: [:user, :admin]
 end
 ```
 
-Note that enumerized values are just identificators so if you want to use multi-word, etc. values you should use `I18n` feature.
+Note that enumerized values are just identificators so if you want to use multi-word, etc. values then you should use `I18n` feature.
 
+---
 
-ActiveRecord:
+## Database support
+
+### ActiveRecord
 
 ```ruby
 class CreateUsers < ActiveRecord::Migration
   def change
     create_table :users do |t|
-      t.string :sex
+      t.string :status
       t.string :role
 
       t.timestamps
@@ -52,7 +84,7 @@ end
 class User < ActiveRecord::Base
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], default: lambda { |user| SexIdentifier.sex_for_name(user.name).to_sym }
+  enumerize :status, in: [:student, :employed, :retired], default: lambda { |user| StatusIdentifier.status_for_age(user.age).to_sym }
 
   enumerize :role, in: [:user, :admin], default: :user
 end
@@ -64,13 +96,13 @@ end
 class User < ActiveRecord::Base
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], skip_validations: lambda { |user| user.new_record? }
+  enumerize :status, in: [:student, :employed, :retired], skip_validations: lambda { |user| user.new_record? }
 
   enumerize :role, in: [:user, :admin], skip_validations: true
 end
 ```
 
-Mongoid:
+### Mongoid
 
 ```ruby
 class User
@@ -82,7 +114,7 @@ class User
 end
 ```
 
-MongoMapper:
+### MongoMapper
 
 ```ruby
 class User
@@ -94,50 +126,54 @@ class User
 end
 ```
 
-I18n:
+---
+
+## I18n Support
 
 ```ruby
 en:
   enumerize:
     user:
-      sex:
-        male: "Male"
-        female: "Female"
+      status:
+        student: "Student"
+        employed: "Employed"
+        retired: "Retiree"
 ```
 
-or if you use `sex` attribute across several models you can use `defaults` scope:
+or if you use `status` attribute across several models you can use `defaults` scope:
 
 ```ruby
 en:
   enumerize:
     defaults:
-      sex:
-        male: "Male"
-        female: "Female"
+      status:
+        student: "Student"
+        employed: "Employed"
+        retired: "Retiree"
 ```
 
 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"]
+  enumerize :status, in: %w[student employed retired], i18n_scope: "status"
+  enumerize :roles, in: %w[user admin], i18n_scope: ["user.roles", "roles"]
 end
 
 # localization file
 en:
-  sex:
-    male: "Male"
-    female: "Female"
-  various:
-    colors:
-      black: "Black"
-  colors:
-    white: "White"
+  status:
+    student: "Student"
+    employed: "Employed"
+    retired: "Retiree"
+  user:
+    roles:
+      user: "User"
+  roles:
+    admin: "Admin"
 ```
 
 Note that if you want to use I18n feature with plain Ruby object don't forget to extend it with `ActiveModel::Naming`:
@@ -149,88 +185,120 @@ class User
 end
 ```
 
-get attribute value:
+### I18n Helper Methods
+
+#### \*\_text / .text
+
+Attribute's I18n text value:
+
+```ruby
+@user.status_text # or @user.status.text
+```
+
+#### values
+
+List of possible values for an enumerized attribute:
 
 ```ruby
-@user.sex_text # or @user.sex.text
+User.status.values # or User.enumerized_attributes[:status].values
+# => ['student', 'employed', 'retired']
 ```
 
-get all values for enumerized attribute:
+#### I18n text values
+
+List of possible I18n text values for an enumerized attribute:
 
 ```ruby
-User.sex.values # or User.enumerized_attributes[:sex].values
+User.status.values.collect(&:text)
+# => ['Student', 'Employed', 'Retiree']
 ```
 
-use it with forms (it supports `:only` and `:except` options):
+#### Form example
+
+Use it with forms (it supports `:only` and `:except` options):
 
 ```erb
 <%= form_for @user do |f| %>
-  <%= f.select :sex, User.sex.options %>
+  <%= f.select :status, User.status.options %>
 <% end %>
 ```
 
-Boolean methods:
+---
+
+## Boolean Helper Methods
+
+### Basic
 
 ```ruby
-user.sex = :male
-user.sex.male? #=> true
-user.sex.female? #=> false
+user.status = :student
+user.status.student? #=> true
+user.status.retired? #=> false
 ```
 
-Predicate methods:
+### Predicate Methods
 
 ```ruby
 class User
   extend Enumerize
 
-  enumerize :sex, in: %w(male female), predicates: true
+  enumerize :status, in: %w(student employed retired), predicates: true
 end
 
 user = User.new
 
-user.male?   # => false
-user.female? # => false
+user.student?  # => false
+user.employed? # => false
 
-user.sex = 'male'
+user.status = :student
 
-user.male?   # => true
-user.female? # => false
+user.student?  # => true
+user.employed? # => 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:
+#### Predicate Prefixes
 
 ```ruby
 class User
   extend Enumerize
 
-  enumerize :sex, in: %w(male female), predicates: { prefix: true }
+  enumerize :status, in: %w(student employed retired), predicates: { prefix: true }
 end
 
 user = User.new
-user.sex = 'female'
-user.sex_female? # => true
+user.status = 'student'
+user.status_student? # => true
 ```
+
 Use `:only` and `:except` options to specify what values create predicate methods for.
 
+---
+
+## Optimzations and Tips
+
+### Extendable Module
+
 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
+module RoleEnumerations
   extend Enumerize
 
-  enumerize :sex, in: %w[male female]
+  enumerize :roles, in: %w[user admin]
 end
 
-class Person
-  include PersonEnumerations
+class Buyer
+  include RoleEnumerations
 end
 
-class User
-  include PersonEnumerations
+class Seller
+  include RoleEnumerations
 end
 ```
 
+### Customizing Enumerize Value
+
 It's also possible to store enumerized attribute value using custom values (e.g. integers). You can pass a hash as `:in` option to achieve this:
 
 ```ruby
@@ -249,45 +317,49 @@ User.role.find_value(:user).value #=> 1
 User.role.find_value(:admin).value #=> 2
 ```
 
-ActiveRecord scopes:
+### ActiveRecord scopes:
+
+#### Basic
 
 ```ruby
 class User < ActiveRecord::Base
   extend Enumerize
-  enumerize :sex, :in => [:male, :female], scope: true
-  enumerize :status, :in => { active: 1, blocked: 2 }, scope: :having_status
+  enumerize :role, :in => [:user, :admin], scope: true
+  enumerize :status, :in => { student: 1, employed: 2, retired: 3 }, scope: :having_status
 end
 
-User.with_sex(:female)
-# SELECT "users".* FROM "users" WHERE "users"."sex" IN ('female')
+User.with_role(:admin)
+# SELECT "users".* FROM "users" WHERE "users"."role" IN ('admin')
 
-User.without_sex(:male)
-# SELECT "users".* FROM "users" WHERE "users"."sex" NOT IN ('male')
+User.without_role(:admin)
+# SELECT "users".* FROM "users" WHERE "users"."role" NOT IN ('admin')
 
-User.having_status(:blocked).with_sex(:male, :female)
-# SELECT "users".* FROM "users" WHERE "users"."status" IN (2) AND "users"."sex" IN ('male', 'female')
+User.having_status(:employed).with_role(:user, :admin)
+# SELECT "users".* FROM "users" WHERE "users"."status" IN (2) AND "users"."role" IN ('user', 'admin')
 ```
 
-Shallow scopes:
+#### Shallow Scopes
 
-Adds named scopes to the class directly
+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
+  enumerize :status, :in => [:student, :employed, :retired], scope: :shallow
+  enumerize :role, :in => { user: 1, admin: 2 }, scope: :shallow
 end
 
-User.male
-# SELECT "users".* FROM "users" WHERE "users"."sex" = 'male'
+User.student
+# SELECT "users".* FROM "users" WHERE "users"."status" = 'student'
 
-User.active
-# SELECT "users".* FROM "users" WHERE "users"."status" = 1
+User.admin
+# SELECT "users".* FROM "users" WHERE "users"."role" = 2
 ```
 
 :warning: It is not possible to define a scope when using the `:multiple` option. :warning:
 
+### Array-like Attributes
+
 Array-like attributes with plain ruby objects:
 
 ```ruby
@@ -322,22 +394,26 @@ get an array of all text values:
 Also, the reader method can be overridden, referencing the enumerized attribute value using `super`:
 
 ```ruby
-def sex
+def status
   if current_user.admin?
-    "Super#{super}"
+    "Super #{super}"
   else
     super
   end
 end
 ```
 
+---
+
+## Forms
+
 ### SimpleForm
 
 If you are using SimpleForm gem you don't need to specify input type (`:select` by default) and collection:
 
 ```erb
 <%= simple_form_for @user do |f| %>
-  <%= f.input :sex %>
+  <%= f.input :status %>
 <% end %>
 ```
 
@@ -345,7 +421,7 @@ and if you want it as radio buttons:
 
 ```erb
 <%= simple_form_for @user do |f| %>
-  <%= f.input :sex, :as => :radio_buttons %>
+  <%= f.input :status, :as => :radio_buttons %>
 <% end %>
 ```
 
@@ -357,7 +433,7 @@ If you are using Formtastic gem you also don't need to specify input type (`:sel
 
 ```erb
 <%= semantic_form_for @user do |f| %>
-  <%= f.input :sex %>
+  <%= f.input :status %>
 <% end %>
 ```
 
@@ -365,10 +441,14 @@ and if you want it as radio buttons:
 
 ```erb
 <%= semantic_form_for @user do |f| %>
-  <%= f.input :sex, :as => :radio %>
+  <%= f.input :status, :as => :radio %>
 <% end %>
 ```
 
+---
+
+## Testing
+
 ### RSpec
 
 Also you can use builtin RSpec matcher:
@@ -377,14 +457,14 @@ Also you can use builtin RSpec matcher:
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female]
+  enumerize :status, in: [:student, :employed, :retired]
 end
 
 describe User do
-  it { should enumerize(:sex) }
+  it { should enumerize(:status) }
 
   # or with RSpec 3 expect syntax
-  it { is_expected.to enumerize(:sex) }
+  it { is_expected.to enumerize(:status) }
 end
 ```
 
@@ -398,11 +478,11 @@ Use `in` to test usage of the `:in` option.
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female]
+  enumerize :status, in: [:student, :employed, :retired]
 end
 
 describe User do
-  it { should enumerize(:sex).in(:male, :female) }
+  it { should enumerize(:status).in(:student, :employed, :retired) }
 end
 ```
 
@@ -413,11 +493,11 @@ qualifier.
 class User
   extend Enumerize
 
-  enumerize :sex, in: { male: 0, female: 1 }
+  enumerize :role, in: { user: 0, admin: 1 }
 end
 
 describe User do
-  it { should enumerize(:sex).in(male: 0, female: 1) }
+  it { should enumerize(:role).in(user: 0, admin: 1) }
 end
 ```
 
@@ -429,11 +509,11 @@ Use `with_default` to test usage of the `:default` option.
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], default: :female
+  enumerize :role, in: [:user, :admin], default: :user
 end
 
 describe User do
-  it { should enumerize(:sex).in(:male, :female).with_default(:female) }
+  it { should enumerize(:user).in(:user, :admin).with_default(:user) }
 end
 ```
 
@@ -445,11 +525,11 @@ Use `with_i18n_scope` to test usage of the `:i18n_scope` option.
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], i18n_scope: 'sex'
+  enumerize :status, in: [:student, :employed, :retired], i18n_scope: 'status'
 end
 
 describe User do
-  it { should enumerize(:sex).in(:male, :female).with_i18n_scope('sex') }
+  it { should enumerize(:status).in(:student, :employed, :retired).with_i18n_scope('status') }
 end
 ```
 
@@ -461,11 +541,11 @@ Use `with_predicates` to test usage of the `:predicates` option.
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], predicates: true
+  enumerize :status, in: [:student, :employed, :retired], predicates: true
 end
 
 describe User do
-  it { should enumerize(:sex).in(:male, :female).with_predicates(true) }
+  it { should enumerize(:status).in(:student, :employed, :retired).with_predicates(true) }
 end
 ```
 
@@ -475,11 +555,11 @@ You can text prefixed predicates with the `with_predicates` qualifiers.
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], predicates: { prefix: true }
+  enumerize :status, in: [:student, :employed, :retired], predicates: { prefix: true }
 end
 
 describe User do
-  it { should enumerize(:sex).in(:male, :female).with_predicates(prefix: true) }
+  it { should enumerize(:status).in(:student, :employed, :retired).with_predicates(prefix: true) }
 end
 ```
 
@@ -491,25 +571,25 @@ Use `with_scope` to test usage of the `:scope` option.
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], scope: true
+  enumerize :status, in: [:student, :employed, :retired], scope: true
 end
 
 describe User do
-  it { should enumerize(:sex).in(:male, :female).with_scope(true) }
+  it { should enumerize(:status).in(:student, :employed, :retired).with_scope(true) }
 end
 ```
 
-You can text custom scope with the `with_scope` qualifiers.
+You can test a custom scope with the `with_scope` qualifiers.
 
 ```ruby
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], scope: :having_sex
+  enumerize :status, in: [:student, :employed], scope: :employable
 end
 
 describe User do
-  it { should enumerize(:sex).in(:male, :female).with_scope(scope: :having_sex) }
+  it { should enumerize(:status).in(:student, :employed, :retired).with_scope(scope: :employable) }
 end
 ```
 
@@ -521,11 +601,11 @@ Use `with_multiple` to test usage of the `:multiple` option.
 class User
   extend Enumerize
 
-  enumerize :sex, in: [:male, :female], multiple: true
+  enumerize :status, in: [:student, :employed, :retired], multiple: true
 end
 
 describe User do
-  it { should enumerize(:sex).in(:male, :female).with_multiple(true) }
+  it { should enumerize(:status).in(:student, :employed, :retired).with_multiple(true) }
 end
 ```
 
@@ -548,8 +628,9 @@ end
 
 Enumerize integrates with the following automatically:
 
-* [RailsAdmin](https://github.com/sferik/rails_admin/)
+- [RailsAdmin](https://github.com/sferik/rails_admin/)
 
+---
 
 ## Contributing
 

data/lib/enumerize/activerecord.rb

@@ -21,7 +21,11 @@ module Enumerize
           require 'enumerize/hooks/uniqueness'
 
           unless options[:multiple]
-            if ::ActiveRecord.version >= ::Gem::Version.new("6.1.0.alpha")
+            if ::ActiveRecord.version >= ::Gem::Version.new("7.0.0.alpha")
+              attribute(name) do |subtype|
+                Type.new(enumerized_attributes[name], subtype)
+              end
+            elsif ::ActiveRecord.version >= ::Gem::Version.new("6.1.0.alpha")
               decorate_attribute_type(name.to_s) do |subtype|
                 Type.new(enumerized_attributes[name], subtype)
               end
@@ -65,7 +69,7 @@ module Enumerize
         reloaded.class.enumerized_attributes.each do |attr|
           begin
             # Checks first if the enumerized attribute is in ActiveRecord::Store
-            store_attr, _ = reloaded.class.stored_attributes.detect do |store_attr, keys|
+            store_attr, _ = reloaded.class.stored_attributes.detect do |_store_attr, keys|
               keys.include?(attr.name)
             end
 

data/lib/enumerize/scope/activerecord.rb

@@ -42,6 +42,10 @@ module Enumerize
           define_singleton_method(value_obj) do
             where(attribute_name => value_obj.value)
           end
+
+          define_singleton_method("not_#{value_obj}") do
+            where.not(attribute_name => value_obj.value)
+          end
         end
       end
     end

data/lib/enumerize/scope/mongoid.rb

@@ -39,6 +39,10 @@ module Enumerize
           define_singleton_method(value_obj) do
             self.in(attribute_name => value_obj.value)
           end
+
+          define_singleton_method("not_#{value_obj}") do
+            self.not_in(attribute_name => value_obj.value)
+          end
         end
       end
     end

data/lib/enumerize/scope/sequel.rb

@@ -45,6 +45,10 @@ module Enumerize
           def_dataset_method(value_obj) do
             where(attribute_name => value_obj.value.to_s)
           end
+
+          def_dataset_method("not_#{value_obj}") do
+            exclude(attribute_name => value_obj.value.to_s)
+          end
         end
       end
     end

data/lib/enumerize/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Enumerize
-  VERSION = '2.4.0'
+  VERSION = '2.5.0'
 end