enumerate_it 4.0.0 → 4.2.0

data/README.md

@@ -4,19 +4,44 @@ Enumerations for Ruby with some magic powers! 🎩
 
 [![CI Status](https://github.com/lucascaton/enumerate_it/workflows/CI/badge.svg)](https://github.com/lucascaton/enumerate_it/actions?query=workflow%3ACI)
 [![Gem Version](https://badge.fury.io/rb/enumerate_it.svg)](https://rubygems.org/gems/enumerate_it)
-[![Code Climate](https://codeclimate.com/github/lucascaton/enumerate_it/badges/gpa.svg)](https://codeclimate.com/github/lucascaton/enumerate_it)
 [![Downloads](https://img.shields.io/gem/dt/enumerate_it.svg)](https://rubygems.org/gems/enumerate_it)
 [![Changelog](https://img.shields.io/badge/changelog--brightgreen.svg?style=flat)](https://github.com/lucascaton/enumerate_it/releases)
 
-**EnumerateIt** helps you to declare and use enumerations in a very simple and
+**EnumerateIt** helps you declare and use enumerations in a very simple and
 flexible way.
 
-### Why would I want a gem if Rails already has native enumerations support?
+### Why would I want a gem if Rails already has native enumeration support?
 
 Firstly, although **EnumerateIt** works well with **Rails**, it isn't required!
-It means you can add it to any **Ruby** project! Secondly, you can
-[define your enumerations in classes](https://github.com/lucascaton/enumerate_it#creating-enumerations),
-so you can **add behaviour** and also **reuse** them! 😀
+This means you can add it to any **Ruby** project! Secondly, you can
+[define your enumerations in classes](#creating-enumerations), allowing you to
+**add behavior** and **reuse** them! 😀
+
+At a glance:
+
+```ruby
+class RelationshipStatus < EnumerateIt::Base
+  associate_values :single, :married, :divorced
+
+  custom_helpers do
+    def ever_married?(value)
+      [MARRIED, DIVORCED].include?(value)
+    end
+  end
+end
+
+class Person < ApplicationRecord
+  has_enumeration_for :relationship_status, create_helpers: true, create_scopes: true
+end
+
+person = Person.new(relationship_status: RelationshipStatus::MARRIED)
+
+person.married? #=> true
+person.ever_married? #=> true
+person.relationship_status_humanize #=> 'Married'
+Person.married.to_sql #=> SELECT "people".* FROM "people" WHERE "people"."relationship_status" = "married"
+RelationshipStatus.to_a #=> [['Divorced', 'divorced'], ['Married', 'married'], ['Single', 'single']]
+```
 
 ---
 
@@ -24,21 +49,18 @@ so you can **add behaviour** and also **reuse** them! 😀
 
 ## Table of Contents
 
-- [EnumerateIt](#enumerateit)
-  - [Why would I want a gem if Rails already has native enumerations support?](#why-would-i-want-a-gem-if-rails-already-has-native-enumerations-support)
-  - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
   - [Using with Rails](#using-with-rails)
   - [Creating enumerations](#creating-enumerations)
     - [Sorting enumerations](#sorting-enumerations)
   - [Using enumerations](#using-enumerations)
   - [FAQ](#faq)
-    - [Why define enumerations outside the class that uses them?](#why-define-enumerations-outside-the-class-that-uses-them)
-    - [Can I use `enumerate_it` gem without Rails?](#can-i-use-enumerate_it-gem-without-rails)
-    - [What versions of Ruby and Rails are supported?](#what-versions-of-ruby-and-rails-are-supported)
-    - [Can I set a value to always be at the end of a sorted list?](#can-i-set-a-value-to-always-be-at-the-end-of-a-sorted-list)
+      - [Why define enumerations outside the class that uses them?](#why-define-enumerations-outside-the-class-that-uses-them)
+      - [Can I use `enumerate_it` gem without Rails?](#can-i-use-enumerate_it-gem-without-rails)
+      - [What versions of Ruby and Rails are supported?](#what-versions-of-ruby-and-rails-are-supported)
+      - [Can I set a value to always be at the end of a sorted list?](#can-i-set-a-value-to-always-be-at-the-end-of-a-sorted-list)
   - [I18n](#i18n)
-    - [Translate a name-spaced enumeration](#translate-a-name-spaced-enumeration)
+    - [Translate a namespaced enumeration](#translate-a-namespaced-enumeration)
   - [Handling a legacy database](#handling-a-legacy-database)
   - [Changelog](#changelog)
   - [Note on Patches/Pull Requests](#note-on-patchespull-requests)
@@ -68,11 +90,11 @@ rails generate enumerate_it:enum --help
 
 ## Creating enumerations
 
-Enumerations are created as classes and you should put them inside
+Enumerations are created as classes and should be placed inside the
 `app/enumerations` folder.
 
-You can pass an array of symbols, so that the respective value for each symbol
-will be the stringified version of the symbol itself:
+You can pass an array of symbols, where each symbol's value will be its
+stringified version:
 
 ```ruby
 class RelationshipStatus < EnumerateIt::Base
@@ -84,9 +106,9 @@ class RelationshipStatus < EnumerateIt::Base
 end
 ```
 
-This will create some nice stuff:
+This will generate some nice stuff:
 
-- Each enumeration's value will turn into a constant:
+- Constants for each enumeration value:
 
   ```ruby
   RelationshipStatus::SINGLE
@@ -96,22 +118,21 @@ This will create some nice stuff:
   #=> 'married'
   ```
 
-- You can retrieve a list with all the enumeration codes:
+- A list of all enumeration codes:
 
   ```ruby
   RelationshipStatus.list
   #=> ['divorced', 'married', 'single']
   ```
 
-- You can retrieve a JSON with all the enumeration codes:
+- A JSON representation:
 
   ```ruby
   RelationshipStatus.to_json
   #=> "[{\"value\":\"divorced\",\"label\":\"Divorced\"},{\"value\":\"married\", ...
   ```
 
-- You can get an array of options, ready to use with the `select`, `select_tag`,
-  etc. family of Rails helpers.
+- An array of options for Rails helpers, such as `select`, `select_tag`, etc.:
 
   ```ruby
   RelationshipStatus.to_a
@@ -166,11 +187,10 @@ This will create some nice stuff:
 
 ### Sorting enumerations
 
-When calling methods like `to_a`, `to_json` and `list`, the returned values will
-be sorted by default in the same order passed to `associate_values` call.
+When calling methods like `to_a`, `to_json` and `list`, values are sorted in the
+order they were passed to `associate_values`, by default.
 
-However, if you want to overwrite the default sort mode, you can use the
-`sort_by` class method:
+You can override this with the `sort_by` class method:
 
 ```ruby
 class RelationshipStatus < EnumerateIt::Base
@@ -180,18 +200,20 @@ class RelationshipStatus < EnumerateIt::Base
 end
 ```
 
-The `sort_by` method accepts one of the following values:
+Accepted values for `sort_by`:
 
-| Value          | Behavior                                                                                     |
-| :------------- | :------------------------------------------------------------------------------------------- |
-| `:none`        | The default behavior, will return values in order that was passed to `associate_values` call |
-| `:name`        | Will sort the returned values based on the name of each enumeration option                   |
-| `:translation` | will sort the returned values based on their translations                                    |
-| `:value`       | See [Handling a legacy database](#handling-a-legacy-database) section for more details       |
+| Value                    | Behavior                                                                              |
+| :----------------------- | :------------------------------------------------------------------------------------ |
+| `:none`                  | Uses the original order from `associate_values`                                       |
+| `:name`                  | Sorts by the name of each enumeration option                                          |
+| `:translation`           | Sorts by their translations                                                           |
+| `:normalize_translation` | Sorts by their translations normalized with NFKD unicode method (without accents)     |
+| `:value`                 | Sorts by assigned values (useful for [legacy databases](#handling-a-legacy-database)) |
 
 ## Using enumerations
 
-The cool part is that you can use these enumerations with any class:
+The cool part is that you can use these enumerations in any class, whether
+ActiveRecord-based or not:
 
 ```ruby
 # ActiveRecord instance
@@ -210,11 +232,13 @@ class Person
 end
 ```
 
-> **Note:** **EnumerateIt** will try to load an enumeration class based on the
-> camelized attribute name. If you have a different name, you can specify it by
-> using the `with` option:
+<!-- prettier-ignore -->
+> [!NOTE]
+> If the enumeration class name differs from the attribute name, use the `with` option:
 >
-> `has_enumeration_for :relationship_status, with: RelationshipStatus`
+> ```ruby
+> has_enumeration_for :relationship_status, with: RelationshipStatus
+> ```
 
 This will create:
 
@@ -234,7 +258,7 @@ This will create:
   p = Person.new
   p.relationship_status = RelationshipStatus::DIVORCED
   p.relationship_status_humanize
-  #=> 'Divorciado'
+  #=> 'Divorciado' # with a pt-BR locale loaded
   ```
 
 - The associated enumerations, which can be retrieved with the `enumerations`
@@ -340,6 +364,63 @@ This will create:
   #=> true
   ```
 
+  <!-- prettier-ignore -->
+  > [!IMPORTANT]
+  > On ActiveRecord objects, mutator methods like `married!` call `save!`
+  > immediately, running callbacks and raising on validation failure. They are
+  > not pure setters.
+
+  You can also define custom helper methods on the enumeration class using
+  a `custom_helpers` block:
+
+  ```ruby
+  class RelationshipStatus < EnumerateIt::Base
+    associate_values :single, :married, :divorced
+
+    custom_helpers do
+      def ever_married?(value)
+        [MARRIED, DIVORCED].include?(value)
+      end
+    end
+  end
+  ```
+
+  These become class methods on the enumeration:
+
+  ```ruby
+  RelationshipStatus.ever_married?(RelationshipStatus::MARRIED)  #=> true
+  RelationshipStatus.ever_married?(RelationshipStatus::DIVORCED) #=> true
+  RelationshipStatus.ever_married?(RelationshipStatus::SINGLE)   #=> false
+  ```
+
+  When `create_helpers: true` is used, they also become instance methods on the
+  model:
+
+  ```ruby
+  class Person < ApplicationRecord
+    has_enumeration_for :relationship_status, with: RelationshipStatus, create_helpers: true
+  end
+
+  person = Person.new(relationship_status: RelationshipStatus::DIVORCED)
+  person.ever_married? #=> true
+  ```
+
+  The `prefix` option also applies to custom helpers:
+
+  ```ruby
+  class Person < ApplicationRecord
+    has_enumeration_for :relationship_status,
+      with: RelationshipStatus, create_helpers: { prefix: true }
+  end
+
+  person = Person.new(relationship_status: RelationshipStatus::DIVORCED)
+  person.relationship_status_ever_married? #=> true
+  ```
+
+  Custom helper methods return `nil` when the attribute is `nil`. If a method
+  name collides with an already-defined class method on the enumeration, an
+  `ArgumentError` is raised at load time.
+
 - A scope method for each enumeration option if you pass the `create_scopes`
   option as `true`:
 
@@ -349,7 +430,7 @@ This will create:
   end
 
   Person.married.to_sql
-  #=> SELECT "users".* FROM "users" WHERE "users"."relationship_status" = "married"
+  #=> SELECT "people".* FROM "people" WHERE "people"."relationship_status" = "married"
   ```
 
   The `:create_scopes` also accepts `prefix` option.
@@ -406,6 +487,12 @@ This will create:
   #=> true
   ```
 
+  <!-- prettier-ignore -->
+  > [!NOTE]
+  > `skip_validation: true` disables all validations added by EnumerateIt,
+  > including the presence validation from `required: true`. If both are
+  > passed, `skip_validation` wins and `required` is silently ignored.
+
 Remember that you can add validations to any kind of class and not only
 `ActiveRecord` ones.
 
@@ -414,7 +501,7 @@ Remember that you can add validations to any kind of class and not only
 #### Why define enumerations outside the class that uses them?
 
 - It's clearer.
-- You can add behaviour to the enumeration class.
+- You can add behavior to the enumeration class.
 - You can reuse the enumeration inside other classes.
 
 #### Can I use `enumerate_it` gem without Rails?
@@ -424,7 +511,7 @@ You sure can! 😄
 #### What versions of Ruby and Rails are supported?
 
 - **Ruby**: `3.0+`
-- **Rails** `6.0+`
+- **Rails**: `6.0+`
 
 All versions are tested via
 [GitHub Actions](https://github.com/lucascaton/enumerate_it/blob/HEAD/.github/workflows/ci.yml).
@@ -436,7 +523,7 @@ Yes,
 
 ## I18n
 
-I18n lookup is provided on both `_humanized` and `Enumeration#to_a` methods,
+I18n lookup is provided for both `_humanize` and `Enumeration#to_a` methods,
 given the hash key is a Symbol. The I18n strings are located on
 `enumerations.<enumeration_name>.<key>`:
 
@@ -458,11 +545,11 @@ end
 
 p = Person.new
 p.relationship_status = RelationshipStatus::MARRIED
-p.relationship_status_humanize # Existent key
+p.relationship_status_humanize # Key found in the locale file
 #=> 'Casado'
 
 p.relationship_status = RelationshipStatus::SINGLE
-p.relationship_status_humanize # Non-existent key
+p.relationship_status_humanize # Key missing, falls back to the humanized name
 #=> 'Single'
 ```
 
@@ -474,10 +561,10 @@ RelationshipStatus.t(status)
 #=> 'Casado'
 ```
 
-### Translate a name-spaced enumeration
+### Translate a namespaced enumeration
 
 In order to translate an enumeration in a specific namespace (say
-`Design::Color`), you can add the following:
+`Design::Color`), use the following structure:
 
 ```yaml
 pt-BR:
@@ -555,13 +642,12 @@ you can see them on the [releases page](../../releases).
 - Add tests for it. This is important so we don't break it in a future version
   unintentionally.
 - [Optional] Run the tests against a specific Gemfile:
-  `$ bundle exec appraisal rails_7.0 rake spec`.
-- Run the tests against all supported versions: `$ bundle exec rake` (or
-  `$ bundle exec wwtd`)
+  `bundle exec appraisal rails_8.1 rake spec`.
+- Run the tests against all supported versions: `bundle exec rake`
 - Commit, but please do not mess with `Rakefile`, version, or history.
 - Send a Pull Request. Bonus points for topic branches.
 
 ## Copyright
 
-Copyright (c) 2010-2024 Cássio Marques and Lucas Caton. See `LICENSE` file for
+Copyright (c) 2010-2026 Cássio Marques and Lucas Caton. See `LICENSE` file for
 details.

data/enumerate_it.gemspec

@@ -31,5 +31,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rubocop'
   gem.add_development_dependency 'rubocop-rake'
   gem.add_development_dependency 'rubocop-rspec'
-  gem.add_development_dependency 'sqlite3', '< 2'
+  gem.add_development_dependency 'sqlite3'
 end

data/gemfiles/rails_6.0.gemfile

@@ -4,6 +4,9 @@ source 'https://rubygems.org'
 
 gem 'activerecord', '~> 6.0.6.1'
 gem 'activesupport', '~> 6.0.6.1'
+gem 'base64'
+gem 'bigdecimal'
+gem 'mutex_m'
 gem 'sqlite3', '< 2'
 
 gemspec path: '../'

data/gemfiles/rails_6.1.gemfile

@@ -2,8 +2,11 @@
 
 source 'https://rubygems.org'
 
-gem 'activerecord', '~> 6.1.7.7'
-gem 'activesupport', '~> 6.1.7.7'
+gem 'activerecord', '~> 6.1.7.10'
+gem 'activesupport', '~> 6.1.7.10'
+gem 'base64'
+gem 'bigdecimal'
+gem 'mutex_m'
 gem 'sqlite3', '< 2'
 
 gemspec path: '../'

data/gemfiles/rails_7.0.gemfile

@@ -2,8 +2,11 @@
 
 source 'https://rubygems.org'
 
-gem 'activerecord', '~> 7.0.8.1'
-gem 'activesupport', '~> 7.0.8.1'
+gem 'activerecord', '~> 7.0.10'
+gem 'activesupport', '~> 7.0.10'
+gem 'base64'
+gem 'bigdecimal'
+gem 'mutex_m'
 gem 'sqlite3', '< 2'
 
 gemspec path: '../'

data/gemfiles/rails_7.1.gemfile

@@ -2,8 +2,8 @@
 
 source 'https://rubygems.org'
 
-gem 'activerecord', '~> 7.1.3.2'
-gem 'activesupport', '~> 7.1.3.2'
-gem 'sqlite3', '< 2'
+gem 'activerecord', '~> 7.1.6'
+gem 'activesupport', '~> 7.1.6'
+gem 'sqlite3'
 
 gemspec path: '../'

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activerecord', '~> 7.2.3.1'
+gem 'activesupport', '~> 7.2.3.1'
+gem 'sqlite3'
+
+gemspec path: '../'

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activerecord', '~> 8.0.5'
+gem 'activesupport', '~> 8.0.5'
+gem 'sqlite3'
+
+gemspec path: '../'

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activerecord', '~> 8.1.3'
+gem 'activesupport', '~> 8.1.3'
+gem 'sqlite3'
+
+gemspec path: '../'

data/lib/enumerate_it/base.rb

@@ -1,7 +1,7 @@
 require 'forwardable'
 
 module EnumerateIt
-  class Base
+  class Base # rubocop:disable Metrics/ClassLength
     class << self
       extend Forwardable
 
@@ -95,6 +95,25 @@ module EnumerateIt
         I18n.t("enumerations.#{name.underscore}.#{value.to_s.underscore}", default: default)
       end
 
+      def custom_helpers(&block)
+        @custom_helper_methods ||= []
+
+        mod = Module.new(&block)
+        methods = mod.instance_methods(false)
+        collisions = methods & singleton_class.instance_methods
+
+        raise ArgumentError, <<~MESSAGE.chomp if collisions.any?
+          Custom helper(s) '#{collisions.join(', ')}' would override existing EnumerateIt::Base methods
+        MESSAGE
+
+        @custom_helper_methods.concat(methods)
+        extend mod
+      end
+
+      def custom_helper_methods
+        @custom_helper_methods || []
+      end
+
       private
 
       def sorted_map
@@ -105,12 +124,17 @@ module EnumerateIt
 
       def sort_lambda
         {
-          value:       ->(_k, v) { v[0] },
-          name:        ->(k, _v) { k },
-          translation: ->(_k, v) { translate(v[1]) }
+          value:                 ->(_k, v) { v[0] },
+          name:                  ->(k, _v) { k },
+          translation:           ->(_k, v) { translate(v[1]) },
+          normalize_translation: ->(_k, v) { normalize_translation(translate(v[1])) }
         }[sort_mode]
       end
 
+      def normalize_translation(text)
+        text.unicode_normalize(:nfkd).gsub(/[^\x00-\x7F]/, '')
+      end
+
       def normalize_enumeration(values_hash)
         values_hash.each_pair do |key, value|
           values_hash[key] = [value, key] unless value.is_a? Array
@@ -129,9 +153,7 @@ module EnumerateIt
       def values_hash(args)
         return args.first if args.first.is_a?(Hash)
 
-        args.each_with_object({}) do |value, hash|
-          hash[value] = value.to_s
-        end
+        args.to_h { |value| [value, value.to_s] }
       end
     end
   end

data/lib/enumerate_it/class_methods.rb

@@ -1,5 +1,5 @@
 module EnumerateIt
-  module ClassMethods
+  module ClassMethods # rubocop:disable Metrics/ModuleLength
     def has_enumeration_for(attribute, options = {})
       self.enumerations = enumerations.dup
 
@@ -17,7 +17,8 @@ module EnumerateIt
       set_validations(attribute, options) unless options[:skip_validation]
 
       if options[:create_helpers]
-        %w[create_helper_methods create_mutator_methods create_polymorphic_methods].each do |method|
+        %w[create_helper_methods create_mutator_methods create_polymorphic_methods
+           create_custom_helper_methods].each do |method|
           send(method, options[:with], attribute, options[:create_helpers])
         end
       end
@@ -100,12 +101,27 @@ module EnumerateIt
       end
     end
 
+    def create_custom_helper_methods(klass, attribute_name, helpers)
+      return unless klass.custom_helper_methods.any?
+
+      prefix_name = "#{attribute_name}_" if helpers.is_a?(Hash) && helpers[:prefix]
+
+      class_eval do
+        klass.custom_helper_methods.each do |method_name|
+          define_method "#{prefix_name}#{method_name}" do
+            value = send(attribute_name)
+            klass.public_send(method_name, value) unless value.nil?
+          end
+        end
+      end
+    end
+
     def define_enumeration_class(attribute, options)
       return if options[:with]
 
       inner_enum_class_name = attribute.to_s.camelize.to_sym
 
-      options[:with] = if constants.include?(inner_enum_class_name)
+      options[:with] = if const_defined?(inner_enum_class_name)
         const_get(inner_enum_class_name)
       else
         attribute.to_s.camelize.constantize

data/lib/enumerate_it/version.rb

@@ -1,3 +1,3 @@
 module EnumerateIt
-  VERSION = '4.0.0'.freeze
+  VERSION = '4.2.0'.freeze
 end