cattri 0.1.0 → 0.1.2

data/lib/cattri/error.rb

@@ -1,5 +1,105 @@
 # frozen_string_literal: true
 
 module Cattri
+  # Base error class for all exceptions raised by Cattri.
+  #
+  # All Cattri-specific errors inherit from this class.
+  #
+  # @example
+  #   rescue Cattri::Error => e
+  #     puts "Something went wrong with Cattri: #{e.message}"
   class Error < StandardError; end
+
+  # Parent class for all attribute-related errors in Cattri.
+  #
+  # This includes definition conflicts, setter failures, or configuration issues.
+  #
+  # @example
+  #   rescue Cattri::AttributeError => e
+  #     puts "Attribute error: #{e.message}"
+  class AttributeError < Cattri::Error; end
+
+  # Raised when a class or instance attribute is defined more than once.
+  #
+  # This helps detect naming collisions during DSL usage.
+  #
+  # @example
+  #   raise Cattri::AttributeDefinedError.new(attribute)
+  #
+  # @example
+  #   rescue Cattri::AttributeDefinedError => e
+  #     puts e.message
+  class AttributeDefinedError < Cattri::AttributeError
+    # @param type [Symbol, String] either :class or :instance
+    # @param name [Symbol, String] the name of the missing attribute
+    def initialize(type, name)
+      super("#{type.capitalize} attribute :#{name} has already been defined")
+    end
+  end
+
+  # Raised when attempting to access or modify an attribute that has not been defined.
+  #
+  # This applies to both class-level and instance-level attributes.
+  # It is typically raised when calling `.class_attribute_setter` or `.instance_attribute_setter`
+  # on a name that does not exist or lacks the expected method (e.g., writer).
+  #
+  # @example
+  #   raise Cattri::AttributeNotDefinedError.new(:class, :foo)
+  #   # => Class attribute :foo has not been defined
+  #
+  # @example
+  #   rescue Cattri::AttributeNotDefinedError => e
+  #     puts e.message
+  class AttributeNotDefinedError < Cattri::AttributeError
+    # @param type [Symbol, String] either :class or :instance
+    # @param name [Symbol, String] the name of the missing attribute
+    def initialize(type, name)
+      super("#{type.capitalize} attribute :#{name} has not been defined")
+    end
+  end
+
+  # Raised when a method definition (reader, writer, or callable) fails.
+  #
+  # This wraps the original error that occurred during `define_method` or visibility handling.
+  #
+  # @example
+  #   raise Cattri::AttributeDefinitionError.new(target, attribute, error)
+  #
+  # @example
+  #   rescue Cattri::AttributeDefinitionError => e
+  #     puts e.message
+  class AttributeDefinitionError < Cattri::AttributeError
+    # @param target [Module] the class or module receiving the method
+    # @param attribute [Cattri::Attribute] the attribute being defined
+    # @param error [StandardError] the original raised exception
+    def initialize(target, attribute, error)
+      super("Failed to define method :#{attribute.name} on #{target}. Error: #{error.message}")
+      set_backtrace(error.backtrace)
+    end
+  end
+
+  # Raised when an unsupported attribute type is passed to Cattri.
+  #
+  # Valid types are typically `:class` and `:instance`. Any other value is invalid.
+  #
+  # @example
+  #   raise Cattri::UnsupportedTypeError.new(:foo)
+  #   # => Attribute type :foo is not supported
+  class UnsupportedTypeError < Cattri::AttributeError
+    # @param type [Symbol] the invalid type that triggered the error
+    def initialize(type)
+      super("Attribute type :#{type} is not supported")
+    end
+  end
+
+  # Raised when a block is provided when defining a group of attributes `cattr :attr_a, :attr_b do ... end`
+  #
+  # @example
+  #   raise Cattri::AmbiguousBlockError
+  #   # => Cannot define multiple attributes with a block
+  class AmbiguousBlockError < Cattri::AttributeError
+    def initialize
+      super("Cannot define multiple attributes with a block")
+    end
+  end
 end

data/lib/cattri/instance_attributes.rb

@@ -1,93 +1,132 @@
 # frozen_string_literal: true
 
+require_relative "attribute_definer"
+
 module Cattri
-  # Provides a DSL for defining instance-level attributes with support for:
-  #
-  # - Default values (static or callable)
-  # - Optional reader/writer method generation
-  # - Custom coercion logic for writers
-  # - Full attribute metadata access and reset capabilities
-  #
-  # This module is designed for mixin into classes or modules that want to offer
-  # configurable instance attributes (e.g., plugin systems, DTOs, DSLs).
-  #
-  # Example:
+  # Mixin that provides support for defining instance-level attributes.
   #
-  #   class MyObject
-  #     extend Cattri::InstanceAttributes
+  # This module is included into a class (via `include Cattri`) and exposes
+  # a DSL similar to `attr_accessor`, with enhancements:
   #
-  #     iattr :name, default: "anonymous"
-  #     iattr_writer :age, default: 0 do |v|
-  #       Integer(v)
-  #     end
-  #   end
+  # - Lazy or static default values
+  # - Coercion via custom setter blocks
+  # - Visibility control (`:public`, `:protected`, `:private`)
+  # - Read-only or write-only support
   #
-  #   obj = MyObject.new
-  #   obj.name # => "anonymous"
-  #   obj.age = "42"
-  #   obj.instance_variable_get(:@age) # => 42
+  # Each defined attribute is stored as metadata and linked to a reader and/or writer.
+  # Values are accessed and stored via standard instance variables.
   module InstanceAttributes
-    include Cattri::Helpers
-
+    # Hook called when this module is included into a class.
+    #
+    # @param base [Class]
+    # @return [void]
     def self.included(base)
       base.extend(ClassMethods)
     end
 
-    # Class-level methods for defining instance attributes
+    # Defines instance-level attribute DSL methods.
     module ClassMethods
-      include Cattri::Helpers
-
-      # Default options for all instance attributes
-      DEFAULT_OPTIONS = { default: nil, reader: true, writer: true }.freeze
-
-      # Defines a new instance-level attribute with optional default and coercion.
+      # Defines one or more instance-level attributes with optional default and coercion.
       #
-      # @param name [Symbol, String] the name of the attribute
+      # 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 defaults
+      #   iattr :foo, :bar, default: []
+      #
+      # @example Define a single attribute with coercion
+      #   iattr :level do |val|
+      #     Integer(val)
+      #   end
+      #
+      # @param names [Array<Symbol | String>] the names of the attributes to define
       # @param options [Hash] additional options like `:default`, `:reader`, `:writer`
-      # @option options [Object, Proc] :default the default value or proc returning the value
+      # @option options [Object, Proc] :default the default value or lambda
       # @option options [Boolean] :reader whether to define a reader method (default: true)
       # @option options [Boolean] :writer whether to define a writer method (default: true)
-      # @yield [value] optional coercion logic for the writer
+      # @option options [Symbol] :access method visibility (:public, :protected, :private)
+      # @yieldparam value [Object] optional custom coercion logic for the setter
+      # @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 instance_attribute(name, **options, &block)
-        name, definition = define_attribute(name, options, block, DEFAULT_OPTIONS)
-        __cattri_instance_attributes[name] = definition
+      def instance_attribute(*names, **options, &block)
+        raise Cattri::AmbiguousBlockError if names.size > 1 && block_given?
 
-        define_reader(name, definition) if options.fetch(:reader, true)
-        define_writer(name, definition) if options.fetch(:writer, true)
+        names.each { |name| define_instance_attribute(name, options, block) }
       end
 
       # Defines a read-only instance-level attribute.
       #
-      # @param name [Symbol, String]
-      # @param options [Hash]
+      # Equivalent to `instance_attribute(..., writer: false)`
+      #
+      # @param names [Array<Symbol | String>] the names of the attributes to define
+      # @param options [Hash] additional options like `:default`, `:reader`, `:writer`
+      # @option options [Object, Proc] :default the default value or lambda
+      # @option options [Boolean] :reader whether to define a reader method (default: true)
+      # @option options [Symbol] :access method visibility (:public, :protected, :private)
+      # @yieldparam value [Object] optional custom coercion logic for the setter
+      # @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 instance_attribute_reader(name, **options)
-        instance_attribute(name, writer: false, **options)
+      def instance_attribute_reader(*names, **options)
+        instance_attribute(*names, **options, writer: false)
       end
 
       # Defines a write-only instance-level attribute.
       #
-      # @param name [Symbol, String]
-      # @param options [Hash]
-      # @yield [value] coercion logic
+      # Equivalent to `instance_attribute(..., reader: false)`
+      #
+      # @param names [Array<Symbol | String>] the names of the attributes to define
+      # @param options [Hash] additional options like `:default`, `:reader`, `:writer`
+      # @option options [Object, Proc] :default the default value or lambda
+      # @option options [Boolean] :writer whether to define a writer method (default: true)
+      # @option options [Symbol] :access method visibility (:public, :protected, :private)
+      # @yieldparam value [Object] optional custom coercion logic for the setter
+      # @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 instance_attribute_writer(name, **options, &block)
-        instance_attribute(name, reader: false, **options, &block)
+      def instance_attribute_writer(*names, **options, &block)
+        instance_attribute(*names, **options.merge(reader: false), &block)
       end
 
-      def __cattri_instance_attributes
-        @__cattri_instance_attributes ||= {}
+      # Updates the setter behavior of an existing instance-level attribute.
+      #
+      # This allows coercion logic to be defined or overridden after the attribute
+      # has been declared using `iattr`, as long as the writer method exists.
+      #
+      # @example Add coercion to an existing attribute
+      #   iattr :format
+      #   iattr_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 instance_attribute_setter(name, &block)
+        attribute = __cattri_instance_attributes[name.to_sym]
+
+        raise Cattri::AttributeNotDefinedError.new(:instance, name) if attribute.nil?
+        raise Cattri::AttributeError, "Cannot define setter for readonly attribute :#{name}" unless attribute[:writer]
+
+        attribute.instance_variable_set(:@setter, attribute.send(:normalize_setter, block))
+        Cattri::AttributeDefiner.define_writer!(attribute, context)
       end
 
-      # Returns all defined instance-level attribute names.
+      # Returns a list of defined instance-level attribute names.
       #
       # @return [Array<Symbol>]
       def instance_attributes
         __cattri_instance_attributes.keys
       end
 
-      # Checks whether an instance attribute is defined.
+      # Checks if an instance-level attribute has been defined.
       #
       # @param name [Symbol, String]
       # @return [Boolean]
@@ -95,104 +134,93 @@ module Cattri
         __cattri_instance_attributes.key?(name.to_sym)
       end
 
-      # Fetches the full definition hash for a specific attribute.
+      # Returns the full attribute definition for a given name.
       #
       # @param name [Symbol, String]
-      # @return [Hash, nil]
+      # @return [Cattri::Attribute, nil]
       def instance_attribute_definition(name)
         __cattri_instance_attributes[name.to_sym]
       end
 
       # @!method iattr(name, **options, &block)
-      #   Alias for {.instance_attribute}
-      #   @see .instance_attribute
+      #   Alias for {#instance_attribute}
       alias iattr instance_attribute
 
       # @!method iattr_accessor(name, **options, &block)
-      #   Alias for {.instance_attribute}
-      #   @see .instance_attribute
+      #   Alias for {#instance_attribute}
       alias iattr_accessor instance_attribute
 
       # @!method iattr_reader(name, **options)
-      #   Alias for {.instance_attribute_reader}
-      #   @see .instance_attribute_reader
+      #   Alias for {#instance_attribute_reader}
       alias iattr_reader instance_attribute_reader
 
       # @!method iattr_writer(name, **options, &block)
-      #   Alias for {.instance_attribute_writer}
-      #   @see .instance_attribute_writer
+      #   Alias for {#instance_attribute_writer}
       alias iattr_writer instance_attribute_writer
 
+      # @!method iattr_setter(name, &block)
+      #   Alias for {#instance_attribute_setter}
+      alias iattr_setter instance_attribute_setter
+
       # @!method iattrs
-      #   @return [Hash<Symbol, Hash>] all defined attributes
-      #   @see .instance_attributes
+      #   Alias for {#instance_attributes}
       alias iattrs instance_attributes
 
       # @!method iattr_defined?(name)
-      #   @return [Boolean]
-      #   @see .instance_attribute_defined?
+      #   Alias for {#instance_attribute_defined?}
       alias iattr_defined? instance_attribute_defined?
 
-      # @!method iattr_for(name)
-      #   @return [Hash, nil]
-      #   @see .instance_attribute_definition
+      # @!method iattr_definition(name)
+      #   Alias for {#instance_attribute_definition}
       alias iattr_definition instance_attribute_definition
 
       private
 
-      # Defines the reader method for an instance attribute.
+      # Defines a single instance-level attribute.
+      #
+      # This is the internal implementation used by {.instance_attribute} and its aliases.
+      # It creates a `Cattri::Attribute`, registers it, and defines the appropriate
+      # reader and/or writer methods on the class.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @param options [Hash] additional options for the attribute
+      # @param block [Proc, nil] optional setter coercion logic
       #
-      # @param name [Symbol] attribute name
-      # @param definition [Hash] full attribute definition
-      def define_reader(name, definition)
-        ivar = definition[:ivar]
+      # @raise [Cattri::AttributeDefinedError] if the attribute has already been defined
+      # @raise [Cattri::AttributeDefinitionError] if method definition fails
+      #
+      # @return [void]
+      def define_instance_attribute(name, options, block)
+        options[:access] ||= __cattri_visibility
+        attribute = Cattri::Attribute.new(name, :instance, options, block)
 
-        define_method(name) do
-          return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+        raise Cattri::AttributeDefinedError.new(:instance, name) if instance_attribute_defined?(attribute.name)
 
-          value = definition[:default].call
-          instance_variable_set(ivar, value)
+        begin
+          __cattri_instance_attributes[name.to_sym] = attribute
+          Cattri::AttributeDefiner.define_accessor(attribute, context)
+        rescue StandardError => e
+          raise Cattri::AttributeDefinitionError.new(self, attribute, e)
         end
       end
 
-      # Defines the writer method for an instance attribute.
+      # Internal registry of instance attributes defined on the class.
       #
-      # @param name [Symbol] attribute name
-      # @param definition [Hash] full attribute definition
-      def define_writer(name, definition)
-        define_method("#{name}=") do |value|
-          coerced_value = definition[:setter].call(value)
-          instance_variable_set(definition[:ivar], coerced_value)
-        end
+      # @return [Hash{Symbol => Cattri::Attribute}]
+      def __cattri_instance_attributes
+        @__cattri_instance_attributes ||= {}
       end
-    end
 
-    # Resets all defined attributes to their default values.
-    #
-    # @return [void]
-    def reset_instance_attributes!
-      reset_attributes!(self, self.class.__cattri_instance_attributes.values)
-    end
-
-    # Resets a specific attribute to its default value.
-    #
-    # @param name [Symbol, String]
-    # @return [void]
-    def reset_instance_attribute!(name)
-      definition = self.class.__cattri_instance_attributes[name]
-      return unless definition
-
-      reset_attributes!(self, [definition])
+      # Returns the context used to define methods for this class.
+      #
+      # Used internally to encapsulate method definition and visibility rules.
+      #
+      # @return [Cattri::Context]
+      # :nocov:
+      def context
+        @context ||= Context.new(self)
+      end
+      # :nocov:
     end
-
-    # @!method reset_iattrs!
-    #   @return [void]
-    #   @see .reset_instance_attributes!
-    alias reset_iattrs! reset_instance_attributes!
-
-    # @!method reset_iattr!(name)
-    #   @return [void]
-    #   @see .reset_instance_attribute!
-    alias reset_iattr! reset_instance_attribute!
   end
 end

data/lib/cattri/introspection.rb

@@ -39,7 +39,7 @@ module Cattri
 
         class_attributes.each_with_object({}) do |attribute, hash|
           hash[attribute] = send(attribute)
-        end
+        end.freeze
       end
 
       # @!method snapshot_cattrs

data/lib/cattri/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cattri
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/cattri/visibility.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Cattri
+  # Cattri::Visibility tracks the current method visibility context (`public`, `protected`, `private`)
+  # when defining methods dynamically. It mimics Ruby's native visibility behavior so that
+  # `cattr` and `iattr` definitions can automatically infer the intended access level
+  # based on the current context in the source file.
+  #
+  # This module is intended to be extended by classes that include or extend Cattri.
+  #
+  # @example
+  #   class MyClass
+  #     include Cattri
+  #
+  #     private
+  #     cattr :sensitive_data
+  #   end
+  #
+  #   # => :sensitive_data will be defined as a private method
+  module Visibility
+    # Returns the currently active visibility scope on the class or module.
+    #
+    # Defaults to `:public` unless changed explicitly via `public`, `protected`, or `private`.
+    #
+    # @return [Symbol] :public, :protected, or :private
+    def __cattri_visibility
+      @__cattri_visibility ||= :public
+    end
+
+    # Intercepts calls to `public` to update the visibility tracker.
+    #
+    # If no method names are passed, this sets the current visibility scope for future methods.
+    # Otherwise, delegates to Ruby’s native `Module#public`.
+    #
+    # @param args [Array<Symbol>] method names to make public, or empty to set context
+    # @return [void]
+    def public(*args)
+      @__cattri_visibility = :public if args.empty?
+      Module.instance_method(:public).bind(self).call(*args)
+    end
+
+    # Intercepts calls to `protected` to update the visibility tracker.
+    #
+    # If no method names are passed, this sets the current visibility scope for future methods.
+    # Otherwise, delegates to Ruby’s native `Module#protected`.
+    #
+    # @param args [Array<Symbol>] method names to make protected, or empty to set context
+    # @return [void]
+    def protected(*args)
+      @__cattri_visibility = :protected if args.empty?
+      Module.instance_method(:protected).bind(self).call(*args)
+    end
+
+    # Intercepts calls to `private` to update the visibility tracker.
+    #
+    # If no method names are passed, this sets the current visibility scope for future methods.
+    # Otherwise, delegates to Ruby’s native `Module#private`.
+    #
+    # @param args [Array<Symbol>] method names to make private, or empty to set context
+    # @return [void]
+    def private(*args)
+      @__cattri_visibility = :private if args.empty?
+      Module.instance_method(:private).bind(self).call(*args)
+    end
+  end
+end

data/lib/cattri.rb

@@ -1,36 +1,119 @@
 # frozen_string_literal: true
 
 require_relative "cattri/version"
+require_relative "cattri/visibility"
 require_relative "cattri/class_attributes"
 require_relative "cattri/instance_attributes"
 require_relative "cattri/introspection"
 
 # The primary entry point for the Cattri gem.
 #
-# When included, it adds support for both class-level and instance-level
-# attribute declarations using `cattr` and `iattr` style methods.
+# When included, it enables both class-level and instance-level attribute definitions
+# via `cattr` and `iattr`-style DSLs, providing a lightweight alternative to traditional
+# `attr_*` and `cattr_*` patterns.
 #
-# This module does **not** include introspection helpers by default —
-# use `include Cattri::Introspection` explicitly if needed.
+# The module includes:
+# - `Cattri::ClassAttributes` (for class-level configuration)
+# - `Cattri::InstanceAttributes` (for instance-level configuration)
+# - `Cattri::Visibility` (for default access control)
+#
+# It also installs a custom `.inherited` hook to ensure that subclassed classes
+# receive deep copies of attribute metadata and current values.
+#
+# Note: The `Cattri::Introspection` module must be included manually if needed.
 #
 # @example Using both class and instance attributes
-#   class MyConfig
+#   class Config
 #     include Cattri
 #
 #     cattr :enabled, default: true
 #     iattr :name, default: "anonymous"
 #   end
 #
-#   MyConfig.enabled # => true
-#   MyConfig.new.name # => "anonymous"
+#   Config.enabled          # => true
+#   Config.new.name         # => "anonymous"
 module Cattri
   # Hook triggered when `include Cattri` is called.
-  # Adds class and instance attribute support to the target.
+  #
+  # Installs core attribute DSLs and visibility settings into the host class.
+  # Also injects `.inherited` logic to propagate attribute metadata to subclasses.
   #
   # @param base [Class, Module] the receiving class or module
   # @return [void]
   def self.included(base)
+    base.extend(Cattri::Visibility)
     base.extend(Cattri::ClassAttributes)
     base.include(Cattri::InstanceAttributes)
+
+    base.singleton_class.define_method(:inherited) do |subclass|
+      super(subclass) if defined?(super)
+
+      %i[class instance].each do |type|
+        Cattri.send(:copy_attributes_to, self, subclass, type)
+      end
+    end
+  end
+
+  class << self
+    private
+
+    # Copies attribute definitions and backing values from one class to a subclass.
+    #
+    # This is invoked automatically via the `.inherited` hook to ensure
+    # subclass isolation and metadata integrity.
+    #
+    # @param origin [Class] the parent class
+    # @param subclass [Class] the child class inheriting the attributes
+    # @param type [Symbol] either `:class` or `:instance`
+    # @return [void]
+    # @raise [Cattri::AttributeError] if an ivar copy operation fails
+    def copy_attributes_to(origin, subclass, type)
+      ivar = :"@__cattri_#{type}_attributes"
+      attributes = origin.instance_variable_get(ivar) || {}
+
+      subclass_attributes = attributes.transform_values do |attribute|
+        copy_ivar_to(origin, subclass, attribute)
+        attribute.dup
+      end
+
+      subclass.instance_variable_set(ivar, subclass_attributes)
+    end
+
+    # Duplicates the current value of an attribute's backing ivar to the subclass.
+    #
+    # Falls back to raw assignment if duplication is not supported.
+    #
+    # @param origin [Class] the parent class
+    # @param subclass [Class] the receiving subclass
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    # @raise [Cattri::AttributeError] if the value cannot be safely duplicated
+    def copy_ivar_to(origin, subclass, attribute)
+      value = duplicate_value(origin, attribute)
+      subclass.instance_variable_set(attribute.ivar, value)
+    end
+
+    # Attempts to duplicate the value of an attribute's backing ivar.
+    #
+    # This method first tries to duplicate the value stored in the ivar.
+    # If duplication is not supported due to the object's nature (e.g., it is frozen or immutable),
+    # it will fall back to returning the original value.
+    #
+    # @param origin [Class] the parent class from which the ivar value is being retrieved
+    # @param attribute [Cattri::Attribute] the attribute for which the ivar value is being duplicated
+    # @return [Object] the duplicated value or the original value if duplication is not possible
+    # @raise [Cattri::AttributeError] if duplication fails due to unsupported object types
+    def duplicate_value(origin, attribute)
+      value = origin.instance_variable_get(attribute.ivar)
+
+      begin
+        value.dup
+      rescue TypeError, FrozenError
+        puts "HERE"
+        value
+      end
+    rescue StandardError => e
+      raise Cattri::AttributeError, "Failed to duplicate value for attribute #{attribute}. Error: #{e.message}"
+    end
   end
 end