anchormodel 0.3.0 → 0.4.0

data/lib/anchormodel/util.rb

@@ -1,16 +1,29 @@
-# @api description
-# A swiss army knife for common functionality
+# Internal utilities used by the {Anchormodel::ModelMixin#belongs_to_anchormodel} and
+# {Anchormodel::ModelMixin#belongs_to_anchormodels} macros. The public-facing entry
+# points are the macros themselves; methods here are the wiring that installs the
+# generated readers, writers, scopes, type casters, and helper scopes.
 module Anchormodel::Util
-  # Installs an anchormodel attribute in a model class
-  # @param model_class [ActiveRecord::Base] Internal only. The model class that the attribute should be installed to.
-  # @param attribute_name [String,Symbol] The name and database column of the attribute
-  # @param anchormodel_class [Class] Class of the Anchormodel (omit if attribute `:foo_bar` holds a `FooBar`)
-  # @param optional [Boolean] If false, a presence validation is added to the model. Forced to true if multiple is true.
-  # @param multiple [Boolean] Internal only. Distinguishes between `belongs_to_anchormodel` and `belongs_to_anchormodels`.
-  # @param model_readers [Boolean] If true, the model is given an ActiveRecord::Enum style method `my_model.my_key?` reader for each key in the anchormodel
-  # @param model_writers [Boolean] If true, the model is given an ActiveRecord::Enum style method `my_model.my_key!` writer for each key in the anchormodel
-  # @param model_scopes [Boolean] If true, the model is given an ActiveRecord::Enum style scope `MyModel.mykey` for each key in the anchormodel
-  # @param model_methods [Boolean, NilClass] If non-nil, this mass-assigns and overrides `model_readers`, `model_writers` and `model_scopes`
+  # Installs an anchormodel attribute in a model class. Wires up the AR `attribute`
+  # type cast, the custom reader/writer, the per-key readers/writers/scopes, and (for
+  # `belongs_to_anchormodels`) the bulk-key `with_any_<attr>` / `with_all_<attr>` scopes.
+  #
+  # Called from {Anchormodel::ModelMixin#belongs_to_anchormodel} and
+  # {Anchormodel::ModelMixin#belongs_to_anchormodels}. Not normally invoked directly.
+  #
+  # @param model_class [Class] Internal only. The model class the attribute is installed on.
+  # @param attribute_name [String,Symbol] The name and database column of the attribute.
+  # @param anchormodel_class [Class,nil] The anchormodel class. If omitted, inferred from
+  #   `attribute_name` (`:foo_bar` → `FooBar`).
+  # @param optional [Boolean] If false, a presence validation is added to the model. Forced
+  #   to true when `multiple` is true.
+  # @param multiple [Boolean] Internal only. Distinguishes between `belongs_to_anchormodel`
+  #   (false) and `belongs_to_anchormodels` (true).
+  # @param model_readers [Boolean] If true, generates `model.key?` readers per anchormodel key.
+  # @param model_writers [Boolean] If true, generates `model.key!` writers per anchormodel key.
+  # @param model_scopes [Boolean] If true, generates `Model.key` scopes per anchormodel key.
+  # @param model_methods [Boolean,nil] If non-nil, mass-overrides `model_readers`/`model_writers`/`model_scopes`.
+  # @return [void]
+  # @raise [RuntimeError] if a generated method or scope name collides with an existing one.
   def self.install_methods_in_model(model_class, attribute_name, anchormodel_class = nil,
                                     optional: false,
                                     multiple: false,
@@ -129,21 +142,93 @@ module Anchormodel::Util
     end
 
     # Create ActiveRecord::Enum style scope directly in the model class if asked to do so
-    # For a model User with anchormodel Role with keys :admin and :guest, this creates user.admin! and user.guest! (setting the role to admin/guest)
+    # For a model User with anchormodel Role with keys :admin and :guest, this creates User.admin and User.guest scopes
     if model_scopes
       anchormodel_class.all.each do |entry|
         if model_class.respond_to?(entry.key)
           fail("Anchormodel scope #{entry.key} already defined for #{self}, add `model_scopes: false` to `belongs_to_anchormodel :#{attribute_name}`.")
         end
         if multiple
-          model_class.scope(entry.key, lambda {
-                                         where("#{attribute_name} LIKE ? OR #{attribute_name} LIKE ? OR #{attribute_name} LIKE ? OR #{attribute_name} LIKE ?",
-                                               "%#{entry.key},%", "%#{entry.key}", "#{entry.key},%", entry.key.to_s)
-                                       })
+          sql, *binds = Anchormodel::Util.csv_contains_like(attribute_name, entry.key)
+          model_class.scope(entry.key, -> { where(sql, *binds) })
         else
           model_class.scope(entry.key, -> { where(attribute_name => entry.key) })
         end
       end
     end
+
+    # For `belongs_to_anchormodels`, add bulk-key scopes since `where(col: array)` cannot
+    # match CSV-in-column storage. Defined regardless of `model_scopes` — they are bulk
+    # query helpers, not per-key scopes.
+    if multiple
+      model_class.scope(:"with_any_#{attribute_name}", lambda do |*keys|
+        keys = Anchormodel::Util.normalize_anchormodel_keys(keys, anchormodel_class)
+        next none if keys.empty?
+
+        clauses = keys.map { |k| Anchormodel::Util.csv_contains_like(attribute_name, k) }
+        sql = clauses.map { |c| "(#{c.first})" }.join(' OR ')
+        binds = clauses.flat_map { |c| c.drop(1) }
+        where(sql, *binds)
+      end)
+
+      model_class.scope(:"with_all_#{attribute_name}", lambda do |*keys|
+        keys = Anchormodel::Util.normalize_anchormodel_keys(keys, anchormodel_class)
+        next all if keys.empty?
+
+        keys.reduce(all) { |rel, k| rel.merge(public_send(:"with_any_#{attribute_name}", k)) }
+      end)
+    end
+  end
+
+  # Coerces a list of mixed-type key inputs into validated key Strings, ready for SQL binding.
+  # Accepts Strings, Symbols, Anchormodel instances, and arbitrarily nested arrays of those.
+  #
+  # @param keys [Array] Input list (flattened internally).
+  # @param anchormodel_class [Class] The anchormodel class against which keys are validated.
+  # @return [Array<String>] Flattened, stringified, validated keys.
+  # @raise [Anchormodel::InvalidKey] if any element is not a registered key.
+  # @example
+  #   Anchormodel::Util.normalize_anchormodel_keys([:cat, 'dog', Animal.find(:horse)], Animal)
+  #   # => ["cat", "dog", "horse"]
+  def self.normalize_anchormodel_keys(keys, anchormodel_class)
+    keys = keys.flatten.map { |k| k.respond_to?(:key) ? k.key.to_s : k.to_s }
+    keys.each { |k| anchormodel_class.find(k) }
+    keys
+  end
+
+  # Builds a `WHERE` fragment matching rows whose CSV-stored `attribute` column contains
+  # `key`. Generates four predicates OR'd together to cover the cases where `key` appears
+  # at the start, end, middle, or as the sole entry in the CSV.
+  #
+  # `_` and `%` characters in `key` are escaped via `ESCAPE '!'` so that LIKE wildcards
+  # in the key (e.g. `:big_cat`) are treated literally instead of cross-matching arbitrary
+  # column values like `"bigXcat,foo"`.
+  #
+  # @param attribute [String,Symbol] Column name to query.
+  # @param key [String,Symbol] Key to search for inside the CSV column value.
+  # @return [Array(String, *String)] `[sql_fragment, *bind_values]`, suitable for splatting
+  #   into `Model.where(sql, *binds)`.
+  # @example
+  #   sql, *binds = Anchormodel::Util.csv_contains_like(:animals, :cat)
+  #   User.where(sql, *binds)
+  def self.csv_contains_like(attribute, key)
+    escaped = escape_like(key.to_s)
+    sql = "#{attribute} = ? OR #{attribute} LIKE ? ESCAPE '!' " \
+          "OR #{attribute} LIKE ? ESCAPE '!' OR #{attribute} LIKE ? ESCAPE '!'"
+    binds = [key.to_s, "#{escaped},%", "%,#{escaped}", "%,#{escaped},%"]
+    [sql, *binds]
+  end
+
+  # Escapes `_`, `%`, and `!` so the string can be used as a literal inside a SQL `LIKE`
+  # pattern paired with `ESCAPE '!'`. Uses `!` rather than the conventional `\` to avoid
+  # the cross-DB ambiguity of backslash inside SQL string literals (SQLite vs MySQL vs
+  # PostgreSQL all differ).
+  #
+  # @param str [String,Symbol] Input to escape.
+  # @return [String] Escaped string.
+  # @example
+  #   Anchormodel::Util.escape_like('big_cat') # => "big!_cat"
+  def self.escape_like(str)
+    str.to_s.gsub(/[!%_]/) { |c| "!#{c}" }
   end
 end

data/lib/anchormodel.rb

@@ -1,8 +1,39 @@
-# @api description
-# Inherit from this class and place your Anchormodel under `app/anchormodels/your_anchor_model.rb`. Use it like `YourAnchorModel`.
-# Refer to the README for usage.
+# An Anchormodel is a registry of named constants that behave like first-class objects.
+# It is a richer alternative to Rails Enums: each entry is a real Ruby instance that can
+# carry behavior and per-key attributes while still being persistable to a String column
+# in the database.
+#
+# Place anchormodel subclasses under `app/anchormodels/your_anchor_model.rb` so Rails
+# autoloading picks them up. Refer to the README for usage.
+#
+# @example Define an anchormodel
+#   class Role < Anchormodel
+#     include Comparable
+#     attr_reader :privilege_level
+#
+#     def <=>(other) = privilege_level <=> other.privilege_level
+#
+#     new :guest,   privilege_level: 0
+#     new :manager, privilege_level: 1
+#     new :admin,   privilege_level: 2
+#   end
+#
+# @example Use it from an ActiveRecord model
+#   class User < ApplicationRecord
+#     belongs_to_anchormodel :role
+#   end
+#
+#   user = User.create!(role: :admin)
+#   user.role                   # => #<Role<admin>:...>
+#   user.role.privilege_level   # => 2
+#   user.admin?                 # => true
 class Anchormodel
+  # @!attribute [r] key
+  #   @return [Symbol] The key under which this entry was registered.
   attr_reader :key
+
+  # @!attribute [r] index
+  #   @return [Integer] Zero-based declaration order within the subclass.
   attr_reader :index
 
   class_attribute :setup_completed, default: false
@@ -10,8 +41,14 @@ class Anchormodel
   class_attribute :entries_hash, default: {} # For quick access
   class_attribute :valid_keys, default: Set.new
 
-  # When a descendant of Anchormodel is first used, it must overwrite the class_attributes
-  # to prevent cross-class pollution.
+  # Initializes the per-subclass registry on first use. Called automatically from
+  # the first `new` invocation. Each subclass gets its own duped copies of the
+  # registry class attributes to prevent cross-class pollution.
+  #
+  # You normally do not need to call this directly.
+  #
+  # @return [void]
+  # @raise [RuntimeError] if called twice for the same subclass.
   def self.setup!
     fail("`setup!` was called twice for Anchormodel subclass #{self}.") if setup_completed
     self.entries_list = entries_list.dup
@@ -20,31 +57,61 @@ class Anchormodel
     self.setup_completed = true
   end
 
-  # Returns all possible values this Anchormodel can take.
+  # @return [Array<Anchormodel>] All registered entries of this subclass, in declaration order.
+  # @example
+  #   Role.all # => [#<Role<guest>>, #<Role<manager>>, #<Role<admin>>]
   def self.all
     entries_list
   end
 
-  # Shorthand to satisfy rubocop
+  # Shorthand for `all.first`. Provided so callers can avoid Rubocop's
+  # `Style/FirstElementInCollection`-style warnings on `Foo.all.first`.
+  # @return [Anchormodel,nil] The first registered entry, or `nil` if the registry is empty.
   def self.first
     all.first
   end
 
-  # Returns an array of tuples [label, key] suitable for passing as a collection to some form input helpers
+  # Builds a `[label, key_string]` tuple list suitable for Rails form select helpers.
+  # @return [Array<Array(String,String)>]
+  # @example
+  #   <%= form.select :role, Role.form_collection %>
   def self.form_collection
     entries_list.map { |el| [el.label, el.key.to_s] }
   end
 
-  # Retrieves a particular value given the key. Fails if not found.
-  # @param key [String,Symbol] The key of the value that should be retrieved.
+  # Raised when an anchormodel key is unknown to its class — i.e. no `new :that_key`
+  # call was made on the subclass.
+  #
+  # Inherits from `RuntimeError` so existing `rescue RuntimeError` blocks remain
+  # compatible while allowing the narrower `rescue Anchormodel::InvalidKey`.
+  class InvalidKey < RuntimeError; end
+
+  # Retrieves the entry registered under `key`.
+  #
+  # @param key [String,Symbol,nil] The key of the value that should be retrieved.
+  # @return [Anchormodel,nil] The matching entry, or `nil` if `key` is `nil`.
+  # @raise [Anchormodel::InvalidKey] if no entry with that key exists.
+  # @example
+  #   Role.find(:admin)   # => #<Role<admin>>
+  #   Role.find('admin')  # => #<Role<admin>>   (same singleton instance)
+  #   Role.find(nil)      # => nil
+  #   Role.find(:nope)    # raises Anchormodel::InvalidKey
   def self.find(key)
     return nil if key.nil?
-    return entries_hash[key.to_sym] || fail("Retreived undefined anchor model key #{key.inspect} for #{inspect}.")
+    return entries_hash[key.to_sym] || raise(InvalidKey, "Retrieved undefined anchor model key #{key.inspect} for #{inspect}.")
   end
 
-  # Call this initializer directly in your Anchormodel class. To set `@foo=:bar` for anchor `:ter`, use `new(:ter, foo: :bar)`
-  # @param key [String,Symbol] The key under which the entry should be stored.
-  # @param attributes All named arguments to Anchormodel are made available as instance attributes.
+  # Registers a new entry. Called in the body of an Anchormodel subclass.
+  # All keyword arguments become instance attributes accessible via `attr_reader`.
+  #
+  # @param key [String,Symbol] The unique key under which the entry is registered.
+  # @param attributes [Hash] Arbitrary attributes exposed as instance variables.
+  # @raise [RuntimeError] if `key` is already registered for this subclass.
+  # @example
+  #   class Role < Anchormodel
+  #     attr_reader :privilege_level
+  #     new :guest, privilege_level: 0
+  #   end
   def initialize(key, **attributes)
     self.class.setup! unless self.class.setup_completed
 
@@ -70,23 +137,50 @@ class Anchormodel
     end
   end
 
+  # Two anchormodels are equal iff they have the same concrete class and key.
+  # Different subclasses sharing a key are not equal.
+  # @param other [Object]
+  # @return [Boolean]
   def ==(other)
     self.class == other.class && key == other.key
   end
+  alias eql? ==
+
+  # Hash matches `==` (class + key) so `Set` and `Hash` membership work correctly
+  # even for copies (`dup`, Marshal round-trip) of the singleton entries.
+  # @return [Integer]
+  def hash
+    [self.class, key].hash
+  end
 
-  # Returns a Rails label that is compatible with the [Rails FastGettext](https://github.com/grosser/gettext_i18n_rails/) gem.
+  # Returns a translatable label for this entry, compatible with the
+  # [Rails FastGettext](https://github.com/grosser/gettext_i18n_rails/) gem.
+  # The translation key is `"<SubclassName>|<Humanized key>"`.
+  # @return [String]
+  # @example
+  #   Role.find(:admin).label # => "Role|Admin" (or its I18n translation)
   def label
     I18n.t("#{self.class.name.demodulize}|#{key.to_s.humanize}")
   end
 
+  # @return [String] Debug representation like `"#<Role<admin>:HASH>"`.
   def inspect
     "#<#{self.class.name}<#{key}>:#{hash}>"
   end
 
+  # Same as {#inspect}. Anchormodel intentionally overrides `to_s` so string
+  # interpolation in templates is unambiguous; render `#label` or `#key` directly
+  # if you want a user-facing form.
+  # @return [String]
   def to_s
     inspect
   end
 
+  # JSON serialization returns the key as a String so anchormodels round-trip
+  # cleanly through JSON (e.g. for API payloads).
+  # @return [String]
+  # @example
+  #   Role.find(:admin).as_json # => "admin"
   def as_json
     key.to_s
   end

data/lib/generators/anchormodel/anchormodel_generator.rb

@@ -1,6 +1,14 @@
+# Rails generator for scaffolding a new anchormodel.
+#
+# @example
+#   rails generate anchormodel Role
+#   # → creates app/anchormodels/role.rb
 class AnchormodelGenerator < Rails::Generators::NamedBase
   source_root File.expand_path('templates', __dir__)
 
+  # Writes the new anchormodel file from the ERB template.
+  # @return [void]
+  # @raise [RuntimeError] if NAME is blank.
   def add_anchormodel
     fail('NAME must be present.') if name.blank?
     @klass = @name.camelize