cattri 0.1.0 → 0.1.2

data/lib/cattri/attribute_definer.rb

@@ -0,0 +1,124 @@
+# 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?
+
+        context.target.define_method(attribute.name) do
+          self.class.__send__(attribute.name)
+        end
+
+        context.send(:apply_access, attribute.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,84 +1,111 @@
 # 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.
+    # 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.
     #
-    # @param name [Symbol] the attribute name
+    # @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 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
+    # @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)
     # @return [void]
-    def class_attribute(name, **options, &block)
-      define_inheritance unless respond_to?(:__cattri_class_attributes)
+    def class_attribute(*names, **options, &block)
+      raise Cattri::AmbiguousBlockError if names.size > 1 && block_given?
 
-      name, definition = define_attribute(name, options, block, DEFAULT_OPTIONS)
-      raise Cattri::Error, "Class attribute `#{name}` already defined" if class_attribute_defined?(name)
+      names.each { |name| define_class_attribute(name, options, block) }
+    end
 
-      __cattri_class_attributes[name] = definition
-      define_accessor(name, definition)
-      define_instance_reader(name) if options.fetch(:instance_reader, true)
+    # 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)
+    # @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
 
-    # Defines a read-only class attribute (no writer).
+    # Updates the setter behavior of an existing class-level attribute.
     #
-    # @param name [Symbol]
-    # @param options [Hash]
+    # 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_reader(name, **options)
-      class_attribute(name, readonly: true, **options)
+    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
 
-    # 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 +113,92 @@ 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.
+    # Defines a single class-level attribute.
     #
-    # @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.
+    # 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
     #
-    # @param name [Symbol]
-    # @param definition [Hash]
     # @return [void]
-    def define_accessor(name, definition)
-      ivar = definition[:ivar]
+    def define_class_attribute(name, options, block) # rubocop:disable Metrics/AbcSize
+      options[:access] ||= __cattri_visibility
+      attribute = Cattri::Attribute.new(name, :class, options, block)
 
-      define_singleton_method(name) do |*args, **kwargs|
-        readonly = readonly_call?(args, kwargs) || definition[:readonly]
-        return apply_readonly(ivar, definition[:default]) if readonly
+      raise Cattri::AttributeDefinedError.new(:class, name) if class_attribute_defined?(attribute.name)
 
-        instance_variable_set(ivar, definition[:setter].call(*args, **kwargs))
-      end
-
-      return if definition[:readonly]
+      begin
+        __cattri_class_attributes[name] = attribute
 
-      define_singleton_method("#{name}=") do |value|
-        instance_variable_set(ivar, definition[:setter].call(value))
+        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 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,171 @@
+# 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)
+
+      define_method!(attribute, name: name, &block)
+    end
+
+    # Defines a method on the target class or singleton class, regardless of whether it already exists.
+    #
+    # This bypasses any checks for prior definition and forcibly installs the method using `define_method`.
+    # The method will be assigned visibility based on the attribute's `:access` setting.
+    #
+    # Used internally by attribute definers to (re)define writers, readers, or callables.
+    #
+    # @param attribute [Cattri::Attribute] the attribute whose context and access rules apply
+    # @param name [Symbol, nil] the method name to define (defaults to attribute name)
+    # @yield the method body to define
+    # @raise [Cattri::AttributeDefinitionError] if method definition fails
+    # @return [void]
+    def define_method!(attribute, name: nil, &block)
+      target = target_for(attribute)
+
+      begin
+        target.define_method(name, &block)
+        @defined_methods << name unless method_defined?(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