cattri 0.1.0 → 0.1.1

data/lib/cattri/class_attributes.rb

@@ -1,68 +1,56 @@
 # frozen_string_literal: true
 
-require_relative "error"
-require_relative "helpers"
+require_relative "attribute"
+require_relative "context"
+require_relative "attribute_definer"
+require_relative "visibility"
 
 module Cattri
-  # Provides a DSL for defining class-level attributes with support for:
+  # Mixin that provides support for defining class-level attributes.
   #
-  # - Static or dynamic default values
+  # 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
-  # - Read-only attribute enforcement
-  # - Inheritance-safe duplication
-  # - Attribute locking to prevent mutation in subclasses
-  #
-  # This module is designed for advanced metaprogramming needs such as DSL builders,
-  # configuration objects, and plugin systems that require reusable and introspectable
-  # class-level state.
-  #
-  # @example
-  #   class MyClass
-  #     extend Cattri::ClassAttributes
-  #
-  #     cattr :format, default: :json
-  #     cattr_reader :version, default: "1.0.0"
-  #     cattr :enabled, default: true do |value|
-  #       !!value
-  #     end
-  #   end
+  # - Visibility enforcement (`:public`, `:protected`, `:private`)
   #
-  #   MyClass.format        # => :json
-  #   MyClass.format :xml
-  #   MyClass.format        # => :xml
-  #   MyClass.version       # => "1.0.0"
-  #
-  #   instance = MyClass.new
-  #   instance.format       # => :xml
+  # Class attributes are stored internally as `Cattri::Attribute` instances and
+  # values are memoized using class-level instance variables.
   module ClassAttributes
-    include Cattri::Helpers
-
-    # Default options applied to all class-level attributes.
-    DEFAULT_OPTIONS = { default: nil, readonly: false }.freeze
-
     # Defines a class-level attribute with optional default, coercion, and reader access.
     #
     # @param name [Symbol] the attribute name
     # @param options [Hash] additional attribute options
-    # @option options [Object, Proc] :default the default value or callable
+    # @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
-    # @yield [*args] Optional setter block for custom coercion
-    # @raise [Cattri::Error] if attribute is already defined
-    # @return [void]
+    # @option options [Boolean] :instance_reader whether to define an instance-level reader (default: true)
+    # @option options [Symbol] :access visibility level (:public, :protected, :private)
+    # @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)
     def class_attribute(name, **options, &block)
-      define_inheritance unless respond_to?(:__cattri_class_attributes)
+      options[:access] ||= __cattri_visibility
+      attribute = Cattri::Attribute.new(name, :class, options, block)
+
+      raise Cattri::AttributeDefinedError, attribute if class_attribute_defined?(attribute.name)
 
-      name, definition = define_attribute(name, options, block, DEFAULT_OPTIONS)
-      raise Cattri::Error, "Class attribute `#{name}` already defined" if class_attribute_defined?(name)
+      begin
+        __cattri_class_attributes[name] = attribute
 
-      __cattri_class_attributes[name] = definition
-      define_accessor(name, definition)
-      define_instance_reader(name) if options.fetch(:instance_reader, true)
+        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
     end
 
-    # Defines a read-only class attribute (no writer).
+    # Defines a read-only class attribute.
+    #
+    # Equivalent to calling `class_attribute(name, readonly: true, ...)`
     #
     # @param name [Symbol]
     # @param options [Hash]
@@ -71,14 +59,14 @@ module Cattri
       class_attribute(name, readonly: true, **options)
     end
 
-    # Returns all defined class-level attribute names.
+    # Returns a list of defined class attribute names.
     #
     # @return [Array<Symbol>]
     def class_attributes
       __cattri_class_attributes.keys
     end
 
-    # Checks whether a class-level attribute is defined.
+    # Checks whether a class attribute has been defined.
     #
     # @param name [Symbol]
     # @return [Boolean]
@@ -86,161 +74,62 @@ module Cattri
       __cattri_class_attributes.key?(name.to_sym)
     end
 
-    # Returns metadata for a given class-level attribute.
+    # Returns the full attribute definition object.
     #
     # @param name [Symbol]
-    # @return [Hash, nil]
+    # @return [Cattri::Attribute, nil]
     def class_attribute_definition(name)
       __cattri_class_attributes[name.to_sym]
     end
 
-    # Resets all defined class attributes to their default values.
-    #
-    # @return [void]
-    def reset_class_attributes!
-      reset_attributes!(self, __cattri_class_attributes.values)
-    end
-
-    # Resets a single class attribute to its default value.
-    #
-    # @param name [Symbol]
-    # @return [void]
-    def reset_class_attribute!(name)
-      definition = __cattri_class_attributes[name]
-      return unless definition
-
-      reset_attributes!(self, [definition])
-    end
-
-    # alias lock_cattrs! lock_class_attributes!
-    # alias cattrs_locked? class_attributes_locked?
-
     # @!method cattr(name, **options, &block)
     #   Alias for {.class_attribute}
-    #   @see .class_attribute
+    #   @see #class_attribute
     alias cattr class_attribute
 
     # @!method cattr_accessor(name, **options, &block)
     #   Alias for {.class_attribute}
-    #   @see .class_attribute
+    #   @see #class_attribute
     alias cattr_accessor class_attribute
 
     # @!method cattr_reader(name, **options)
     #   Alias for {.class_attribute_reader}
-    #   @see .class_attribute_reader
+    #   @see #class_attribute_reader
     alias cattr_reader class_attribute_reader
 
     # @!method cattrs
-    #   @return [Array<Symbol>] all defined class attribute names
-    #   @see .class_attributes
+    #   Alias for {.class_attributes}
+    #   @return [Array<Symbol>]
     alias cattrs class_attributes
 
     # @!method cattr_defined?(name)
-    #   @return [Boolean] whether the given attribute has been defined
-    #   @see .class_attribute_defined?
+    #   Alias for {.class_attribute_defined?}
+    #   @param name [Symbol]
+    #   @return [Boolean]
     alias cattr_defined? class_attribute_defined?
 
-    # @!method cattr_for(name)
-    #   @return [Hash, nil] the internal metadata hash for a defined attribute
-    #   @see .class_attribute_for
+    # @!method cattr_definition(name)
+    #   Alias for {.class_attribute_definition}
+    #   @param name [Symbol]
+    #   @return [Cattri::Attribute, nil]
     alias cattr_definition class_attribute_definition
 
-    # @!method reset_cattrs!
-    #   Resets all class attributes to their default values.
-    #   @see .reset_class_attributes!
-    alias reset_cattrs! reset_class_attributes!
-
-    # @!method reset_cattr!(name)
-    #   Resets a specific class attribute to its default value.
-    #   @see .reset_class_attribute!
-    alias reset_cattr! reset_class_attribute!
-
     private
 
-    # Defines class-level inheritance behavior for declared attributes.
-    #
-    # @return [void]
-    def define_inheritance
-      unless singleton_class.method_defined?(:__cattri_class_attributes)
-        define_singleton_method(:__cattri_class_attributes) { @__cattri_class_attributes ||= {} }
-      end
-
-      define_singleton_method(:inherited) do |subclass|
-        super(subclass)
-        subclass_attributes = {}
-
-        __cattri_class_attributes.each do |name, definition|
-          apply_attribute!(subclass, subclass_attributes, name, definition)
-        end
-
-        subclass.instance_variable_set(:@__cattri_class_attributes, subclass_attributes)
-      end
-    end
-
-    # Defines the primary accessor method on the class.
-    #
-    # @param name [Symbol]
-    # @param definition [Hash]
-    # @return [void]
-    def define_accessor(name, definition)
-      ivar = definition[:ivar]
-
-      define_singleton_method(name) do |*args, **kwargs|
-        readonly = readonly_call?(args, kwargs) || definition[:readonly]
-        return apply_readonly(ivar, definition[:default]) if readonly
-
-        instance_variable_set(ivar, definition[:setter].call(*args, **kwargs))
-      end
-
-      return if definition[:readonly]
-
-      define_singleton_method("#{name}=") do |value|
-        instance_variable_set(ivar, definition[:setter].call(value))
-      end
-    end
-
-    # Defines an instance-level reader that delegates to the class-level method.
-    #
-    # @param name [Symbol]
-    # @return [void]
-    def define_instance_reader(name)
-      define_method(name) { self.class.__send__(name) }
-    end
-
-    # Applies the default value for a read-only call.
+    # Internal registry of defined class-level attributes.
     #
-    # @param ivar [Symbol]
-    # @param default [Proc]
-    # @return [Object]
-    def apply_readonly(ivar, default)
-      return instance_variable_get(ivar) if instance_variable_defined?(ivar)
-
-      value = default.call
-      instance_variable_set(ivar, value)
+    # @return [Hash{Symbol => Cattri::Attribute}]
+    def __cattri_class_attributes
+      @__cattri_class_attributes ||= {}
     end
 
-    # Applies inherited attribute definitions to a subclass.
+    # Context object used to define accessors with scoped visibility.
     #
-    # @param subclass [Class]
-    # @param attributes [Hash]
-    # @param name [Symbol]
-    # @param definition [Hash]
-    # @return [void]
-    def apply_attribute!(subclass, attributes, name, definition)
-      value = instance_variable_get(definition[:ivar])
-      value = value.dup rescue value # rubocop:disable Style/RescueModifier
-
-      subclass.instance_variable_set(definition[:ivar], value)
-      attributes[name] = definition
-    end
-
-    # Determines if the method call should be treated as read-only access.
-    #
-    # @param args [Array]
-    # @param kwargs [Hash]
-    # @return [Boolean]
-    def readonly_call?(args, kwargs)
-      args.empty? && kwargs.empty?
+    # @return [Cattri::Context]
+    # :nocov:
+    def context
+      @context ||= Context.new(self)
     end
+    # :nocov:
   end
 end

data/lib/cattri/context.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Cattri
+  # Provides a controlled interface for defining methods and instance variables
+  # on a target class or module. Used internally by Cattri to define attribute
+  # readers and writers while preserving access visibility and tracking which
+  # methods were explicitly created.
+  #
+  # This abstraction allows class and instance attribute logic to be composed
+  # consistently and safely across both standard and singleton contexts.
+  class Context
+    # Allowed Ruby visibility levels for methods.
+    ACCESS_LEVELS = %i[public protected private].freeze
+    private_constant :ACCESS_LEVELS
+
+    # @return [Module, Class] the receiver to which accessors will be added
+    attr_reader :target
+
+    # Initializes a new context wrapper around the given target.
+    #
+    # @param target [Module, Class] the object to define methods or ivars on
+    def initialize(target)
+      @target = target
+      @defined_methods = Set.new
+    end
+
+    # Returns the singleton class of the target.
+    #
+    # This is used to define methods on the class itself (not its instances).
+    #
+    # @return [Class]
+    def singleton
+      @target.singleton_class
+    end
+
+    # Checks whether a method is already defined on the target.
+    #
+    # This includes public, protected, private, and previously defined methods
+    # via this context (tracked in `@defined_methods`).
+    #
+    # @param method [String, Symbol]
+    # @return [Boolean]
+    def method_defined?(method)
+      @target.method_defined?(method) ||
+        @target.private_method_defined?(method) ||
+        @target.protected_method_defined?(method) ||
+        @defined_methods.include?(method.to_sym)
+    end
+
+    # Defines a method on the appropriate context (class or singleton).
+    #
+    # If the method already exists, it is not redefined. Visibility is applied
+    # according to the attribute's `:access` setting (defaulting to `:public`).
+    #
+    # @param attribute [Cattri::Attribute]
+    # @param name [Symbol, nil] optional method name override
+    # @yield the method implementation
+    # @raise [Cattri::AttributeDefinitionError] if method definition fails
+    # @return [void]
+    def define_method(attribute, name: nil, &block)
+      name = (name || attribute.name).to_sym
+      return if method_defined?(name)
+
+      target = target_for(attribute)
+
+      begin
+        target.define_method(name, &block)
+        @defined_methods << name
+        apply_access(name, attribute)
+      rescue StandardError => e
+        raise Cattri::AttributeDefinitionError.new(target, attribute, e)
+      end
+    end
+
+    # Checks whether the target has the given instance variable.
+    #
+    # @param name [Symbol, String]
+    # @return [Boolean]
+    def ivar_defined?(name)
+      @target.instance_variable_defined?(sanitize_ivar(name))
+    end
+
+    # Retrieves the value of the specified instance variable on the target.
+    #
+    # @param name [Symbol, String]
+    # @return [Object]
+    def ivar_get(name)
+      @target.instance_variable_get(sanitize_ivar(name))
+    end
+
+    # Assigns a value to the specified instance variable on the target.
+    #
+    # @param name [Symbol, String]
+    # @param value [Object]
+    # @return [void]
+    def ivar_set(name, value)
+      @target.instance_variable_set(sanitize_ivar(name), value)
+    end
+
+    # Memoizes a value in the instance variable only if not already defined.
+    #
+    # @param name [Symbol, String]
+    # @param value [Object]
+    # @return [Object] the existing or assigned value
+    def ivar_memoize(name, value)
+      return ivar_get(name) if ivar_defined?(name)
+
+      ivar_set(name, value)
+    end
+
+    private
+
+    # Selects the correct definition target based on attribute type.
+    #
+    # @param attribute [Cattri::Attribute]
+    # @return [Module] either the target or its singleton class
+    def target_for(attribute)
+      attribute.class_level? ? singleton : @target
+    end
+
+    # Validates and normalizes access level.
+    #
+    # @param access [Symbol, String, nil]
+    # @return [Symbol] a valid visibility level
+    def validate_access(access)
+      access = (access || :public).to_sym
+      return access if ACCESS_LEVELS.include?(access)
+
+      warn "[Cattri] `#{access.inspect}` is not a supported access level, defaulting to :public"
+      :public
+    end
+
+    # Applies method visibility to a newly defined method.
+    #
+    # @param method_name [Symbol]
+    # @param attribute [Cattri::Attribute]
+    # @return [void]
+    def apply_access(method_name, attribute)
+      return if attribute.public?
+
+      access = validate_access(attribute[:access])
+      Module.instance_method(access).bind(@target).call(method_name)
+    end
+
+    # Ensures consistent formatting for ivar keys.
+    #
+    # @param name [Symbol, String]
+    # @return [Symbol]
+    def sanitize_ivar(name)
+      :"@#{name.to_s.delete_prefix("@")}"
+    end
+  end
+end

data/lib/cattri/error.rb

@@ -1,5 +1,72 @@
 # 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 attribute [Cattri::Attribute] the conflicting attribute
+    def initialize(attribute)
+      super("#{attribute.type.capitalize} attribute :#{attribute.name} has already 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 < Error
+    # @param type [Symbol] the invalid type that triggered the error
+    def initialize(type)
+      super("Attribute type :#{type} is not supported")
+    end
+  end
 end