cattri 0.1.0 → 0.1.1

data/lib/cattri/instance_attributes.rb

@@ -1,64 +1,61 @@
 # 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).
+  # Mixin that provides support for defining instance-level attributes.
   #
-  # Example:
+  # This module is included into a class (via `include Cattri`) and exposes
+  # a DSL similar to `attr_accessor`, with enhancements:
   #
-  #   class MyObject
-  #     extend Cattri::InstanceAttributes
+  # - Lazy or static default values
+  # - Coercion via custom setter blocks
+  # - Visibility control (`:public`, `:protected`, `:private`)
+  # - Read-only or write-only support
   #
-  #     iattr :name, default: "anonymous"
-  #     iattr_writer :age, default: 0 do |v|
-  #       Integer(v)
-  #     end
-  #   end
-  #
-  #   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 an instance-level attribute with optional default and coercion.
       #
       # @param name [Symbol, String] the name of the attribute
       # @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
-      # @return [void]
+      # @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)
       def instance_attribute(name, **options, &block)
-        name, definition = define_attribute(name, options, block, DEFAULT_OPTIONS)
-        __cattri_instance_attributes[name] = definition
+        options[:access] ||= __cattri_visibility
+        attribute = Cattri::Attribute.new(name, :instance, options, block)
+
+        raise Cattri::AttributeDefinedError, attribute if instance_attribute_defined?(attribute.name)
 
-        define_reader(name, definition) if options.fetch(:reader, true)
-        define_writer(name, definition) if options.fetch(:writer, true)
+        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 a read-only instance-level attribute.
       #
+      # Equivalent to `instance_attribute(..., writer: false)`
+      #
       # @param name [Symbol, String]
       # @param options [Hash]
       # @return [void]
@@ -68,26 +65,24 @@ module Cattri
 
       # Defines a write-only instance-level attribute.
       #
+      # Equivalent to `instance_attribute(..., reader: false)`
+      #
       # @param name [Symbol, String]
       # @param options [Hash]
-      # @yield [value] coercion logic
+      # @yieldparam value [Object] optional coercion logic
       # @return [void]
       def instance_attribute_writer(name, **options, &block)
         instance_attribute(name, reader: false, **options, &block)
       end
 
-      def __cattri_instance_attributes
-        @__cattri_instance_attributes ||= {}
-      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 +90,61 @@ 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 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.
+      # Internal registry of instance attributes defined on the class.
       #
-      # @param name [Symbol] attribute name
-      # @param definition [Hash] full attribute definition
-      def define_reader(name, definition)
-        ivar = definition[:ivar]
-
-        define_method(name) do
-          return instance_variable_get(ivar) if instance_variable_defined?(ivar)
-
-          value = definition[:default].call
-          instance_variable_set(ivar, value)
-        end
+      # @return [Hash{Symbol => Cattri::Attribute}]
+      def __cattri_instance_attributes
+        @__cattri_instance_attributes ||= {}
       end
 
-      # Defines the writer method for an instance attribute.
+      # Returns the context used to define methods for this 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
+      # Used internally to encapsulate method definition and visibility rules.
+      #
+      # @return [Cattri::Context]
+      # :nocov:
+      def context
+        @context ||= Context.new(self)
       end
+      # :nocov:
     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])
-    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.1"
 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cattri
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Nathan Lucas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-19 00:00:00.000000000 Z
+date: 2025-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -102,9 +102,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".idea/workspace.xml"
 - ".rspec"
-- ".rspec_status"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -113,12 +111,15 @@ files:
 - Rakefile
 - cattri.gemspec
 - lib/cattri.rb
+- lib/cattri/attribute.rb
+- lib/cattri/attribute_definer.rb
 - lib/cattri/class_attributes.rb
+- lib/cattri/context.rb
 - lib/cattri/error.rb
-- lib/cattri/helpers.rb
 - lib/cattri/instance_attributes.rb
 - lib/cattri/introspection.rb
 - lib/cattri/version.rb
+- lib/cattri/visibility.rb
 - sig/cattri.rbs
 homepage: https://github.com/bnlucas/cattri
 licenses: