active_module 0.6.8 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aceb33a1b0059198c851a897ab6dd3636a9796f25db0912a43ffeb4bcad9af30
-  data.tar.gz: 675db3e326eee1cc570f62d4d0199cabcd0841b42dc362e5eb247299d27f1183
+  metadata.gz: 380e377e525e9ed59c3154706e0183a744ff91660db261aa3a4ee012ad8feaf0
+  data.tar.gz: 615e920f65193a34f20adb0480311f86f16dfcd8d9ae9c68bfafca1b38af8919
 SHA512:
-  metadata.gz: c1cf90718ec48d5c3cd155b5bb7f3330b30a251e2f1a0b16394a3051893dbc701c3b60085647a737d4fe660e977b70386f0556b7d5db680be7eef1afb381b869
-  data.tar.gz: 1d3257b60414f30b9ebb699c9067155ea4669e68e30ba9998e98a92719ecb86f891888b05876cbfae810fdd22a0b7906571826f2ad932ca86113dcee6543fd79
+  metadata.gz: 3264235d103059314e29f031c7ec6d1b7d3edc37c65e415bb61a14d0ae71d58edd794c1eeaf7ad7dc5e211d9e5b6a891861fef6e934e1bce1552558db4a26803
+  data.tar.gz: 20f7c237d5d2c2b7e4088e6c050fb4b1115460e0dd051ec2a08fcd019d6fa624e6a4bfadb559912c1384fe69f38f9d1ae39f5cd21e0ecc0174f9ad33a1a68e65

data/README.md

@@ -1,4 +1,3 @@
-
 # active_module
 [![Gem Version](https://img.shields.io/gem/v/active_module)](https://rubygems.org/gems/active_module)
 [![License: MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
@@ -6,9 +5,7 @@
 [![100% Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/pedrorolo/active_module/blob/main/spec/spec_helper.rb)
 [![Gem Total Downloads](https://img.shields.io/gem/dt/active_module?style=flat)](https://bestgems.org/gems/active_module)
 
-
-
-#### *Modules and Classes as first-class active record values!*
+*Modules and Classes as first-class active record values!*
 
 ActiveModel/ActiveRecord implementation of the Module attribute type.
 
@@ -23,38 +20,46 @@ This is a very generic mechanism that enables many possible utilizations, for in
 - **Static configuration management**
 - **Rich Java/C#-like enums**
 
-You can find examples of these in [Usage -> Examples](#Examples).
+You can find examples of these in [Usage -> Examples](#examples).
 
 ## TL;DR
 
 Declare module attributes like this:
+
 ```ruby
 class MyARObject < ActiveRecord::Base
-  attribute :module_field, 
-            :active_module, 
+  attribute :module_field,
+            :active_module,
             possible_modules: [MyModule1, MyClass, Nested::Module]
+
+  # Optional: adds Rails-enum-like helpers (my_module1?, my_module1!,
+  # with_my_module1, ...). Drop this line if you don't need them:
+  active_module_enum :module_field
 end
 ```
 
 Assign them like this:
-```ruby 
+
+```ruby
 object.module_field = Nested::Module
 object.module_field = :Module
 object.module_field = "Module"
-object.module_field #=> Nested::Module:Module
+object.module_field = :nested_module          # underscored nested name
+object.module_field                           #=> Nested::Module
 ```
 
 Query them like this:
-```ruby 
+
+```ruby
 MyARObject.where(module_field: Nested::Module)
 MyARObject.where(module_field: :Module)
 MyARObject.where(module_field: "Module")
-object.module_field #=> Nested::Module:Module
+MyARObject.where(module_field: :nested_module) # underscored nested name
 ```
 
 And compare them like this:
 
-```ruby 
+```ruby
 object.module_field == Nested::Module
 
 module MyNameSpace
@@ -62,6 +67,7 @@ module MyNameSpace
 
   object.module_field =~ :Module
   object.module_field =~ "Module"
+  object.module_field =~ :nested_module     # underscored nested name
 end
 ```
 
@@ -70,7 +76,7 @@ end
 Add to your gemfile - and if you are using rails - that's all you need:
 
 ```ruby
-gem 'active_module', "~> 0.6"
+gem "active_module", "~> 0.8"
 ```
 
 If you are not using rails, just issue this command after loading active record
@@ -89,7 +95,8 @@ ActiveRecord::Type.register(:active_module, ActiveModule::Base)
 
 ## Usage
 
-Add a string field to the table you want to hold a module attribute in your migrations
+Add a string field to the table you want to hold a module attribute in your migrations:
+
 ```ruby
 create_table :my_ar_objects do |t|
   t.string :module_field, index: true
@@ -97,74 +104,120 @@ end
 ```
 
 Now given this random module hierarchy:
+
 ```ruby
 class MyARObject < ActiveRecord::Base
   module MyModule1; end
   module MyModule2; end
-  class MyClass; 
+
+  class MyClass
     module MyModule1; end
   end
 end
 ```
+
 You can make the field refer to one of these modules/classes like this:
+
 ```ruby
 class MyARObject < ActiveRecord::Base
-  attribute :module_field, 
-            :active_module, 
+  attribute :module_field,
+            :active_module,
             possible_modules: [MyModule1, MyModule2, MyClass, MyClass::MyModule1]
 end
 ```
 
-Optionally, you can specify how to map your modules into the database 
+Optionally, you can specify how to map your modules into the database
 (the default is the module's fully qualified name):
+
 ```ruby
-attribute :module_field, 
-          :active_module, 
-          possible_modules: [MyModule1, MyModule2, MyClass, MyClass::MyModule1]
-          mapping: {MyModule1 => "this is the db representation of module1"}
+attribute :module_field,
+          :active_module,
+          possible_modules: [MyModule1, MyModule2, MyClass, MyClass::MyModule1],
+          mapping: { MyModule1 => "m1" }
 ```
 
-And this is it! Easy!<br>
+Modules not included in the mapping hash will use their fully qualified
+name as the database representation. Assignment and querying still work
+with module literals, symbols, and strings:
+
+```ruby
+my_ar_object.module_field = :MyModule1
+my_ar_object.module_field #=> MyARObject::MyModule1
+
+MyARObject.where(module_field: :MyModule1)
+```
+
+The mapping only affects what is stored in the database column.
+
+And this is it! Easy!
 
 ### Assigning and querying module attributes
+
 Now you can use this attribute in many handy ways!
-<br>
-<br>
-For instance, you may refer to it using module literals:
-```ruby
-MyARObject.create!(module_field: MyARObject::MyModule1)
 
-MyARObject.where(module_field: MyARObject::MyModule1)
+The most ergonomic way is to use underscored symbols. For flat modules,
+use the underscored name directly:
 
-my_ar_object.module_field = MyARObject::MyModule1
+```ruby
+MyARObject.create!(module_field: :my_module1)
 
-my_ar_object.module_field #=> MyARObject::MyModule1:Module
+MyARObject.where(module_field: :my_module1)
 
+my_ar_object.module_field = :my_module1
+
+my_ar_object.module_field #=> MyARObject::MyModule1
 ```
-But as typing fully qualified module names is not very ergonomic, you may also use symbols instead:
+
+Nested modules can be referenced using underscored symbols at any
+nesting level:
 
 ```ruby
-MyARObject.create!(module_field: :MyClass)
+MyARObject.create!(module_field: :my_class_my_module1)  # partial nesting
+MyARObject.create!(module_field: :my_module1)           # demodulized name
+MyARObject.where(module_field: :my_class_my_module1)    # all segments joined
+
+my_ar_object.module_field = :my_class_my_module1
+my_ar_object.module_field #=> MyARObject::MyClass::MyModule1
+```
 
-MyARObject.where(module_field: :MyClass)
+When a demodulized name is ambiguous (shared by modules at different
+nesting levels), the least-nested module always wins for assignment
+and querying:
 
-my_ar_object.module_field = :MyClass
+```ruby
+# Given possible_modules: [MyModule1, MyClass::MyModule1]
+# :MyModule1 resolves to the flat MyModule1 (not MyClass::MyModule1)
 
-my_ar_object.module_field #=> MyARObject::MyClass:Class
+MyARObject.create!(module_field: :MyModule1)   # sets to MyModule1
+MyARObject.where(module_field: :MyModule1)     # filters by MyModule1
+my_ar_object.module_field = :MyModule1         # assigns MyModule1
 
+# Use the underscored nested name for the nested module
+MyARObject.where(module_field: :my_class_my_module1)  # filters by MyClass::MyModule1
 ```
 
-However, if there is the need for disambiguation, you can always use strings instead:
+You can always refer to modules using their fully qualified names
+via symbols or module literals:
 
 ```ruby
+MyARObject.create!(module_field: :MyModule1)
+MyARObject.create!(module_field: MyARObject::MyModule1)
+
+MyARObject.where(module_field: :MyModule1)
+MyARObject.where(module_field: MyARObject::MyModule1)
+```
+
+And if there is the need for disambiguation, you can always use
+fully qualified strings:
 
+```ruby
 MyARObject.create!(module_field: "MyClass::MyModule1")
 
 MyARObject.where(module_field: "MyClass::MyModule1")
 
 my_ar_object.module_field = "MyClass::MyModule1"
 
-my_ar_object.module_field #=> MyARObject::MyClass::MyModule::Module
+my_ar_object.module_field #=> MyARObject::MyClass::MyModule1
 ```
 
 ### Comparing modules with strings and symbols
@@ -178,7 +231,9 @@ module YourClassOrModuleThatWantsToCompare
   using ActiveModule::Comparison
 
   def method_that_compares
-    my_ar_object.module_field =~ :MyModule1
+    my_ar_object.module_field =~ :my_module1          # underscored name
+    my_ar_object.module_field =~ :my_class_my_module1 # nested underscored
+    my_ar_object.module_field =~ "MyClass::MyModule1" # fully qualified string
   end
 end
 ```
@@ -186,7 +241,7 @@ end
 or like this, if you don't want to use the refinement:
 
 ```ruby
-ActiveModule::Comparison.compare(my_ar_object.module_field, :MyModule1)
+ActiveModule::Comparison.compare(my_ar_object.module_field, :my_module1)
 ```
 
 but in this last case it would probably make more sense to simply use a module literal:
@@ -200,10 +255,11 @@ my_ar_object.module_field == MyClass::MyModule1
 
 ### Composition-based polymorphism (Strategy design pattern)
 
-[The Strategy design pattern](https://en.wikipedia.org/wiki/Strategy_pattern) allows composition based polymorphism. This enables runtime polymorphism (by changing the strategy in runtime), 
+[The Strategy design pattern](https://en.wikipedia.org/wiki/Strategy_pattern) allows composition based polymorphism. This enables runtime polymorphism (by changing the strategy in runtime),
 and multiple-polymorphism (by composing an object of multiple strategies).
 
-If you want to use classes this will do: 
+If you want to use classes this will do:
+
 ```ruby
 class MyARObject < ActiveRecord::Base
   attribute :strategy_class, :active_module, possible_modules: StrategySuperclass.subclasses
@@ -235,8 +291,8 @@ class MyARObject < ActiveRecord::Base
     end
   end
 
-  attribute :strategy, 
-            :active_module, 
+  attribute :strategy,
+            :active_module,
             possible_modules: [Strategy1, Strategy2]
 
   def run_strategy!(some_args)
@@ -244,8 +300,8 @@ class MyARObject < ActiveRecord::Base
   end
 end
 
-MyARObject.create!(module_field: :Strategy1).run_strategy! #=> "strategy1 called"
-MyARObject.create!(module_field: :Strategy2).run_strategy! #=> "strategy2 called"
+MyARObject.create!(strategy: :Strategy1).run_strategy! #=> "strategy1 called"
+MyARObject.create!(strategy: :Strategy2).run_strategy! #=> "strategy2 called"
 ```
 
 You can later easily promote these modules to classes if you need instance variables:
@@ -268,8 +324,8 @@ class MyARObject < ActiveRecord::Base
     end
   end
 
-  attribute :strategy, 
-            :active_module, 
+  attribute :strategy,
+            :active_module,
             possible_modules: [Strategy1, Strategy2]
 
   def run_strategy!(some_args)
@@ -277,17 +333,17 @@ class MyARObject < ActiveRecord::Base
   end
 end
 
-MyARObject.create!(module_field: :Strategy1).run_strategy! #=> "strategy1 called"
-MyARObject.create!(module_field: :Strategy2).run_strategy! #=> "strategy2 called"
+MyARObject.create!(strategy: :Strategy1).run_strategy! #=> "strategy1 called"
+MyARObject.create!(strategy: :Strategy2).run_strategy! #=> "strategy2 called"
 ```
 
 
 ### Rapid prototyping static domain objects
 
-```ruby 
+```ruby
 # Provider domain Object
 module Provider
- # As if the domain model class
+  # As if the domain model class
   def self.all
     [Ebay, Amazon]
   end
@@ -307,20 +363,21 @@ module Provider
 end
 
 class MyARObject < ActiveRecord::Base
-  attribute :provider, 
-            :active_module, 
+  attribute :provider,
+            :active_module,
             possible_modules: Provider.all
 end
 
-MyARObject.create!(provider: :Ebay).provier.do_something! 
+MyARObject.create!(provider: :Ebay).provider.do_something!
   #=> "do something with the ebay provider config"
-MyARObject.create!(provider: Provider::Amazon).provider.do_something! 
+MyARObject.create!(provider: Provider::Amazon).provider.do_something!
   #=> "do something with the amazon provider config"
 ```
 
 What is interesting about this is that we can later easily promote
-our provider objects into full fledged ActiveRecord objects without 
+our provider objects into full fledged ActiveRecord objects without
 big changes to our code:
+
 ```ruby
 class Provider < ActiveRecord::Base
   def do_something!
@@ -333,10 +390,10 @@ class MyARObject < ActiveRecord::Base
 end
 ```
 
-Just in case you'd like to have shared code amongst the instances in the above example, 
+Just in case you'd like to have shared code amongst the instances in the above example,
 this is how you could do so:
 
-```ruby 
+```ruby
 # Provider domain Object
 module Provider
   # As if the domain model class
@@ -344,7 +401,7 @@ module Provider
     [Ebay, Amazon]
   end
 
-  module Base 
+  module Base
     def do_something!
       "do something with #{something_from_an_instance}"
     end
@@ -375,24 +432,24 @@ end
 ### Static configuration management
 
 This example is not much different than previous one. It however stresses that the module we
-refer to might be used as a source of configuration parameters that change the behaviour of 
+refer to might be used as a source of configuration parameters that change the behaviour of
 the class it belongs to:
 
-```ruby 
+```ruby
 # Provider domain Object
 module ProviderConfig
   module Ebay
     module_function
 
-    def url= 'www.ebay.com'
-    def number_of_attempts= 5 
+    def url = "www.ebay.com"
+    def number_of_attempts = 5
   end
 
   module Amazon
     module_function
 
-    def url= 'www.amazon.com'
-    def number_of_attempts= 10
+    def url = "www.amazon.com"
+    def number_of_attempts = 10
   end
 
   def self.all
@@ -401,19 +458,19 @@ module ProviderConfig
 end
 
 class MyARObject < ActiveRecord::Base
-  attribute :provider_config, 
-            :active_module, 
+  attribute :provider_config,
+            :active_module,
             possible_modules: ProviderConfig.all
 
   def load_page!
     n_attempts = 0
     result = nil
-    while n_attempts < provider.number_of_attempts
-      result = get_page(provider.url)
-      if(result)
+    while n_attempts < provider_config.number_of_attempts
+      result = get_page(provider_config.url)
+      if result
         return result
       else
-        n_attempts.inc
+        n_attempts += 1
       end
     end
     result
@@ -423,12 +480,61 @@ end
 MyARObject.create!(provider_config: :Ebay).load_page!
 ```
 
-### Rich Java/C#-like enums
-This example is only to show the possibility. 
-This would probably benefit from using a meta programming abstraction and we will provide something
-like that in the future.
+### Rich Java/C#-like enums with `active_module_enum`
+
+Java/C# enums allow defining methods on the enum, which are shared across all enum values.
+ActiveModule supports this pattern with `active_module_enum`, which generates query, bang,
+and scope methods for your active_module attributes.
+
+Nested modules can always be referenced using underscored names at any level of nesting.
+For example, given a deeply nested module:
+
+```ruby
+module Lime
+  module Banana
+    module Strawberry; end
+  end
+end
+
+class MyARObject < ActiveRecord::Base
+  attribute :fruit,
+            :active_module,
+            possible_modules: [Lime::Banana::Strawberry]
+end
+```
+
+All of the following resolve to `Lime::Banana::Strawberry`:
+
+```ruby
+MyARObject.create!(fruit: :strawberry)              # last segment only
+MyARObject.create!(fruit: :banana_strawberry)       # last two segments
+MyARObject.create!(fruit: :lime_banana_strawberry)  # all segments
+```
+
+This also works for querying:
+
+```ruby
+MyARObject.where(fruit: :banana_strawberry)
+```
+
+And for comparison (with `ActiveModule::Comparison`):
+
+```ruby
+module MyModuleOrClass
+  using ActiveModule::Comparison
+
+  def self.match?(mod, value)
+    mod =~ value
+  end
+end
+
+MyModuleOrClass.match?(Lime::Banana::Strawberry, :banana_strawberry) #=> true
+```
+
+#### `active_module_enum` — generating query, bang, and scope methods
 
-Java/C# enums allow defining methods on the enum, which are shared across all enum values:
+The `active_module_enum` method generates Rails-enum-style convenience methods
+for your active_module attributes:
 
 ```ruby
 module PipelineStage
@@ -438,55 +544,217 @@ module PipelineStage
     [InitialContact, InNegotiations, LostDeal, PaidOut]
   end
 
-  def cast(stage)
-    self.all.map(&:external_provider_code).find{|code| code == stage} ||
-    self.all.map(&:database_representation).find{|code| code == stage} ||
-    self.all.map(&:frontend_representation).find{|code| code == stage} 
-  end
-
   module Base
     def external_provider_code
       @external_provider_code ||= self.name.underscore
     end
 
-    def database_representation
-      self.name
-    end
-
     def frontend_representation
       @frontend_representation ||= self.name.demodulize.upcase
     end
   end
 
-  module InitialContact
-    extend Base
-  end
+  module InitialContact; extend Base; end
+  module InNegotiations; extend Base; end
+  module LostDeal; extend Base; end
+  module PaidOut; extend Base; end
+end
 
-  module InNegotiations
-    extend Base
-  end
+class MyARObject < ActiveRecord::Base
+  attribute :pipeline_stage,
+            :active_module,
+            possible_modules: PipelineStage.all
 
-  module LostDeal
-    extend Base
-  end
+  active_module_enum :pipeline_stage
+end
+```
+
+This generates:
 
-  module PaidOut
-    extend Base
+```ruby
+# Instance query methods (?)
+object = MyARObject.new(pipeline_stage: :initial_contact)
+object.initial_contact?                    #=> true
+object.lost_deal?                          #=> false
+
+# Instance bang methods (!) — set and save
+object.initial_contact!
+object.reload
+object.pipeline_stage #=> PipelineStage::InitialContact
+
+# Class-level scopes
+MyARObject.with_initial_contact            #=> ActiveRecord::Relation
+MyARObject.with_lost_deal                  #=> ActiveRecord::Relation
+
+# Class-level query methods (same as scopes)
+MyARObject.initial_contact                 #=> ActiveRecord::Relation
+```
+
+The pluralized attribute name method returns a hash mapping
+modules to their fully qualified names:
+
+```ruby
+MyARObject.pipeline_stages
+#=> { PipelineStage::InitialContact => "PipelineStage::InitialContact",
+#     PipelineStage::InNegotiations => "PipelineStage::InNegotiations",
+#     PipelineStage::LostDeal => "PipelineStage::LostDeal",
+#     PipelineStage::PaidOut => "PipelineStage::PaidOut" }
+
+MyARObject.pipeline_stages.keys   #=> [PipelineStage::InitialContact, ...]
+MyARObject.pipeline_stages.values #=> ["PipelineStage::InitialContact", ...]
+```
+
+All forms of underscored symbol names work for assignment and querying:
+
+```ruby
+MyARObject.create!(pipeline_stage: :initial_contact)
+MyARObject.create!(pipeline_stage: :in_negotiations)
+MyARObject.where(pipeline_stage: :lost_deal)
+MyARObject.where(pipeline_stage: :paid_out)
+```
+
+For nested modules, methods are generated at **all nesting levels**:
+
+```ruby
+module Lime
+  module Banana
+    module Strawberry; end
   end
 end
 
+class Fruit < ActiveRecord::Base
+  attribute :kind, :active_module,
+            possible_modules: [Lime::Banana::Strawberry]
+  active_module_enum :kind
+end
+
+object = Fruit.new(kind: :strawberry)
+object.strawberry?                 #=> true
+object.banana_strawberry?          #=> true (partial nesting)
+object.lime_banana_strawberry?     #=> true (full nesting)
+
+Fruit.with_banana_strawberry       #=> ActiveRecord::Relation
+```
+
+The pluralized attribute name method also works with nested modules.
+Each module maps to its fully qualified name:
+
+```ruby
+module StatusA; end
+module StatusB; end
+module Nested
+  module StatusA; end
+  module StatusB; end
+end
+
+class Fruit < ActiveRecord::Base
+  attribute :kind, :active_module,
+            possible_modules: [StatusA, StatusB,
+                               Nested::StatusA, Nested::StatusB]
+  active_module_enum :kind
+end
+
+Fruit.kinds
+#=> { StatusA => "StatusA", StatusB => "StatusB",
+#     Nested::StatusA => "Nested::StatusA",
+#     Nested::StatusB => "Nested::StatusB" }
+```
+
+All underscored forms work for assignment and querying:
+
+```ruby
+Fruit.create!(kind: :strawberry)
+Fruit.create!(kind: :banana_strawberry)
+Fruit.create!(kind: :lime_banana_strawberry)
+Fruit.where(kind: :banana_strawberry)
+```
+
+##### Options
+
+`active_module_enum` accepts the following options:
+
+```ruby
+active_module_enum :pipeline_stage,
+                   prefix: true,       # prefix method names with the attribute name
+                   suffix: true,       # suffix method names with the attribute name
+                   scope: true,        # generate with_ scopes (default: true)
+                   instance_methods: true,  # generate ? and ! methods (default: true)
+                   on_ambiguous: :warn # :warn or :silence (default: :warn)
+```
+
+- **`prefix: true`** — prefixes methods with the attribute name:
+  `pipeline_stage_initial_contact?`, `with_pipeline_stage_initial_contact`
+- **`prefix: "custom"`** — prefixes with a custom string:
+  `custom_initial_contact?`, `with_custom_initial_contact`
+- **`suffix: true`** — suffixes methods with the attribute name:
+  `initial_contact_pipeline_stage?`, `with_initial_contact_pipeline_stage`
+- **`suffix: "custom"`** — suffixes with a custom string:
+  `initial_contact_custom?`, `with_initial_contact_custom`
+- **`scope: false`** — skips scope generation
+- **`instance_methods: false`** — skips `?` and `!` method generation
+- **`on_ambiguous: :silence`** — suppresses warnings when multiple
+  modules share the same demodulized name (e.g. `Tino` and
+  `Banana::Tino` both producing `tino?`)
+
+##### Ambiguity resolution
+
+When two modules at different nesting levels produce the same demodulized
+name (e.g. `Status` and `Nested::Status` both mapping to `status?`),
+**the least-nested module always wins** across all contexts —
+assignment, querying, scopes, and enum methods:
+
+```ruby
+module Status; end
+module Nested
+  module Status; end
+end
+
 class MyARObject < ActiveRecord::Base
-  attribute :pipeline_stage, 
-            :active_module, 
-            possible_modules: PipelineStage.all
+  attribute :status, :active_module,
+            possible_modules: [Status, Nested::Status]
+  active_module_enum :status
 end
 
-object = MyARObject.new(pipeline_stage: :InitialStage)
-object.pipeline_stage&.frontend_representation #=> "INITIAL_STAGE"
-object.pipeline_stage = :InNegotiations
-object.pipeline_stage&.database_representation #=> "PipelineStage::InNegotiations"
+# Assignment resolves to the flat module
+object = MyARObject.new(status: :status)
+object.status         #=> Status (flat, not Nested::Status)
+
+# Querying resolves to the flat module
+MyARObject.where(status: :status)       # filters by Status
+MyARObject.find_by(status: "Status")    # finds Status
+
+# Enum query resolves to the flat module
+object.status?        #=> true (matches Status)
+object.nested_status? #=> true (use underscored name for Nested::Status)
+
+# Bang method resolves to the flat module
+object.status!
+object.reload
+object.status         #=> Status
 ```
 
+To access the nested module, always use its underscored form:
+
+```ruby
+object.nested_status?         #=> true
+object.nested_status!         #=> sets to Nested::Status
+MyARObject.with_nested_status #=> ActiveRecord::Relation filtering by Nested::Status
+```
+
+This resolution applies consistently to `with_` scopes, class-level
+query methods, `find_by`/`where`, and assignment via symbol or string —
+the least-nested module wins for the ambiguous name:
+
+```ruby
+MyARObject.create!(status: Nested::Status)
+MyARObject.create!(status: Status)
+
+MyARObject.status.count             #=> 1 (flat Status only)
+MyARObject.with_nested_status.count #=> 1 (Nested::Status only)
+```
+
+Note: when both `prefix: true` and `suffix: true` are set, only `prefix` takes
+effect.
 
 ## Development
 
@@ -497,3 +765,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/pedrorolo/active_module.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/active_module/base.rb

@@ -6,9 +6,7 @@ module ActiveModule
 
     def initialize(possible_modules_or_mapping = [],
                    possible_modules: [],
-                   mapping: {},
-                   enum_compatibility: false)
-      @enum_compatibility = enum_compatibility
+                   mapping: {})
       if possible_modules_or_mapping.is_a?(Array)
         @possible_modules =
           (possible_modules_or_mapping + possible_modules + mapping.keys).uniq
@@ -72,7 +70,7 @@ module ActiveModule
     end
 
     def str_to_module(str)
-      modules_index[str.to_sym] ||
+      modules_index[str] ||
         raise_invalid_module_value_error(str)
     end
 
@@ -93,9 +91,7 @@ module ActiveModule
     end
 
     def modules_index
-      @modules_index ||=
-        (@enum_compatibility ? Enum::ModulesIndex : ModulesIndex)
-        .new(@possible_modules)
+      @modules_index ||= ModulesIndex.new(@possible_modules)
     end
 
     def from_db

data/lib/active_module/enum/class_methods_definer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActiveModule
+  module Enum
+    module ClassMethodsDefiner
+      def define_class_query(attribute_name, mod,
+                             value_name, opts,
+                             existing)
+        name = enum_method_name(value_name, opts)
+        return if existing[:singleton]
+                  .include?(name.to_sym)
+        return if respond_to?(name)
+
+        define_singleton_method(name) do
+          where(attribute_name => mod)
+        end
+      end
+
+      def define_enum_scope(attribute_name, mod,
+                            value_name, opts,
+                            existing)
+        name = enum_method_name(value_name, opts)
+        scope_name = :"with_#{name}"
+        return if existing[:singleton]
+                  .include?(scope_name)
+        return if respond_to?(scope_name)
+
+        define_singleton_method(scope_name) do
+          where(attribute_name => mod)
+        end
+      end
+
+      def define_fields_method(attribute_name, modules)
+        fields = build_fields_map(modules)
+        name = attribute_name.to_s.pluralize
+        return if singleton_methods.include?(name.to_sym)
+        return if respond_to?(name)
+
+        define_singleton_method(name) { fields }
+      end
+
+      def build_fields_map(modules)
+        modules.each_with_object({}) do |mod, h|
+          h[mod] = mod.name
+        end
+      end
+    end
+  end
+end

data/lib/active_module/enum/instance_methods_definer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActiveModule
+  module Enum
+    module InstanceMethodsDefiner
+      def define_instance_methods(attribute_name, mod,
+                                  value_name, opts,
+                                  existing)
+        name = enum_method_name(value_name, opts)
+        define_if_new(
+          existing[:instance], :"#{name}?"
+        ) do
+          public_send(attribute_name) == mod
+        end
+        define_if_new(
+          existing[:instance], :"#{name}!"
+        ) do
+          public_send("#{attribute_name}=", mod)
+          save!
+        end
+      end
+    end
+  end
+end

data/lib/active_module/enum/util.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ActiveModule
+  module Enum
+    module Util
+      using ModuleRefinement
+
+      def determine_prefix(attribute_name, prefix, suffix)
+        if prefix.is_a?(String)
+          prefix
+        elsif prefix == true ||
+              (prefix.nil? && suffix == true &&
+               !prefix.nil?)
+          prefix == true ? attribute_name.to_s : nil
+        end
+      end
+
+      def determine_suffix(attribute_name, prefix, suffix)
+        if suffix.is_a?(String)
+          suffix
+        elsif suffix == true && prefix != true
+          attribute_name.to_s
+        end
+      end
+
+      def enum_method_name(value_name, opts)
+        [opts[:prefix], value_name, opts[:suffix]]
+          .compact.join("_")
+      end
+
+      def define_if_new(existing, name, &block)
+        return if existing.include?(name)
+        return if new.respond_to?(name)
+
+        define_method(name, &block)
+      end
+
+      def warn_if_ambiguous(mod, value_name, opts, maps)
+        return unless maps[:ambiguity][value_name]&.size&.> 1
+        return if opts[:on_ambiguous] == :silence
+
+        name = enum_method_name(value_name, opts)
+        alts = (maps[:unique][mod] || [])
+               .map { |a| "`#{a}`" }
+        warn("WARNING: `#{name}` is ambiguous. " \
+             "Use #{alts.join(", ")} for " \
+             "unambiguous access. " \
+             "Pass on_ambiguous: :silence " \
+             "to suppress this warning.")
+      end
+
+      def build_name_maps(modules)
+        ambiguity = build_ambiguity_map(modules)
+        unique = build_unique_names_map(
+          modules, ambiguity
+        )
+        { ambiguity: ambiguity, unique: unique }
+      end
+
+      def build_ambiguity_map(modules)
+        modules.each_with_object({}) do |mod, h|
+          mod.underscored_names.each do |name|
+            (h[name] ||= []) << mod
+          end
+        end
+      end
+
+      def build_unique_names_map(modules, ambiguity)
+        modules.each_with_object({}) do |mod, h|
+          mod.underscored_names.each do |name|
+            next if ambiguity[name].size > 1
+
+            (h[mod] ||= []) << name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_module/enum.rb

@@ -1,6 +1,91 @@
 # frozen_string_literal: true
 
 module ActiveModule
-  class Enum
+  module Enum
+    using ModuleRefinement
+    include Util
+    include InstanceMethodsDefiner
+    include ClassMethodsDefiner
+
+    def active_module_enum(attribute_name,
+                           prefix: nil,
+                           suffix: nil,
+                           scope: true,
+                           **options)
+      type = attribute_types[attribute_name.to_s]
+      unless type.is_a?(ActiveModule::Base)
+        raise ArgumentError,
+              "#{attribute_name} is not " \
+              "an active_module attribute"
+      end
+      opts = build_enum_opts(
+        attribute_name, prefix, suffix,
+        scope, options
+      )
+      mods = type.possible_modules
+      define_enum_methods(attribute_name, mods, opts)
+      define_fields_method(attribute_name, mods)
+    end
+
+    private
+
+    def build_enum_opts(attribute_name, prefix,
+                        suffix, scope, options)
+      {
+        prefix: determine_prefix(
+          attribute_name, prefix, suffix
+        ),
+        suffix: determine_suffix(
+          attribute_name, prefix, suffix
+        ),
+        scope: scope,
+        instance_methods: options.fetch(
+          :instance_methods, true
+        ),
+        on_ambiguous: options.fetch(
+          :on_ambiguous, :warn
+        )
+      }
+    end
+
+    def define_enum_methods(attribute_name, modules, opts)
+      sorted = modules
+               .sort_by { |m| m.name.count("::") }
+      maps = build_name_maps(sorted)
+      existing = {
+        instance: instance_methods,
+        singleton: singleton_methods
+      }
+      sorted.each do |mod|
+        generate_methods(
+          attribute_name, mod, opts, maps, existing
+        )
+      end
+    end
+
+    def generate_methods(attribute_name, mod, opts,
+                         maps, existing)
+      mod.underscored_names.each do |value_name|
+        warn_if_ambiguous(mod, value_name, opts, maps)
+        if opts[:instance_methods]
+          define_instance_methods(
+            attribute_name, mod, value_name,
+            opts, existing
+          )
+        end
+        if opts[:instance_methods]
+          define_class_query(
+            attribute_name, mod, value_name,
+            opts, existing
+          )
+        end
+        next unless opts[:scope]
+
+        define_enum_scope(
+          attribute_name, mod, value_name,
+          opts, existing
+        )
+      end
+    end
   end
 end

data/lib/active_module/module_refinement.rb

@@ -4,23 +4,37 @@ module ActiveModule
   module ModuleRefinement
     refine ::Module do
       def possible_names
-        name_parts = name.split("::")
-        [qualified_name].tap do |possible_names|
-          loop do
-            possible_names << name_parts.join("::").freeze
-            name_parts = name_parts.drop(1)
-            break if name_parts.empty?
-          end
-        end
+        underscored_names + colon_delimited_names
       end
 
       def possible_symbol_names_set
-        @possible_symbol_names_set ||= Set.new(possible_names.map(&:to_sym))
+        @possible_symbol_names_set ||=
+          Set.new(possible_names.map(&:to_sym))
       end
 
       def qualified_name
         "::#{name}"
       end
+
+      def underscored_names
+        parts = name.split("::")
+        (1..parts.length).map do |i|
+          parts.last(i).map(&:underscore).join("_")
+        end
+      end
+
+      private
+
+      def colon_delimited_names
+        name_parts = name.split("::")
+        [qualified_name].tap do |names|
+          loop do
+            names << name_parts.join("::").freeze
+            name_parts = name_parts.drop(1)
+            break if name_parts.empty?
+          end
+        end
+      end
     end
   end
 end

data/lib/active_module/modules_index.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/hash/indifferent_access"
+
 # Indexes modules by symbols of their qualified and unqualified names.
 module ActiveModule
   class ModulesIndex
@@ -22,11 +24,13 @@ module ActiveModule
 
     def index
       @index ||=
-        @modules.flat_map do |module_instance|
+        @modules
+        .sort_by { |m| -m.name.count("::") }
+        .flat_map do |module_instance|
           possible_names(module_instance).map do |name|
             [name.to_sym, module_instance]
           end
-        end.to_h.freeze
+        end.to_h.with_indifferent_access.freeze
     end
   end
 end

data/lib/active_module/register.rb

@@ -12,6 +12,7 @@ module ActiveModule
 
       require "active_record"
       ActiveRecord::Type.register(type_symbol, ActiveModule::Base)
+      ActiveRecord::Base.extend(ActiveModule::Enum)
     end
   end
 end

data/lib/active_module/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveModule
-  VERSION = "0.6.8"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_module
 version: !ruby/object:Gem::Version
-  version: 0.6.8
+  version: 0.8.0
 platform: ruby
 authors:
 - Pedro Rolo
@@ -13,9 +13,9 @@ dependencies:
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 8.1.3
+        version: '8.2'
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
@@ -23,9 +23,29 @@ dependencies:
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 8.1.3
+        version: '8.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
@@ -73,9 +93,9 @@ files:
 - lib/active_module/base.rb
 - lib/active_module/comparison.rb
 - lib/active_module/enum.rb
-- lib/active_module/enum/comparison.rb
-- lib/active_module/enum/module_refinement.rb
-- lib/active_module/enum/modules_index.rb
+- lib/active_module/enum/class_methods_definer.rb
+- lib/active_module/enum/instance_methods_definer.rb
+- lib/active_module/enum/util.rb
 - lib/active_module/invalid_module_value.rb
 - lib/active_module/module_refinement.rb
 - lib/active_module/modules_index.rb

data/lib/active_module/enum/comparison.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module ActiveModule
-  class Enum
-    module Comparison
-      refine ::Module do
-        using ActiveModule::Enum::ModuleRefinement
-
-        def =~(other)
-          case other
-          when ::Symbol
-            possible_symbol_names_set.include?(other)
-          when ::String
-            possible_symbol_names_set.include?(other.to_sym)
-          else
-            self == other
-          end
-        end
-      end
-
-      using self
-
-      def self.compare(module1, module2)
-        module1 =~ module2
-      end
-    end
-  end
-end

data/lib/active_module/enum/module_refinement.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module ActiveModule
-  class Enum
-    module ModuleRefinement
-      refine ::Module do
-        using ActiveModule::ModuleRefinement
-
-        def possible_names
-          overriden_possible_names
-        end
-
-        def enum_symbol
-          name.demodulize.underscore.to_sym
-        end
-
-        def possible_symbol_names_set
-          @possible_symbol_names_set ||=
-            Set.new(overriden_possible_names.map(&:to_sym))
-        end
-
-        private
-
-        def overriden_possible_names
-          [enum_symbol.to_s] + possible_names
-        end
-      end
-
-      using self
-    end
-  end
-end

data/lib/active_module/enum/modules_index.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "module_refinement"
-
-# Indexes modules by symbols of their qualified and unqualified names.
-module ActiveModule
-  class Enum
-    class ModulesIndex < ActiveModule::ModulesIndex
-      using ActiveModule::Enum::ModuleRefinement
-
-      protected
-
-      # so that this is using the enum refinement
-      def possible_names(module_instance)
-        module_instance.possible_names
-      end
-    end
-  end
-end