Enumerize

Enumerize provides automatic integration with:

• RailsAdmin: Automatically handles enumerated attributes in the admin interface.

To use Enumerize in your Ruby application, add it to your Gemfile:

gem 'enumerize'

Then run bundle install. Alternatively, you can install it directly via the command line:

$ gem install enumerize

Supported Versions:

• Ruby 3.1+
• Rails 7.0+

To use the RSpec matchers within Minitest (specifically when using shoulda), add the following configuration to your test_helper.rb inside the ActiveSupport::TestCase class definition:

class ActiveSupport::TestCase
  ActiveRecord::Migration.check_pending!

  require 'enumerize/integrations/rspec'
  extend Enumerize::Integrations::RSpec

  # ...
end

Enumerize provides a built-in RSpec matcher to verify that attributes are correctly enumerated. You can use the standard should enumerize(:attribute) syntax or the RSpec 3 is_expected.to enumerize(:attribute) syntax.

To use it, ensure your class extends Enumerize and then use the matcher in your describe blocks.

class User
  extend Enumerize

  enumerize :status, in: [:student, :employed, :retired]
end

describe User do
  it { should enumerize(:status) }

  # or with RSpec 3 expect syntax
  it { is_expected.to enumerize(:status) }
end

When used with ActiveModel::Attributes, Enumerize provides a custom type that manages the lifecycle of the attribute value:

• Casting: When a value is assigned, it attempts to find the corresponding enumerized value. For attributes with multiple: true, it uses find_values to process arrays.
• Deserialization: When reading from the database/source, it converts the raw value back into the enumerized object. If the attribute is marked as multiple: true and the value is an Array, it uses find_values.
• Serialization: When saving, it uses the underlying value of the enumerized object (via find_value(value).value) to ensure the correct primitive is stored.

The Enumerize::Value class is a specialized String object used to represent an enumerated item. It is designed to behave like its underlying string value for most operations but provides specific logic for equality and serialization:

• Equality: The == operator checks if the object matches another object by comparing the string representation or the underlying @value.
• JSON Serialization: When converted to JSON via as_json, the object serializes to its string representation.
• Encoding: It supports encode_with for custom encoding (e.g., in YAML), representing the object via its superclass and the underlying @value.

Enumerize implements a custom ActiveRecord::Type::Value subclass to manage the conversion between database values and Enumerize::Value objects.

When a value is assigned to an enumerized attribute, the cast logic follows this priority:

1. If the value is already an instance of Enumerize::Value, it is returned as-is.
2. It attempts to find the value directly using the attribute's find_value method.
3. If not found, it delegates to the attribute's subtype (if applicable) to attempt to cast the value before searching again.

This ensures that both strings (like 'active') and integers (like 1) can be correctly resolved to the appropriate Enumerize::Value object.

Enumerize provides an extension for SimpleForm::FormBuilder that automatically configures input options for enumerated attributes. When using input or input_field in a SimpleForm builder, the extension automatically detects if an attribute is enumerated and applies the following logic:

1. Automatic Collections: It populates the :collection option with the enumerated attribute's options.
2. Multiple Selection Support: If the attribute is defined as Enumerize::Multiple, it automatically adds multiple: true to the :input_html options, unless you have explicitly set :as => :check_boxes.