cattri 0.1.3 → 0.2.0

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "simplecov_helper"
+require "cattri"
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: cattri
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Nathan Lucas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-23 00:00:00.000000000 Z
+date: 2025-05-01 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: debride
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: steep
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -102,25 +130,69 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/main.yml"
+- ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
+- bin/console
+- bin/setup
 - cattri.gemspec
 - lib/cattri.rb
 - lib/cattri/attribute.rb
-- lib/cattri/attribute_definer.rb
-- lib/cattri/class_attributes.rb
+- lib/cattri/attribute_compiler.rb
+- lib/cattri/attribute_options.rb
+- lib/cattri/attribute_registry.rb
 - lib/cattri/context.rb
+- lib/cattri/context_registry.rb
+- lib/cattri/deferred_attributes.rb
+- lib/cattri/dsl.rb
 - lib/cattri/error.rb
-- lib/cattri/instance_attributes.rb
+- lib/cattri/inheritance.rb
+- lib/cattri/initializer_patch.rb
+- lib/cattri/internal_store.rb
 - lib/cattri/introspection.rb
 - lib/cattri/version.rb
 - lib/cattri/visibility.rb
-- sig/cattri.rbs
+- sig/lib/cattri.rbs
+- sig/lib/cattri/attribute.rbs
+- sig/lib/cattri/attribute_compiler.rbs
+- sig/lib/cattri/attribute_options.rbs
+- sig/lib/cattri/attribute_registry.rbs
+- sig/lib/cattri/context.rbs
+- sig/lib/cattri/context_registry.rbs
+- sig/lib/cattri/deferred_attributes.rbs
+- sig/lib/cattri/dsl.rbs
+- sig/lib/cattri/error.rbs
+- sig/lib/cattri/inheritance.rbs
+- sig/lib/cattri/initializer_patch.rbs
+- sig/lib/cattri/internal_store.rbs
+- sig/lib/cattri/introspection.rbs
+- sig/lib/cattri/types.rbs
+- sig/lib/cattri/visibility.rbs
+- spec/cattri/attribute_compiler_spec.rb
+- spec/cattri/attribute_options_spec.rb
+- spec/cattri/attribute_registry_spec.rb
+- spec/cattri/attribute_spec.rb
+- spec/cattri/context_registry_spec.rb
+- spec/cattri/context_spec.rb
+- spec/cattri/deferred_attrributes_spec.rb
+- spec/cattri/dsl_spec.rb
+- spec/cattri/error_spec.rb
+- spec/cattri/inheritance_spec.rb
+- spec/cattri/initializer_patch_spec.rb
+- spec/cattri/internal_store_spec.rb
+- spec/cattri/introspection_spec.rb
+- spec/cattri/visibility_spec.rb
+- spec/cattri_spec.rb
+- spec/simplecov_helper.rb
+- spec/spec_helper.rb
 homepage: https://github.com/bnlucas/cattri
 licenses:
 - MIT
@@ -128,6 +200,7 @@ metadata:
   homepage_uri: https://github.com/bnlucas/cattri
   source_code_uri: https://github.com/bnlucas/cattri
   changelog_uri: https://github.com/bnlucas/cattri/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/cattri
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []

data/lib/cattri/attribute_definer.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-module Cattri
-  # Defines attribute accessors on a given target class using Cattri's Context.
-  #
-  # This class provides a set of utility methods to generate reader and writer
-  # methods dynamically, with support for default values, coercion, and memoization.
-  #
-  # All accessors are defined through the Cattri::Context abstraction to ensure
-  # consistent scoping, visibility, and method tracking.
-  class AttributeDefiner
-    class << self
-      # Defines a callable accessor for class-level attributes.
-      #
-      # The generated method:
-      # - Returns the memoized default value when called with no args or if readonly
-      # - Otherwise, calls the attribute’s setter and memoizes the result
-      #
-      # If the attribute is not readonly, a writer (`foo=`) is also defined.
-      #
-      # @param attribute [Cattri::Attribute]
-      # @param context [Cattri::Context]
-      # @return [void]
-      # @raise [Cattri::AttributeError] if the setter raises an error
-      def define_callable_accessor(attribute, context)
-        return unless attribute.class_level?
-
-        context.define_method(attribute) do |*args, **kwargs|
-          readonly = (args.empty? && kwargs.empty?) || attribute[:readonly]
-          return AttributeDefiner.send(:memoize_default_value, self, attribute) if readonly
-
-          value = attribute.invoke_setter(*args, **kwargs)
-          instance_variable_set(attribute.ivar, value)
-        end
-
-        define_writer(attribute, context) unless attribute[:readonly]
-      end
-
-      # Defines an instance-level reader for class-level attributes.
-      #
-      # This method delegates the instance-level call to the class method.
-      # It is used when `instance_reader: true` is specified.
-      #
-      # @param attribute [Cattri::Attribute]
-      # @param context [Cattri::Context]
-      # @return [void]
-      def define_instance_level_reader(attribute, context)
-        return unless attribute.class_level?
-
-        define_instance_level_method(attribute, context) do
-          self.class.__send__(attribute.name)
-        end
-
-        context.send(:apply_access, attribute.name, attribute)
-      end
-
-      # Defines an instance-level method for a class-level attribute.
-      #
-      # This is a shared utility for defining instance methods that delegate to class attributes,
-      # including both regular readers and predicate-style readers (`predicate: true`).
-      #
-      # Visibility is inherited from the attribute and applied to the defined method.
-      #
-      # @param attribute [Cattri::Attribute] the associated attribute metadata
-      # @param context [Cattri::Context] the context in which to define the method
-      # @param name [Symbol, nil] optional override for the method name (defaults to `attribute.name`)
-      # @yield the method body to define
-      # @return [void]
-      def define_instance_level_method(attribute, context, name: nil, &block)
-        name = (name || attribute.name).to_sym
-        context.target.define_method(name, &block)
-
-        context.send(:apply_access, name, attribute)
-      end
-
-      # Defines standard reader and writer methods for instance-level attributes.
-      #
-      # Skips definition if `reader: false` or `writer: false` is specified.
-      #
-      # @param attribute [Cattri::Attribute]
-      # @param context [Cattri::Context]
-      # @return [void]
-      def define_accessor(attribute, context)
-        define_reader(attribute, context) if attribute[:reader]
-        define_writer(attribute, context) if attribute[:writer]
-      end
-
-      # Defines a memoizing reader for the given attribute.
-      #
-      # This is used for both class and instance attributes, and ensures that
-      # the default value is computed only once and stored in the ivar.
-      #
-      # @param attribute [Cattri::Attribute]
-      # @param context [Cattri::Context]
-      # @return [void]
-      def define_reader(attribute, context)
-        context.define_method(attribute) do
-          AttributeDefiner.send(:memoize_default_value, self, attribute)
-        end
-      end
-
-      # Defines a writer method (`foo=`) that sets and coerces a value via the attribute setter.
-      #
-      # @param attribute [Cattri::Attribute]
-      # @param context [Cattri::Context]
-      # @return [void]
-      def define_writer(attribute, context)
-        context.define_method(attribute, name: :"#{attribute.name}=") do |value|
-          coerced_value = attribute.setter.call(value)
-          instance_variable_set(attribute.ivar, coerced_value)
-        end
-      end
-
-      # Defines, or redefines, a writer method (`foo=`) that sets and coerces a value via the attribute setter.
-      #
-      # @param attribute [Cattri::Attribute]
-      # @param context [Cattri::Context]
-      # @return [void]
-      def define_writer!(attribute, context)
-        context.define_method!(attribute, name: :"#{attribute.name}=") do |value|
-          coerced_value = attribute.setter.call(value)
-          instance_variable_set(attribute.ivar, coerced_value)
-        end
-      end
-
-      private
-
-      # Returns the memoized value for an attribute or computes it from the default.
-      #
-      # This helper ensures lazy initialization while guarding against errors in the default proc.
-      #
-      # @param receiver [Object]
-      # @param attribute [Cattri::Attribute]
-      # @return [Object]
-      # @raise [Cattri::AttributeError] if the default block raises an error
-      def memoize_default_value(receiver, attribute)
-        return receiver.instance_variable_get(attribute.ivar) if receiver.instance_variable_defined?(attribute.ivar)
-
-        receiver.instance_variable_set(attribute.ivar, attribute.invoke_default)
-      end
-    end
-  end
-end

data/lib/cattri/class_attributes.rb

@@ -1,277 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "attribute"
-require_relative "context"
-require_relative "attribute_definer"
-require_relative "visibility"
-
-module Cattri
-  # Mixin that provides support for defining class-level attributes.
-  #
-  # This module is intended to be extended onto a class and provides a DSL
-  # for defining configuration-style attributes at the class level using `cattr`.
-  #
-  # Features:
-  # - Default values (static, frozen, or callable)
-  # - Optional coercion via setter blocks
-  # - Optional instance-level readers
-  # - Visibility enforcement (`:public`, `:protected`, `:private`)
-  #
-  # Class attributes are stored internally as `Cattri::Attribute` instances and
-  # values are memoized using class-level instance variables.
-  module ClassAttributes
-    # Defines one or more class-level attributes with optional default, coercion, and reader access.
-    #
-    # This method supports defining multiple attributes at once, provided they share the same options.
-    # If a block is given, only one attribute may be defined to avoid ambiguity.
-    #
-    # @example Define multiple attributes with shared options
-    #   class_attribute :foo, :bar, default: 42
-    #
-    # @example Define a single attribute with a coercion block
-    #   class_attribute :path do |val|
-    #     Pathname(val)
-    #   end
-    #
-    # @param names [Array<Symbol | String>] the names of the attributes to define
-    # @param options [Hash] additional attribute options
-    # @option options [Object, Proc] :default the default value or lambda
-    # @option options [Boolean] :readonly whether the attribute is read-only
-    # @option options [Boolean] :instance_reader whether to define an instance-level reader (default: true)
-    # @option options [Symbol] :access visibility level (:public, :protected, :private)
-    # @option options [Boolean] :predicate whether to define a predicate-style alias method
-    #   (e.g., `foo?`) for the attribute
-    # @yieldparam value [Object] an optional custom setter block
-    # @raise [Cattri::AttributeError] or its subclasses, including `Cattri::AttributeDefinedError` or
-    #   `Cattri::AttributeDefinitionError` if defining the attribute fails (e.g., if the attribute is
-    #    already defined or an error occurs while defining methods)
-    # @return [void]
-    def class_attribute(*names, **options, &block)
-      raise Cattri::AmbiguousBlockError if names.size > 1 && block_given?
-
-      names.each do |name|
-        if name.end_with?("?")
-          raise Cattri::AttributeError,
-                "Attribute names ending in '?' are not allowed. Use `predicate: true` or `cattr_alias` instead."
-
-        end
-
-        define_class_attribute(name, options, block)
-      end
-    end
-
-    # Defines a read-only class attribute.
-    #
-    # Equivalent to calling `class_attribute(name, readonly: true, ...)`
-    #
-    # @param names [Array<Symbol | String>] the names of the attributes to define
-    # @param options [Hash] additional attribute options
-    # @option options [Object, Proc] :default the default value or lambda
-    # @option options [Boolean] :readonly whether the attribute is read-only
-    # @option options [Boolean] :instance_reader whether to define an instance-level reader (default: true)
-    # @option options [Symbol] :access visibility level (:public, :protected, :private)
-    # @option options [Boolean] :predicate whether to define a predicate-style alias method
-    #   (e.g., `foo?`) for the attribute
-    # @raise [Cattri::AttributeError] or its subclasses, including `Cattri::AttributeDefinedError` or
-    #   `Cattri::AttributeDefinitionError` if defining the attribute fails (e.g., if the attribute is
-    #    already defined or an error occurs while defining methods)
-    # @return [void]
-    def class_attribute_reader(*names, **options)
-      class_attribute(*names, **options, readonly: true)
-    end
-
-    # Updates the setter behavior of an existing class-level attribute.
-    #
-    # This allows coercion logic to be defined or overridden after the attribute
-    # has been declared using `cattr`, as long as the writer method exists.
-    #
-    # @example Add coercion to an existing attribute
-    #   cattr :format
-    #   cattr_setter :format do |val|
-    #     val.to_s.downcase.to_sym
-    #   end
-    #
-    # @param name [Symbol, String] the name of the attribute
-    # @yieldparam value [Object] the value passed to the setter
-    # @yieldreturn [Object] the coerced value to be assigned
-    # @raise [Cattri::AttributeNotDefinedError] if the attribute is not defined or the writer method does not exist
-    # @raise [Cattri::AttributeDefinitionError] if method redefinition fails
-    # @return [void]
-    def class_attribute_setter(name, &block)
-      name = name.to_sym
-      attribute = __cattri_class_attributes[name]
-      puts "<<< #{attribute} = #{name}>"
-
-      if attribute.nil? || !context.method_defined?(:"#{name}=")
-        raise Cattri::AttributeNotDefinedError.new(:class, name)
-      end
-
-      attribute.instance_variable_set(:@setter, attribute.send(:normalize_setter, block))
-      Cattri::AttributeDefiner.define_writer!(attribute, context)
-    end
-
-    # Defines an alias method for an existing class-level attribute.
-    #
-    # This does **not** register a new attribute; it simply defines a method
-    # (e.g., a predicate-style alias like `foo?`) that delegates to an existing one.
-    #
-    # The alias method inherits the visibility of the original attribute.
-    #
-    # @param alias_name [Symbol, String] the new method name (e.g., `:foo?`)
-    # @param original [Symbol, String] the name of the existing attribute to delegate to (e.g., `:foo`)
-    # @raise [Cattri::AttributeNotDefinedError] if the original attribute is not defined
-    # @return [void]
-    def class_attribute_alias(alias_name, original)
-      attribute = __cattri_class_attributes[original.to_sym]
-      raise Cattri::AttributeNotDefinedError.new(:class, original) if attribute.nil?
-
-      context.define_method(attribute, name: alias_name) { public_send(original) }
-    end
-
-    # Returns a list of defined class attribute names.
-    #
-    # @return [Array<Symbol>]
-    def class_attributes
-      ([self] + ancestors + singleton_class.included_modules)
-        .uniq
-        .select { |mod| mod.respond_to?(:__cattri_class_attributes, true) }
-        .flat_map { |mod| mod.send(:__cattri_class_attributes).keys }
-        .uniq
-    end
-
-    # Checks whether a class attribute has been defined.
-    #
-    # @param name [Symbol]
-    # @return [Boolean]
-    def class_attribute_defined?(name)
-      __cattri_class_attributes.key?(name.to_sym)
-    end
-
-    # Returns the full attribute definition object.
-    #
-    # @param name [Symbol]
-    # @return [Cattri::Attribute, nil]
-    def class_attribute_definition(name)
-      __cattri_class_attributes[name.to_sym]
-    end
-
-    # @!method cattr(name, **options, &block)
-    #   Alias for {.class_attribute}
-    #   @see #class_attribute
-    alias cattr class_attribute
-
-    # @!method cattr_accessor(name, **options, &block)
-    #   Alias for {.class_attribute}
-    #   @see #class_attribute
-    alias cattr_accessor class_attribute
-
-    # @!method cattr_reader(name, **options)
-    #   Alias for {.class_attribute_reader}
-    #   @see #class_attribute_reader
-    alias cattr_reader class_attribute_reader
-
-    # @!method cattr_setter(name, **options)
-    #   Alias for {.class_attribute_setter}
-    #   @see #class_attribute_setter
-    alias cattr_setter class_attribute_setter
-
-    # @!method cattr_alias(name, **options)
-    #   Alias for {.class_attribute_alias}
-    #   @see #class_attribute_alias
-    alias cattr_alias class_attribute_alias
-
-    # @!method cattrs
-    #   Alias for {.class_attributes}
-    #   @return [Array<Symbol>]
-    alias cattrs class_attributes
-
-    # @!method cattr_defined?(name)
-    #   Alias for {.class_attribute_defined?}
-    #   @param name [Symbol]
-    #   @return [Boolean]
-    alias cattr_defined? class_attribute_defined?
-
-    # @!method cattr_definition(name)
-    #   Alias for {.class_attribute_definition}
-    #   @param name [Symbol]
-    #   @return [Cattri::Attribute, nil]
-    alias cattr_definition class_attribute_definition
-
-    private
-
-    # Defines a single class-level attribute.
-    #
-    # This is the internal implementation used by {.class_attribute} and its aliases.
-    # It constructs a `Cattri::Attribute`, registers it, and defines the necessary
-    # class and instance methods.
-    #
-    # @param name [Symbol] the name of the attribute to define
-    # @param options [Hash] additional attribute options (e.g., :default, :readonly)
-    # @param block [Proc, nil] an optional setter block for coercion
-    #
-    # @raise [Cattri::AttributeDefinedError] if the attribute has already been defined
-    # @raise [Cattri::AttributeDefinitionError] if method definition fails
-    #
-    # @return [void]
-    def define_class_attribute(name, options, block) # rubocop:disable Metrics/AbcSize
-      options[:access] ||= __cattri_visibility
-      attribute = Cattri::Attribute.new(name, :class, options, block)
-
-      raise Cattri::AttributeDefinedError.new(:class, name) if class_attribute_defined?(attribute.name)
-
-      begin
-        __cattri_class_attributes[name] = attribute
-
-        Cattri::AttributeDefiner.define_callable_accessor(attribute, context)
-        Cattri::AttributeDefiner.define_instance_level_reader(attribute, context) if attribute[:instance_reader]
-      rescue StandardError => e
-        raise Cattri::AttributeDefinitionError.new(self, attribute, e)
-      end
-
-      define_predicate_methods(attribute) if attribute[:predicate]
-    end
-
-    # Defines predicate-style (`:name?`) methods for a class-level attribute.
-    #
-    # If `attribute[:predicate]` is true, this defines a method named `:name?` that returns
-    # a boolean based on the truthiness of the attribute's value (`!!value`).
-    #
-    # If `attribute[:instance_reader]` is also true, an instance-level predicate method
-    # is defined that delegates to the class-level value.
-    #
-    # Visibility is inherited from the original attribute.
-    #
-    # @param attribute [Cattri::Attribute] the attribute for which to define predicate methods
-    # @return [void]
-    def define_predicate_methods(attribute)
-      return unless attribute[:predicate]
-
-      predicate_name = :"#{attribute.name}?"
-
-      # rubocop:disable Style/DoubleNegation
-      context.define_method(attribute, name: predicate_name) { !!send(attribute.name) }
-      return unless attribute[:instance_reader]
-
-      Cattri::AttributeDefiner.define_instance_level_method(attribute, context, name: predicate_name) do
-        !!self.class.__send__(attribute.name)
-      end
-      # rubocop:enable Style/DoubleNegation
-    end
-
-    # Internal registry of defined class-level attributes.
-    #
-    # @return [Hash{Symbol => Cattri::Attribute}]
-    def __cattri_class_attributes
-      @__cattri_class_attributes ||= {}
-    end
-
-    # Context object used to define accessors with scoped visibility.
-    #
-    # @return [Cattri::Context]
-    # :nocov:
-    def context
-      @context ||= Context.new(self)
-    end
-    # :nocov:
-  end
-end