inheritance-helper 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 562ea69d6c46e724638823857ec7df66ec87408b00c541cd63ce34f69fd9f1e7
-  data.tar.gz: 806d2e7ba749dd237e4588794d393aaaf29b76b9c54f41d7174335145d51326b
+  metadata.gz: 5d1e8987c76ed0af5063986813c435c9e755bce6f0d145ab7d63e9f0a35ba0f9
+  data.tar.gz: f1c481bd51c45d74e3e36a6e95fe656e29457fb489a9d99a1760539554577462
 SHA512:
-  metadata.gz: 9cb15000be0f56dd9a8fb48881d7766a07aee34d4330a67c049cbb8370646cccdf4d3a3d6c63f321b18dca91b9bd89ae103a6c9d0f93b339c193f3292a498d95
-  data.tar.gz: 865ea2dbce6c43fdd02424e6936bf385d14e61e5ca5b8904a35f7e628bf142cc2ed332c6d66235789330839522cef3e1d8379b7d37a8e5154b069bb92637de4f
+  metadata.gz: c67b0fb5d1bbdcb65186c689c9e088739132de2cda3cc3d44ef51f131b868c64f73a4df073dfe8f4171257dedd4d8770af3dac7e47b451ca605574766c7add21
+  data.tar.gz: 7ef84095e953df92ee231e364ee9446e2020ee9f2d1fe9063c847bf389e13e594abe153c428669ef9f7e1f0ac00dd62b564790592fae2628622ffa80ee6cf386

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.3.0](https://github.com/dougyouch/inheritance-helper/compare/v0.2.6...v0.3.0) (2026-10-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* get_class_name no longer calls String#classify when ActiveSupport is loaded, so names are no longer singularized there (:line_items now gives LineItems, not LineItem). Class names are now the same whether or not ActiveSupport is loaded.
+
+### 1.0
+
+* clearer nil error, consistent class names, Ruby 3.3 ([#5](https://github.com/dougyouch/inheritance-helper/issues/5)) ([11bb5a8](https://github.com/dougyouch/inheritance-helper/commit/11bb5a8d056d7b6c2794895bd01c9d9bce14805d))
+
+## [0.2.6](https://github.com/dougyouch/inheritance-helper/compare/v0.2.5...v0.2.6) (2026-10-05)
+
+
+### Bug Fixes
+
+* **class-builder:** handle repeated and trailing underscores in class names ([92488f2](https://github.com/dougyouch/inheritance-helper/commit/92488f260e9da03693745c46c9064cafb1f2159f))
+* **methods:** keep the visibility of redefined class methods ([5cd1f79](https://github.com/dougyouch/inheritance-helper/commit/5cd1f79529de471c27249a163b6de66cc45d9453))

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Douglas Youch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,239 @@
+# inheritance-helper
+
+Class-level settings that subclasses can extend without changing their parents.
+
+[![CI](https://github.com/dougyouch/inheritance-helper/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/dougyouch/inheritance-helper/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/dougyouch/inheritance-helper/badges/coverage.svg)](https://github.com/dougyouch/inheritance-helper/actions/workflows/ci.yml)
+[![Branch Coverage](https://raw.githubusercontent.com/dougyouch/inheritance-helper/badges/branches.svg)](https://github.com/dougyouch/inheritance-helper/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/inheritance-helper.svg)](https://rubygems.org/gems/inheritance-helper)
+
+[API reference](https://rubydoc.info/gems/inheritance-helper) · [Changelog](CHANGELOG.md)
+
+DSLs often collect data at the class level: attributes, options, callbacks. With a class instance variable,
+subclasses don't see the parent's data. With a class variable (`@@attributes`), every class in the chain
+shares and changes the same object. `inheritance-helper` avoids both: each call replaces the class method on
+the class it's called on, so a subclass starts with its parent's value, adds to it, and the parent keeps its
+own.
+
+It has no dependencies. It is used by [schema-model](https://github.com/dougyouch/schema) to collect
+attribute definitions.
+
+## Installation
+
+Requires Ruby 3.3 or newer. Add this line to your application's Gemfile:
+
+```ruby
+gem 'inheritance-helper'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Usage
+
+Extend a class with `InheritanceHelper::Methods` and define a class method that returns the starting value.
+Freezing the value is recommended: values built from a frozen value are frozen too, so no class can change
+another's data by mutating it.
+
+```ruby
+require 'inheritance-helper'
+
+class Model
+  extend InheritanceHelper::Methods
+
+  def self.attributes
+    {}.freeze
+  end
+
+  def self.attribute(name, type)
+    add_value_to_class_method(:attributes, name => type)
+    attr_accessor name
+  end
+end
+
+class Person < Model
+  attribute :name, :string
+  attribute :phone, :string
+end
+
+class Employee < Person
+  attribute :employee_id, :integer
+end
+
+Model.attributes     # => {}
+Person.attributes    # => {name: :string, phone: :string}
+Employee.attributes  # => {name: :string, phone: :string, employee_id: :integer}
+```
+
+### add_value_to_class_method
+
+Redefines a class method to return its current value with more added:
+
+- a **Hash** is merged with the new hash
+- an **Array** or **Set** is combined with `Array(value)`, so an array of values adds each one and the
+  result stays flat
+
+```ruby
+class Base
+  extend InheritanceHelper::Methods
+
+  def self.fields = [].freeze
+  def self.tags = Set.new.freeze
+end
+
+class Child < Base
+  add_value_to_class_method :fields, :name
+  add_value_to_class_method :fields, %i[email phone]
+  add_value_to_class_method :tags, :admin
+end
+
+Child.fields  # => [:name, :email, :phone]
+Child.tags    # => Set[:admin]
+Base.fields   # => []
+```
+
+### append_value_to_class_method
+
+Redefines a class method to return its current array with one element appended. Unlike
+`add_value_to_class_method`, an array is added as a single element:
+
+```ruby
+class Base
+  extend InheritanceHelper::Methods
+
+  def self.callbacks = [].freeze
+
+  def self.before_save(*methods)
+    append_value_to_class_method(:callbacks, methods)
+  end
+end
+
+class Child < Base
+  before_save :normalize, :validate
+  before_save :log
+end
+
+Child.callbacks  # => [[:normalize, :validate], [:log]]
+```
+
+### redefine_class_method
+
+Replaces a class method with one that returns the given value. Use it for settings that are replaced rather
+than added to:
+
+```ruby
+class Base
+  extend InheritanceHelper::Methods
+
+  def self.table_name = 'records'
+
+  def self.table(name)
+    redefine_class_method(:table_name, name.freeze)
+  end
+end
+
+class User < Base
+  table 'users'
+end
+
+User.table_name  # => "users"
+Base.table_name  # => "records"
+```
+
+The method returns the same object on every call, so freeze values that callers shouldn't change. The new
+method keeps the visibility of the one it replaces, so a private class method stays private.
+
+`InheritanceHelper::Methods.redefine_class_method(klass, method, value)` does the same for a class that
+doesn't extend the module.
+
+### Copy nested values before changing them
+
+Once a value is set with these helpers, every call returns the same object, and a subclass starts with its
+parent's object. Freezing covers only the top-level value: a hash or array *inside* it is shared by the parent
+and the subclass, so changing it in place changes both:
+
+```ruby
+class Base
+  extend InheritanceHelper::Methods
+
+  def self.config = {}.freeze
+
+  add_value_to_class_method :config, skip: []
+end
+
+class Child < Base
+  # wrong: appends to Base.config[:skip] too
+  config[:skip] << :logs
+
+  # right: build a new nested value and replace the key
+  add_value_to_class_method :config, skip: config[:skip] + [:logs]
+end
+```
+
+The same applies to a value from `redefine_class_method`: `dup` the value (and any nested values you change)
+before changing it, then pass the copy to `redefine_class_method`.
+
+### Notes
+
+- The class method must already return a value: `add_value_to_class_method` and
+  `append_value_to_class_method` call it to get the current value, and raise a `TypeError` naming the method
+  when it returns `nil`.
+- Each call defines a method on the class's singleton class. Classes declared at load time (the usual DSL
+  case) are fine; redefining class methods from several threads at once is not synchronized.
+
+## ClassBuilder::Utils
+
+`InheritanceHelper::ClassBuilder::Utils` creates named classes at runtime, which is useful for DSLs that
+build nested classes (such as a `has_many :items do ... end` block):
+
+```ruby
+module Shop; end
+
+klass = InheritanceHelper::ClassBuilder::Utils.create_class(Shop, :line_item, nil, 'Schema', nil) do
+  attr_accessor :quantity
+end
+
+klass       # => Shop::SchemaLineItem
+klass.name  # => "Shop::SchemaLineItem"
+
+InheritanceHelper::ClassBuilder::Utils.get_class_name(:line_item, 'Has', 'Class')
+# => "HasLineItemClass"
+```
+
+`create_class(base_module, name, base_class, prefix, suffix, &block)` subclasses `base_class` (or `Object` when
+`nil`), assigns it to the constant in `base_module`, and evaluates the block in the new class. If the constant
+already exists it is replaced, with Ruby's "already initialized constant" warning.
+
+`get_class_name` splits the name on underscores and capitalizes the first letter of each part, so
+`line_items` becomes `LineItems`. The result is the same whether or not ActiveSupport is loaded (before 1.0 it
+used `String#classify`, which singularized the name).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # tests, with line and branch coverage in coverage/
+bundle exec rubocop    # lint
+bundle exec yard doc   # API docs in doc/
+```
+
+CI requires 100% line and branch coverage, no RuboCop offenses, and every public method documented with YARD.
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please): conventional
+commits on `master` (`fix:`, `feat:`) update a release PR, and merging it tags the release and publishes the
+gem.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/inheritance-helper/class_builder/utils.rb

@@ -1,31 +1,48 @@
 # frozen_string_literal: true
 
 module InheritanceHelper
-  # Utility methods for building dynamic classes
   module ClassBuilder
+    # Functions for creating named classes inside a module.
+    #
+    # @example
+    #   InheritanceHelper::ClassBuilder::Utils.create_class(MyApp, :line_item, Struct.new(:id), 'Schema', nil)
+    #   # => MyApp::SchemaLineItem
     module Utils
       module_function
 
-      def get_class_name(name, preffix_class_name, postfix_class_name)
-        name = name.to_s
-
-        class_name =
-          if name.respond_to?(:classify)
-            name.classify
-          else
-            # simple naive method to convert a string to a class name
-            name.gsub(/(^.|_.)/) { |_| ($1[1] || $1[0]).upcase }
-          end
-
-        preffix_class_name.to_s + class_name + postfix_class_name.to_s
+      # Builds a class name from `name` with an optional prefix and suffix.
+      #
+      # `name` is split on underscores and the first letter of each part is capitalized. The result doesn't depend
+      # on whether ActiveSupport is loaded, and the name isn't singularized (`:line_items` gives `"LineItems"`).
+      #
+      # @param name [String, Symbol] the base name, such as `:line_item`
+      # @param prefix_class_name [String, nil] text to put before the converted name
+      # @param suffix_class_name [String, nil] text to put after the converted name
+      # @return [String] the class name, such as `"SchemaLineItem"`
+      # @example
+      #   get_class_name(:line_item, 'Schema', 'Class') # => "SchemaLineItemClass"
+      def get_class_name(name, prefix_class_name, suffix_class_name)
+        class_name = name.to_s.split('_').map { |part| part.sub(/\A./, &:upcase) }.join
+        "#{prefix_class_name}#{class_name}#{suffix_class_name}"
       end
 
-      # Purpose to create a class that is under a module with an actual class name
-      def create_class(base_module, name, base_class, preffix_class_name, postfix_class_name, &block)
-        class_name = get_class_name(name, preffix_class_name, postfix_class_name)
-        kls = base_class ? Class.new(base_class) : Class.new
+      # Creates a class and assigns it to a constant in `base_module`, which gives the class a name.
+      #
+      # If the constant already exists it is replaced, and Ruby prints an "already initialized constant"
+      # warning.
+      #
+      # @param base_module [Module] the module the class is defined in
+      # @param name [String, Symbol] the base name, converted with {get_class_name}
+      # @param base_class [Class, nil] the superclass, or `nil` for `Object`
+      # @param prefix_class_name [String, nil] text to put before the converted name
+      # @param suffix_class_name [String, nil] text to put after the converted name
+      # @yield evaluated in the new class with `class_eval`, to define its methods
+      # @return [Class] the new class
+      # @raise [NameError] if the resulting name isn't a valid constant name
+      def create_class(base_module, name, base_class, prefix_class_name, suffix_class_name, &block)
+        class_name = get_class_name(name, prefix_class_name, suffix_class_name)
+        kls = Class.new(base_class || Object)
         base_module.const_set(class_name, kls)
-        kls = base_module.const_get(class_name)
         kls.class_eval(&block) if block
         kls
       end

data/lib/inheritance-helper/methods.rb

@@ -1,21 +1,91 @@
 # frozen_string_literal: true
 
 module InheritanceHelper
-  # Collection of utility methods for rewriting class methods
+  # Class methods for redefining class methods on a subclass.
+  #
+  # Extend a class with this module. A class method on that class, or on any subclass, can then be replaced
+  # with one that returns a new value. The new method is defined on the receiving class's singleton class,
+  # so the parent class keeps its own method and value.
+  #
+  # @example Collect attributes across an inheritance chain
+  #   class Model
+  #     extend InheritanceHelper::Methods
+  #
+  #     def self.attributes
+  #       {}.freeze
+  #     end
+  #
+  #     def self.attribute(name, type)
+  #       add_value_to_class_method(:attributes, name => type)
+  #     end
+  #   end
+  #
+  #   class Person < Model
+  #     attribute :name, :string
+  #   end
+  #
+  #   Person.attributes # => {name: :string}
+  #   Model.attributes  # => {}
   module Methods
+    # Defines (or replaces) the class method `method` on `klass` so that it returns `value`.
+    #
+    # The new method keeps the visibility of the method it replaces, so a private class method stays private.
+    #
+    # @param klass [Module] the class or module to define the method on
+    # @param method [Symbol, String] name of the class method
+    # @param value [Object] the value the method returns. The same object is returned on every call, so
+    #   freeze it if callers shouldn't change it
+    # @return [Module] `klass`
     def self.redefine_class_method(klass, method, value)
-      class << klass; self; end.send(:define_method, method) { value }
+      singleton = klass.singleton_class
+      visibility = method_visibility(singleton, method)
+      singleton.send(:define_method, method) { value }
+      singleton.send(visibility, method)
       klass
     end
 
+    # @api private
+    # @param mod [Module] the module to look the method up in
+    # @param method [Symbol, String] name of the method
+    # @return [Symbol] `:private`, `:protected` or `:public` (also for a method that isn't defined yet)
+    def self.method_visibility(mod, method)
+      if mod.private_method_defined?(method)
+        :private
+      elsif mod.protected_method_defined?(method)
+        :protected
+      else
+        :public
+      end
+    end
+    private_class_method :method_visibility
+
+    # Defines (or replaces) the class method `method` on this class so that it returns `value`.
+    #
+    # @param method [Symbol, String] name of the class method
+    # @param value [Object] the value the method returns
+    # @return [Module] this class
+    # @see InheritanceHelper::Methods.redefine_class_method
     def redefine_class_method(method, value)
       ::InheritanceHelper::Methods.redefine_class_method(self, method, value)
     end
 
-    # useful for adding data to hashes.
-    # when working with arrays it keeps a flat data set
+    # Redefines the class method `method` to return its current value with `value` added.
+    #
+    # - A Hash is merged with `value`, which must be a Hash.
+    # - Anything else (an Array, a Set) is combined with `Array(value)`, so an array of values adds each one
+    #   and the result stays flat. Use {#append_value_to_class_method} to add an array as a single element.
+    #
+    # The current value isn't changed. If it is frozen, the new value is frozen too.
+    #
+    # @param method [Symbol, String] name of a class method that returns a Hash, Array or Set
+    # @param value [Object] the value or values to add
+    # @return [Module] this class
+    # @raise [TypeError] if the class method returns `nil`
+    # @example
+    #   add_value_to_class_method(:attributes, name: :string)  # {} => {name: :string}
+    #   add_value_to_class_method(:fields, [:a, :b])           # [] => [:a, :b]
     def add_value_to_class_method(method, value)
-      old_value = send(method)
+      old_value = current_class_method_value(method)
 
       new_value =
         case old_value
@@ -28,11 +98,36 @@ module InheritanceHelper
       redefine_class_method(method, old_value.frozen? ? new_value.freeze : new_value)
     end
 
-    # useful for working with arrays and maintain a list of values
+    # Redefines the class method `method` to return a copy of its current value with `value` appended as a
+    # single element (using `<<`).
+    #
+    # The current value isn't changed. If it is frozen, the new value is frozen too.
+    #
+    # @param method [Symbol, String] name of a class method that returns an Array (or anything that responds
+    #   to `dup` and `<<`)
+    # @param value [Object] the element to append
+    # @return [Module] this class
+    # @raise [TypeError] if the class method returns `nil`
+    # @example
+    #   append_value_to_class_method(:callbacks, [:save, :log])  # [] => [[:save, :log]]
     def append_value_to_class_method(method, value)
-      old_value = send(method)
+      old_value = current_class_method_value(method)
       new_value = old_value.dup << value
       redefine_class_method(method, old_value.frozen? ? new_value.freeze : new_value)
     end
+
+    private
+
+    # @api private
+    # @param method [Symbol, String] name of the class method
+    # @return [Object] the method's current value
+    # @raise [TypeError] if the method returns `nil`
+    def current_class_method_value(method)
+      value = send(method)
+      return value unless value.nil?
+
+      raise TypeError, "#{self}.#{method} returned nil; define it to return a starting value such as {}.freeze " \
+                       'or [].freeze'
+    end
   end
 end

data/lib/inheritance-helper/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module InheritanceHelper
+  # Gem version, bumped by release-please
+  VERSION = '0.3.0'
+end

data/lib/inheritance-helper.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
-# A set of utility classes for making inheritance work with class level variables
+require_relative 'inheritance-helper/version'
+
+# Helpers for class-level values that subclasses can extend without changing their parent classes.
 module InheritanceHelper
   autoload :Methods, 'inheritance-helper/methods'
 
+  # Helpers for creating classes at runtime.
   module ClassBuilder
     autoload :Utils, 'inheritance-helper/class_builder/utils'
   end

metadata

@@ -1,29 +1,40 @@
 --- !ruby/object:Gem::Specification
 name: inheritance-helper
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Doug Youch
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Redefines class methods
-email: dougyouch+github@gmail.com
+description: Redefine a class method on a subclass to return a new value, so hashes,
+  arrays and sets declared on a parent class can be added to by each subclass while
+  the parent keeps its own copy. Built for DSLs that collect attributes, options or
+  callbacks at the class level. Also includes a helper for creating named classes
+  inside a module.
+email: dougyouch@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
 - lib/inheritance-helper.rb
 - lib/inheritance-helper/class_builder/utils.rb
 - lib/inheritance-helper/methods.rb
+- lib/inheritance-helper/version.rb
 homepage: https://github.com/dougyouch/inheritance-helper
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/dougyouch/inheritance-helper
+  changelog_uri: https://github.com/dougyouch/inheritance-helper/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dougyouch/inheritance-helper/issues
+  documentation_uri: https://rubydoc.info/gems/inheritance-helper
 rdoc_options: []
 require_paths:
 - lib
@@ -31,15 +42,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Inheritance Helpers
+summary: Class-level settings that subclasses can extend without changing their parents
 test_files: []