power_enum 4.3.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4590529169ea38e3c39d111866c615c95516f1079d855c623b794df6a015d13
-  data.tar.gz: 0d73cb99bf685e1b26571d40664b63ba5de64c570f68baee0765e1a755c38529
+  metadata.gz: 1472eb40672379c9033d7bd7dc3e35d545160363f33d7b05b00e174dd05530a1
+  data.tar.gz: cdacd983f5bfe94e07bed56e4a54225a6c4c54fb3d5489aacb5beb7e5886571f
 SHA512:
-  metadata.gz: 365465c3bd51e698ee53ff98f80c3e0914afa4df64511a7c9c5d4cfee19e9bd93c7d66d14b24c5858e24cf08fa093a4d9c5c7abb08127e7a55c651d8a6d1d022
-  data.tar.gz: 429c63fd173a1953ea50b3ae9b17c7dc8ee2c997bf0763e7ba9879f59fd75d035ece1aef40a917dc9755e53052bdfccf04d32c888a7e3b5120e9d70122bda84f
+  metadata.gz: 5395b07f622523606b08e2d81a3a68388abe12841f7e8277a223aae2dbfb488301f2b648241c75c623e50ac968134fc9962b0022982b46262fad6749ffe73347
+  data.tar.gz: ce2caa8a50801b3f004b3d624660827d9c39bbb8298cfe1a748a949ae4d0c8908bb6cd2712179ef6705e1cb10d92bc73e6ffbd4c09c1133e8e5ffbf3c2447590

data/README.markdown

@@ -10,7 +10,8 @@ Enumerations for Rails Done Right.
 
 ## Versions
 
-* PowerEnum 4.0.X (this version) supports Rails 6.X, and Rails 7.0 (Experimental)
+* PowerEnum 4.3+ supports Rails 8.X (Experimental)
+* PowerEnum 4.0.X supports Rails 6.X, and Rails 7.0 (Experimental)
 * PowerEnum 3.X supports Rails 4.2, Rails 5.X and Rails 6.0
 * PowerEnum 2.X supports Rails 4.X and Rails 5.0
 * PowerEnum 1.X supports Rails 3.1/3.2, available here: https://github.com/albertosaurus/power_enum
@@ -53,6 +54,11 @@ See "How to use it" below for more information.
 
 ## Requirements
 
+### PowerEnum 4.3+
+
+* Ruby 3.1 or later (JRuby should work but isn't extensively tested).
+* Rails 8.X
+
 ### PowerEnum 4.0.X
 
 * Ruby 2.7 or later (JRuby should work but isn't extensively tested).
@@ -299,7 +305,7 @@ With that, your BookingStatus class will have the following methods defined:
 
 #### Class Methods
 
-##### [](*args)
+##### [](*args, &block)
 
 `BookingStatus[arg]` performs a lookup for the BookingStatus instance for the given arg. The arg value can be a
 'string' or a :symbol, in which case the lookup will be against the BookingStatus.name field. Alternatively arg can be
@@ -309,8 +315,10 @@ instance of the enum (in this case BookingStatus) as a convenience.
 The `:on_lookup_failure` option specifies the name of a *class* method to invoke when the `[]` method is unable to
 locate a BookingStatus record for arg. The default is the built-in `:enforce_none` which returns nil. There are also
 built-ins for `:enforce_strict` (raise and exception regardless of the type for arg), `:enforce_strict_literals` (raises
-an exception if the arg is a Integer or Symbol), `:enforce_strict_ids` (raises and exception if the arg is a Integer) and
-`:enforce_strict_symbols` (raises an exception if the arg is a Symbol).
+an exception if the arg is a Integer or Symbol), `:enforce_strict_ids` (raises and exception if the arg is a Integer),
+`:enforce_strict_symbols` (raises an exception if the arg is a Symbol), `:insert_new_record` (will insert a new
+record - NOTE: only supported if the DB back end implements atomic UPSERT), and `:call_block`. Alternatively set
+`:on_lookup_failure` to a proc for a more generic handler.
 
 The purpose of the `:on_lookup_failure` option is that a) under some circumstances a lookup failure is a Bad Thing and
 action should be taken, therefore b) a fallback action should be easily configurable. You can
@@ -320,6 +328,27 @@ You can also pass in multiple arguments to `[]`. This returns a list of enums co
 passed in values. Duplicates are filtered out. For example `BookingStatus[arg1, arg2, arg3]` would be equivalent to
 `[BookingStatus[arg1], BookingStatus[arg2], BookingStatus[arg3]]`.
 
+Example:
+
+```ruby
+class BookingStatus < ActiveRecord::Base
+  acts_as_enumerated on_lookup_failure: :call_block
+end
+
+# Given a BookingStatus, whose possible members are "pending", "closed", or "canceled":
+
+# Returns nil
+BookingStatus[:expired]
+
+# Returns the equivalent of BookingStatus[:pending, :closed]
+BookingStatus[:Pending, :Closed] { |klass, arg| klass[arg.to_s.downcase] }
+
+# Inserts a new record - CAVEAT EMPTOR
+BookingStatus[:expired] do |klass, arg|
+  klass.insert_new_record(arg, description: "#{arg.to_s.capitalize} - inserted inline")
+end
+```
+
 ##### contains?(arg)
 
 `BookingStatus.contains?(arg)` returns `true if` the given Symbol, String or id has a member instance in the enumeration,

data/VERSION

@@ -1 +1 @@
-4.3.0
+4.5.0

data/lib/power_enum/enumerated.rb

@@ -30,10 +30,13 @@ module PowerEnum
       #   record for arg. The default is the built-in :enforce_none which returns nil. There are also built-ins for
       #   :enforce_strict (raise and exception regardless of the type for arg), :enforce_strict_literals (raises an
       #   exception if the arg is a Integer or Symbol), :enforce_strict_ids (raises and exception if the arg is a
-      #   Integer) and :enforce_strict_symbols (raises an exception if the arg is a Symbol).  The purpose of the
-      #   :on_lookup_failure option is that a) under some circumstances a lookup failure is a Bad Thing and action
-      #   should be taken, therefore b) a fallback action should be easily configurable.  You can also give it a
-      #   lambda that takes in a single argument (The arg that was passed to +[]+).
+      #   Integer), :enforce_strict_symbols (raises an exception if the arg is a Symbol), :insert_new_record (see
+      #   below), and :call_block (See documentation for +[arg]+).
+      #   The purpose of the :on_lookup_failure option is that a) under some circumstances a lookup failure is a
+      #   Bad Thing and action should be taken, therefore b) a fallback action should be easily configurable.
+      #   You can also give it a lambda that takes in a single argument (The arg that was passed to +[]+).
+      #   Note the :insert_new_record option - it will insert a new record into the database and update the enumerations
+      #   cache. NOTE: This option is only supported where the database back end implements an atomic UPSERT operation.
       # [:name_column]
       #   Override for the 'name' column.  By default, assumed to be 'name'.
       # [:alias_name]
@@ -218,15 +221,19 @@ module PowerEnum
       # Enum lookup by Symbol, String, or id.  Returns <tt>arg<tt> if arg is
       # an enum instance.  Passing in a list of arguments returns a list of
       # enums.  When called with no arguments, returns nil.
-      def [](*args)
+      #
+      # If the given arg is not in the enumerations cache, the lookup failure handler is set to :call_block
+      # and an optional block of the form { |klass, arg| } is passed to this method, the block will be
+      # invoked with the first argument being this instance and the second the given argument.
+      def [](*args, &block)
         case args.size
         when 0
           nil
         when 1
           arg = args.first
-          Array === arg ? self[*arg] : (lookup_enum_by_type(arg) || handle_lookup_failure(arg))
+          Array === arg ? self[*arg, &block] : (lookup_enum_by_type(arg) || handle_lookup_failure(arg, &block))
         else
-          args.map{ |item| self[item] }.uniq
+          args.map{ |item| self[item, &block] }.uniq
         end
       end
 
@@ -356,13 +363,13 @@ module PowerEnum
       end
 
       # Deals with a lookup failure for the given argument.
-      private def handle_lookup_failure(arg)
+      private def handle_lookup_failure(arg, &block)
         if (lookup_failure_handler = self.acts_enumerated_on_lookup_failure)
           case lookup_failure_handler
           when Proc
             lookup_failure_handler.call(arg)
           else
-            self.send(lookup_failure_handler, arg)
+            self.send(lookup_failure_handler, arg, &block)
           end
         else
           self.send(:enforce_none, arg)
@@ -418,6 +425,33 @@ module PowerEnum
         nil
       end
 
+      # Insert a new record if +arg+ is a Symbol or a String, and flush the enumerations cache.
+      def insert_new_record(arg, description: nil)
+        if Symbol === arg || String === arg
+          value = arg.to_s
+          upsert_attributes = if column_names.include?("description")
+                                { acts_enumerated_name_column => value, description: description || value.capitalize.gsub("_", " ") }
+                              else
+                                { acts_enumerated_name_column => value }
+                              end
+
+          update_enumerations_model do
+            upsert(upsert_attributes, update_only: [], unique_by: acts_enumerated_name_column)
+          end
+          self[arg]
+        else
+          nil
+        end
+      end
+
+      private def call_block(arg, &block)
+        if block_given?
+          block.call self, arg
+        else
+          enforce_none(arg)
+        end
+      end
+
       # raise the {ActiveRecord::RecordNotFound} error.
       # @private
       private def raise_record_not_found(arg)

data/lib/power_enum/has_enumerated.rb

@@ -165,9 +165,17 @@ module PowerEnum
           when #{class_name}
             val = #{class_name}.lookup_id(arg.id)
           when String
-            val = #{class_name}.lookup_name(arg)
+            val = if #{class_name}.acts_enumerated_on_lookup_failure.to_s == 'insert_new_record'
+              #{class_name}[arg]
+            else
+              #{class_name}.lookup_name(arg)
+            end
           when Symbol
-            val = #{class_name}.lookup_name(arg.id2name)
+            val = if #{class_name}.acts_enumerated_on_lookup_failure.to_s == 'insert_new_record'
+              #{class_name}[arg.id2name]
+            else
+              #{class_name}.lookup_name(arg.id2name)
+            end
           when Integer
             val = #{class_name}.lookup_id(arg)
           when nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: power_enum
 version: !ruby/object:Gem::Version
-  version: 4.3.0
+  version: 4.5.0
 platform: ruby
 authors:
 - Trevor Squires
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -61,7 +61,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -71,7 +71,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -81,7 +81,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -91,7 +91,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -101,7 +101,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -111,7 +111,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
@@ -159,7 +159,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="