humanize_enum 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f58656198e18e6351df8adad2213dba5ea46c9cc6fde6ae3a0fdf2ea43584961
-  data.tar.gz: d3d98c03cb1827c7e83ba3ea037eebe8db398ad88eee0c7184a15cd0e196c541
+  metadata.gz: 0d6163c9c0cc6895cda69e255abc7c953814c863e76300d70b2916c8e2b245eb
+  data.tar.gz: da44277aabc9a034de3090b5f202ff49339d68b71d0213714b7c7254e2f45208
 SHA512:
-  metadata.gz: 43316746804a9f0c50a5615e7edb75b0b741e2d46853dc777c6da5cf07df0705cbf3d36a0063ad4d34126d946021f7160a58747ea2fd314527db158a187f1efe
-  data.tar.gz: b6e9774193ace25f8421cafd9ce3faecd4a89e2ad180cb22fc35788b047ae166028be52ab16bff4477ccf80920ad5a4d4d81e2de16ef6ca033b7930657e0a60d
+  metadata.gz: dbc0ce238f10c8215b7555aa964d5f5611bfb8133eb521ebb98ed3c3c66641c402d25aa222877bfe85d4c94e79be272f06f19963cb4c9ce65ccfb56a0d6d8898
+  data.tar.gz: 6815ee75ea944d1c6df5cfde200d5c7190d852898eb2ea79e1b071b74069e88e62a37cd22db0d5e3439b9e0fcd85c400c08422def32c63d5a222c062c292dcd8

data/README.md

@@ -62,7 +62,10 @@ payment.humanize_enums(:status)
 
 ```
 
-Or if the incoming data is a text label, get its enum_value:
+### Dehumanize Enum Values
+
+The `dehumanize_enum` method lets you find an enum key based on its human-readable form:
+
 ```ruby
 str = 'Payment error'
 Payment.dehumanize_enum(:status, str) # => "error"
@@ -71,6 +74,83 @@ Payment.dehumanize_enum(:status, str) # => "error"
 Payment.dehumanize_enum(:status, 'blah') # => nil 
 ```
 
+### Advanced Usage
+
+#### Translating Enums and Polymorphic Associations
+
+This gem isn't just for enums; you can also use it to translate polymorphic association types. Here's how you can do it:
+
+Let's consider a model `Document` with an enum field `status` and a polymorphic association called `documentable`:
+
+```ruby
+class Document < ApplicationRecord
+  enum status: { draft: 0, published: 1, archived: 2 }
+  belongs_to :documentable, polymorphic: true
+end
+```
+
+And we have various models that include a concern `Documentable`:
+
+```ruby
+
+module Documentable
+  extend ActiveSupport::Concern
+  included do
+    has_many :documents, as: :documentable
+  end
+end
+
+class Article < ApplicationRecord
+  include Documentable
+end
+
+class Report < ApplicationRecord
+  include Documentable
+end
+```
+
+In your locale files, you can set translations for both the enum `status` and the polymorphic association type `documentable_type`:
+
+```yaml
+en:
+  activerecord:
+    attributes:
+      document:
+        status: "Status"
+        status/draft: "Draft"
+        status/published: "Published"
+        status/archived: "Archived"
+        documentable_type: "Type"
+        documentable_type/article: "Article"
+        documentable_type/report: "Report"
+```
+
+Now you can use `humanize_enum` to get these translations:
+
+```ruby
+document = Document.last
+document.status # => :published
+document.humanize_enum(:status) # => 'Published'
+
+document.documentable_type # => 'Article'
+document.humanize_enum(:documentable_type) # => 'Article'
+```
+
+And to query a translation for a specific value:
+
+```ruby
+Document.humanize_enum(:status, :archived) # => 'Archived'
+Document.humanize_enum(:documentable_type, :article) # => 'Article'
+```
+
+To get the actual enum or polymorphic type from a human-readable string:
+
+```ruby
+Document.dehumanize_enum(:status, 'Published') # => :published
+Document.dehumanize_enum(:documentable_type, 'Article') # => :article
+```
+
+
 ## Inspired by
 
 - a post by [Juraj Kostolanský](https://www.kostolansky.sk/posts/localize-rails-enums/) and
@@ -83,10 +163,22 @@ Payment.dehumanize_enum(:status, 'blah') # => nil
 - [ar_enum_i18n](https://github.com/dalpo/ar_enum_i18n)
 - [translate_enum](https://github.com/shlima/translate_enum)
 
-## TODO
-- [x] check input parameters for presence in enums
-- [x] add some specs?
-- [ ] maybe some justification on why on earth make yet another gem on enum i18n  
+## Why Another Gem for Enum I18n?
+
+You might be wondering, "Why create another gem for internationalizing enums when there are already alternatives?"
+
+Here are some reasons why `humanize_enum` might be the right choice for you:
+
+1. **Not Just for Enums**: Yeah, it's called `humanize_enum`, but you can totally use it for polymorphic associations too. Neat, right?
+
+2. **Fast and Light**: We've trimmed the fat to make sure this gem runs smoothly, without slowing down your app.
+
+3. **No Rocket Science**: Simple to get, simple to use. You don't need a Ph.D. to figure it out.
+
+4. **Clean and Familiar Structure**: We keep your locale keys neat and tidy, like `status/paid`, and it's kinda similar to what you see in other gems like AASM. So, less headache for you.
+
+
+
 
 ## Development
 

data/lib/humanize_enum/class_methods.rb

@@ -0,0 +1,55 @@
+module HumanizeEnum
+  module ClassMethods
+    # @param enum_name [String, Symbol]
+    # @param enum_value [String, Symbol]
+    # @return [String] translated value of an enum
+    # @raise [UnknownEnumKey] if enum_name is not a defined enum
+    # @example
+    #   Payment.humanize_enum(:status, :pending) # => 'Pending'
+    def humanize_enum(enum_name, enum_value)
+      check_enum!(enum_name)
+      I18n.t("activerecord.attributes.#{model_name.i18n_key}.#{enum_name}/#{enum_value.to_s.underscore}")
+    end
+
+    # @return [Hash<String, String>] hash where key is enum name and value is its translation
+    # @example
+    #   Payment.humanize_enums(:status)
+    #   {
+    #     "initial" => "Initial status",
+    #        "paid" => "Payment processed",
+    #       "error" => "Payment error"
+    #   }
+    def humanize_enums(enum_name)
+      enum_options(enum_name).map do |enum|
+        [enum.value, enum.text]
+      end.to_h
+    end
+
+    # Get enum value from a translated enum text.
+    # Useful for parsing incoming i18n-ed text labels that were generated by +humanize_enum+
+    #
+    # @param enum_name [String, Symbol] enum name
+    # @param enum_text [String] text value of the enum
+    # @return [Integer, String, NilClass]
+    def dehumanize_enum(enum_name, enum_text)
+      humanize_enums(enum_name).key(enum_text)&.underscore
+    end
+
+    # @param enum_name [String, Symbol] enum key to be translated
+    # @return [Array<SelectOption>] array of structs with :id, :key, :text, :checked
+    # @raise [UnknownEnumKey] if enum_name is not a defined enum
+    def enum_options(enum_name)
+      check_enum!(enum_name)
+      enum_i18n_key = enum_name.to_s.pluralize
+      send(enum_i18n_key).map do |key, val|
+        SelectOption.new(val, key, humanize_enum(enum_name, key), nil)
+      end
+    end
+
+    # @param enum_name [String, Symbol]
+    # @raise [UnknownEnumKey] if enum_name is not a defined enum
+    def check_enum!(enum_name)
+      raise UnknownEnumKey unless defined_enums.has_key?(enum_name.to_s)
+    end
+  end
+end

data/lib/humanize_enum/enum_translation.rb

@@ -0,0 +1,29 @@
+module HumanizeEnum
+  module EnumTranslation
+
+    def self.included(base)
+      base.extend HumanizeEnum::ClassMethods
+    end
+
+    # @return [String] translated enum value of an instance
+    # @example
+    #   payment = Payment.new
+    #   payment.status = 'initial'
+    #   payment.humanize_enum(:status) # => 'Initial'
+    def humanize_enum(enum_name)
+      self.class.check_enum!(enum_name)
+      I18n.t("activerecord.attributes.#{self.class.model_name.i18n_key}.#{enum_name}/#{send(enum_name).to_s.underscore}")
+    end
+
+    # @see .humanize_enums
+    def humanize_enums(enum_name)
+      self.class.humanize_enums(enum_name)
+    end
+
+    # @return [Array<SelectOption>]
+    # @see .enum_options
+    def enum_options(enum_name)
+      self.class.enum_options(enum_name)
+    end
+  end
+end

data/lib/humanize_enum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HumanizeEnum
-  VERSION = '0.1.8'
+  VERSION = '0.1.9'
 end

data/lib/humanize_enum.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'humanize_enum/version'
-require_relative 'humanize_enum/helpers'
+require_relative 'humanize_enum/enum_translation'
+require_relative 'humanize_enum/class_methods'
 require 'active_support/lazy_load_hooks'
 require 'active_support/inflector'
 
@@ -10,9 +11,12 @@ module HumanizeEnum
   # Error for an unknown enum key
   UnknownEnumKey = Class.new(StandardError)
 
+  # Struct to be used in html selects and similar places
+  SelectOption = Struct.new(:id, :value, :text, :checked)
+
   if defined?(ActiveSupport.on_load)
     ActiveSupport.on_load(:active_record) do
-      include HumanizeEnum::Helpers
+      include HumanizeEnum::EnumTranslation
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: humanize_enum
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Max Buslaev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-07-31 00:00:00.000000000 Z
+date: 2023-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -39,7 +39,8 @@ files:
 - README.md
 - Rakefile
 - lib/humanize_enum.rb
-- lib/humanize_enum/helpers.rb
+- lib/humanize_enum/class_methods.rb
+- lib/humanize_enum/enum_translation.rb
 - lib/humanize_enum/version.rb
 - sig/humanize_enum.rbs
 homepage: https://github.com/austerlitz/humanize_enum

data/lib/humanize_enum/helpers.rb

@@ -1,85 +0,0 @@
-module HumanizeEnum
-  module Helpers
-    # Struct to be used in html selects and similar places
-    SelectOption = Struct.new(:id, :value, :text, :checked)
-
-    def self.included(base)
-      base.extend ClassMethods
-    end
-
-    module ClassMethods
-      # @param enum_name [String, Symbol]
-      # @param enum_value [String, Symbol]
-      # @return [String] translated value of an enum
-      # @raise [UnknownEnumKey] if enum_name is not a defined enum
-      # @example
-      #   Payment.humanize_enum(:status, :pending) # => 'Pending'
-      def humanize_enum(enum_name, enum_value)
-        check_enum!(enum_name)
-        I18n.t("activerecord.attributes.#{model_name.i18n_key}.#{enum_name}/#{enum_value}")
-      end
-
-      # @return [Hash<String, String>] hash where key is enum name and value is its translation
-      # @example
-      #   Payment.humanize_enums(:status)
-      #   {
-      #     "initial" => "Initial status",
-      #        "paid" => "Payment processed",
-      #       "error" => "Payment error"
-      #   }
-      def humanize_enums(enum_name)
-        enum_options(enum_name).map do |enum|
-          [enum.value, enum.text]
-        end.to_h
-      end
-
-      # Get enum value from a translated enum text.
-      # Useful for parsing incoming i18n-ed text labels that were generated by +humanize_enum+
-      #
-      # @param enum_name [String, Symbol] enum name
-      # @param enum_text [String] text value of the enum
-      # @return [Integer, String, NilClass]
-      def dehumanize_enum(enum_name, enum_text)
-        humanize_enums(enum_name).invert[enum_text]
-      end
-
-      # @param enum_name [String, Symbol] enum key to be translated
-      # @return [Array<SelectOption>] array of structs with :id, :key, :text, :checked
-      # @raise [UnknownEnumKey] if enum_name is not a defined enum
-      def enum_options(enum_name)
-        check_enum!(enum_name)
-        enum_i18n_key = enum_name.to_s.pluralize
-        send(enum_i18n_key).map do |key, val|
-          SelectOption.new(val, key, humanize_enum(enum_name, key), nil)
-        end
-      end
-
-      # @param enum_name [String, Symbol]
-      # @raise [UnknownEnumKey] if enum_name is not a defined enum
-      def check_enum!(enum_name)
-        raise UnknownEnumKey unless defined_enums.keys.include?(enum_name.to_s)
-      end
-    end
-
-    # @return [String] translated enum value of an instance
-    # @example
-    #   payment = Payment.new
-    #   payment.status = 'initial'
-    #   payment.humanize_enum(:status) # => 'Initial'
-    def humanize_enum(enum_name)
-      self.class.check_enum!(enum_name)
-      I18n.t("activerecord.attributes.#{self.class.model_name.i18n_key}.#{enum_name}/#{send(enum_name)}")
-    end
-
-    # @see .humanize_enums
-    def humanize_enums(enum_name)
-      self.class.humanize_enums(enum_name)
-    end
-
-    # @return [Array<SelectOption>]
-    # @see .enum_options
-    def enum_options(enum_name)
-      self.class.enum_options(enum_name)
-    end
-  end
-end