domainic-attributer 0.1.0 → 0.2.0

data/lib/domainic/attributer/dsl/initializer.rb

@@ -1,15 +1,19 @@
 # frozen_string_literal: true
 
+require 'domainic/attributer/undefined'
+
 module Domainic
   module Attributer
     module DSL
-      # A class responsible for handling object initialization with attributes.
+      # A class responsible for handling object initialization with attributes
       #
       # This class manages the process of setting attribute values during object
       # initialization. It handles both positional arguments and keyword options,
       # applying them to their corresponding attributes while respecting default
-      # values and required attributes.
+      # values and required attributes
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Initializer
@@ -18,25 +22,25 @@ module Domainic
         # @rbs @base: Object
         # @rbs @option_attributes: Array[Attribute]
 
-        # Initialize a new Initializer.
+        # Initialize a new Initializer
         #
         # @param base [Object] the instance being initialized
         #
-        # @return [void]
+        # @return [Initializer] the new Initializer instance
         # @rbs (Object base) -> void
         def initialize(base)
           @base = base
           @attributes ||= @base.class.send(:__attributes__)
         end
 
-        # Assign values to attributes.
+        # Assign values to attributes
         #
         # Validates and applies both positional arguments and keyword options to
         # their corresponding attributes. Raises an error if required arguments
-        # are missing.
+        # are missing
         #
-        # @param arguments [Array] positional arguments to assign
-        # @param keyword_arguments [Hash] keyword arguments to assign
+        # @param arguments [Array<Object>] positional arguments to assign
+        # @param keyword_arguments [Hash{Symbol => Object}] keyword arguments to assign
         #
         # @raise [ArgumentError] if required arguments are missing
         # @return [void]
@@ -49,14 +53,14 @@ module Domainic
 
         private
 
-        # Access to the current attribute set.
+        # Access to the current attribute set
         #
         # @return [AttributeSet] the attribute set for this instance
         attr_reader :attributes #: AttributeSet
 
-        # Apply positional arguments to their attributes.
+        # Apply positional arguments to their attributes
         #
-        # @param arguments [Array] the positional arguments to apply
+        # @param arguments [Array<Object>] the positional arguments to apply
         #
         # @return [void]
         # @rbs (Array[untyped]) -> void
@@ -67,9 +71,9 @@ module Domainic
           end
         end
 
-        # Apply keyword arguments to their attributes.
+        # Apply keyword arguments to their attributes
         #
-        # @param options [Hash] the keyword options to apply
+        # @param options [Hash{Symbol => Object}] the keyword options to apply
         #
         # @return [void]
         # @rbs (Hash[String | Symbol, untyped]) -> void
@@ -85,7 +89,7 @@ module Domainic
           end
         end
 
-        # Get all argument attributes.
+        # Get all argument attributes
         #
         # @return [Array<Attribute>] the argument attributes
         # @rbs () -> Array[Attribute]
@@ -93,17 +97,18 @@ module Domainic
           @argument_attributes ||= attributes.select { |_, attribute| attribute.signature.argument? }.attributes
         end
 
-        # Assign a value to an attribute.
+        # Assign a value to an attribute
         #
         # @param attribute_name [Symbol] the name of the attribute
         # @param value [Object] the value to assign
         #
         # @return [void]
+        # @rbs (String | Symbol attribute_name, untyped value) -> void
         def assign_value(attribute_name, value)
           @base.send(:"#{attribute_name}=", value)
         end
 
-        # Get all option attributes.
+        # Get all option attributes
         #
         # @return [Array<Attribute>] the option attributes
         # @rbs () -> Array[Attribute]
@@ -111,9 +116,9 @@ module Domainic
           @option_attributes ||= attributes.select { |_, attribute| attribute.signature.option? }.attributes
         end
 
-        # Validate that all required positional arguments are provided.
+        # Validate that all required positional arguments are provided
         #
-        # @param arguments [Array] the arguments to validate
+        # @param arguments [Array<Object>] the arguments to validate
         #
         # @raise [ArgumentError] if required arguments are missing
         # @return [void]

data/lib/domainic/attributer/dsl/method_injector.rb

@@ -3,23 +3,25 @@
 module Domainic
   module Attributer
     module DSL
-      # A class responsible for injecting attribute methods into classes.
+      # A class responsible for injecting attribute methods into classes
       #
       # This class handles the creation of reader and writer methods for attributes,
       # ensuring they are injected safely without overwriting existing methods. It
       # respects visibility settings and properly handles value assignment through
-      # the attribute system.
+      # the attribute system
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class MethodInjector
         # @rbs @attribute: Attribute
         # @rbs @base: __todo__
 
-        # Inject methods for an attribute into a class.
+        # Inject methods for an attribute into a class
         #
         # @param base [Class, Module] the class to inject methods into
-        # @param attribute [Attribute] the attribute to create methods for
+        # @param attribute [Attribute] the {Attribute} to create methods for
         #
         # @return [void]
         # @rbs (__todo__ base, Attribute attribute) -> void
@@ -27,19 +29,19 @@ module Domainic
           new(base, attribute).inject!
         end
 
-        # Initialize a new MethodInjector.
+        # Initialize a new MethodInjector
         #
         # @param base [Class, Module] the class to inject methods into
-        # @param attribute [Attribute] the attribute to create methods for
+        # @param attribute [Attribute] the {Attribute} to create methods for
         #
-        # @return [void]
+        # @return [MethodInjector] the new MethodInjector instance
         # @rbs (__todo__ base, Attribute attribute) -> void
         def initialize(base, attribute)
           @attribute = attribute
           @base = base
         end
 
-        # Inject reader and writer methods.
+        # Inject reader and writer methods
         #
         # @return [void]
         # @rbs () -> void
@@ -50,11 +52,11 @@ module Domainic
 
         private
 
-        # Define a method if it doesn't already exist.
+        # Define a method if it doesn't already exist
         #
         # @param method_name [Symbol] the name of the method to define
-        # @yield the method body to define
         #
+        # @yield the method body to define
         # @return [void]
         # @rbs (Symbol method_name) { (?) [self: untyped] -> void } -> void
         def define_safe_method(method_name, &)
@@ -63,9 +65,9 @@ module Domainic
           @base.define_method(method_name, &)
         end
 
-        # Inject the attribute reader method.
+        # Inject the attribute reader method
         #
-        # Creates a reader method with the configured visibility.
+        # Creates a reader method with the configured visibility
         #
         # @return [void]
         # @rbs () -> void
@@ -74,10 +76,10 @@ module Domainic
           @base.send(@attribute.signature.read_visibility, @attribute.name)
         end
 
-        # Inject the attribute writer method.
+        # Inject the attribute writer method
         #
         # Creates a writer method that processes values through the attribute
-        # system before assignment. Sets the configured visibility.
+        # system before assignment. Sets the configured visibility
         #
         # @return [void]
         # @rbs () -> void

data/lib/domainic/attributer/errors/aggregate_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/errors/error'
+
+module Domainic
+  module Attributer
+    # A specialized error class that combines multiple errors into a single error
+    #
+    # This class encapsulates multiple errors that occur during a single operation and
+    # need to be reported together. It maintains a list of individual errors while providing
+    # a formatted message that includes details from all errors
+    #
+    # @api private
+    # @!visibility private
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class AggregateError < Error
+      # Get the collection of errors that were aggregated
+      #
+      # @return [Array<StandardError>] the collection of errors
+      attr_reader :errors #: Array[StandardError]
+
+      # Initialize a new AggregateError instance
+      #
+      # @param message [String] the main error message
+      # @param errors [Array<StandardError>] the collection of errors to aggregate
+      #
+      # @return [AggregateError] the new AggregateError instance
+      # @rbs (String message, Array[StandardError] errors) -> void
+      def initialize(message, errors)
+        @errors = errors
+        super("#{message}\n#{errors.map { |error| "  - #{error.message}" }.join("\n")}")
+      end
+    end
+  end
+end

data/lib/domainic/attributer/errors/callback_execution_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/errors/aggregate_error'
+
+module Domainic
+  module Attributer
+    # A specialized error class for callback execution failures
+    #
+    # This error class is used when one or more callbacks fail during attribute value
+    # changes. It aggregates all callback-related errors into a single error with a
+    # descriptive message listing each individual failure
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class CallbackExecutionError < AggregateError
+      # Initialize a new CallbackExecutionError instance
+      #
+      # @api private
+      # @!visibility private
+      #
+      # @param errors [Array<StandardError>] the collection of callback errors to aggregate
+      #
+      # @return [CallbackExecutionError] the new CallbackExecutionError instance
+      # @rbs (Array[StandardError] errors) -> void
+      def initialize(errors)
+        super('The following errors occurred during callback execution:', errors)
+      end
+    end
+  end
+end

data/lib/domainic/attributer/errors/coercion_execution_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/errors/error'
+
+module Domainic
+  module Attributer
+    # A specialized error class for coercion execution failures
+    #
+    # This error class is used when a coercion fails during attribute value
+    # processing. It captures the failing coercer to provide context about which
+    # step in the coercion chain caused the failure
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class CoercionExecutionError < Error
+      # Get the coercer that failed
+      #
+      # @return [Proc, Symbol] the coercer that failed
+      attr_reader :coercer #: Attribute::Coercer::handler
+
+      # Initialize a new CoercionExecutionError instance
+      #
+      # @api private
+      # @!visibility private
+      #
+      # @param message [String] the error message
+      # @param coercer [Proc, Symbol] the coercer that failed
+      #
+      # @return [CoercionExecutionError] the new CoercionExecutionError instance
+      # @rbs (String message, Attribute::Coercer::handler coercer) -> void
+      def initialize(message, coercer)
+        @coercer = coercer
+        super(message)
+      end
+    end
+  end
+end

data/lib/domainic/attributer/errors/error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Attributer
+    # Base error class for all Attributer-related errors
+    #
+    # This class serves as the foundation for Attributer's error hierarchy, allowing
+    # for specific error types to be caught and handled appropriately. All custom
+    # errors within the Attributer system should inherit from this class to maintain
+    # a consistent error handling pattern
+    #
+    # @api private
+    # @!visibility private
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class Error < StandardError
+    end
+  end
+end

data/lib/domainic/attributer/errors/validation_execution_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/errors/aggregate_error'
+
+module Domainic
+  module Attributer
+    # A specialized error class for validation execution failures
+    #
+    # This error class is used when one or more validations encounter errors during
+    # their execution. It aggregates all validation-related errors into a single
+    # error with a descriptive message listing each individual failure
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class ValidationExecutionError < AggregateError
+      # Initialize a new ValidationExecutionError instance
+      #
+      # @api private
+      # @!visibility private
+      #
+      # @param errors [Array<StandardError>] the collection of validation errors to aggregate
+      #
+      # @return [ValidationExecutionError] the new ValidationExecutionError instance
+      # @rbs (Array[StandardError] errors) -> void
+      def initialize(errors)
+        super('The following errors occurred during validation execution:', errors)
+      end
+    end
+  end
+end

data/lib/domainic/attributer/instance_methods.rb

@@ -4,11 +4,11 @@ require 'domainic/attributer/dsl/initializer'
 
 module Domainic
   module Attributer
-    # A module providing instance-level attribute functionality.
+    # A module providing instance-level attribute functionality
     #
-    # This module defines instance methods for objects that include Domainic::Attributer.
+    # This module defines instance methods for objects that include {Domainic::Attributer}.
     # It provides initialization handling and attribute serialization capabilities, making
-    # it easy to work with attribute values in a consistent way.
+    # it easy to work with attribute values in a consistent way
     #
     # @example Basic usage
     #   class Person
@@ -25,7 +25,7 @@ module Domainic
     # @author {https://aaronmallen.me Aaron Allen}
     # @since 0.1.0
     module InstanceMethods
-      # Initialize a new instance with attribute values.
+      # Initialize a new instance with attribute values
       #
       # Handles both positional arguments and keyword options, applying them to their
       # corresponding attributes. This process includes:
@@ -34,20 +34,23 @@ module Domainic
       # 3. Type validation and coercion
       # 4. Change notifications
       #
+      # @example
+      #   person = Person.new('Alice', age: 30)
+      #
       # @raise [ArgumentError] if required arguments are missing
-      # @return [void]
+      # @return [InstanceMethods] the new InstanceMethods instance
       # @rbs (*untyped arguments, **untyped keyword_arguments) -> void
       def initialize(...)
         DSL::Initializer.new(self).assign!(...)
       end
 
-      # Convert public attribute values to a hash.
+      # Convert public attribute values to a hash
       #
       # Creates a hash containing all public readable attributes and their current values.
       # Any attributes marked as private or protected for reading are excluded from
-      # the result.
+      # the result
       #
-      # @example Basic conversion
+      # @example
       #   person = Person.new('Alice', age: 30)
       #   person.to_h  # => { name: 'Alice', age: 30 }
       #

data/lib/domainic/attributer/undefined.rb

@@ -2,38 +2,40 @@
 
 module Domainic
   module Attributer
-    # A singleton object representing an undefined value.
+    # A singleton object representing an undefined value
     #
-    # This object is used throughout Domainic::Attributer to represent values that
+    # This object is used throughout {Domainic::Attributer} to represent values that
     # are explicitly undefined, as opposed to nil which represents the absence of
     # a value. It is immutable and implements custom string representations for
-    # debugging purposes.
+    # debugging purposes
     #
+    # @api private
+    # @!visibility private
     # @author {https://aaronmallen.me Aaron Allen}
     # @since 0.1.0
     Undefined = Object.new.tap do |undefined|
-      # Returns self to prevent cloning.
+      # Prevent cloning of the singleton
       #
       # @return [Undefined] self
       def undefined.clone(...)
         self
       end
 
-      # Returns self to prevent duplication.
+      # Prevent duplication of the singleton
       #
       # @return [Undefined] self
       def undefined.dup
         self
       end
 
-      # Returns a string representation of the object.
+      # Get a string representation of the object
       #
       # @return [String] the string 'Undefined'
       def undefined.inspect
         to_s
       end
 
-      # Converts the object to a string.
+      # Convert the object to a string
       #
       # @return [String] the string 'Undefined'
       def undefined.to_s

data/lib/domainic/attributer.rb

@@ -8,38 +8,64 @@ require 'domainic/attributer/instance_methods'
 require 'domainic/attributer/undefined'
 
 module Domainic
-  # Core functionality for defining and managing Ruby class attributes.
+  # `Domainic::Attributer` is a powerful toolkit that brings clarity and safety to your Ruby class attributes.
+  # Ever wished your class attributes could:
   #
-  # This module provides a flexible attribute system for Ruby classes that supports
-  # positional arguments and keyword options with features like type validation,
-  # coercion, and visibility control.
+  # * Validate themselves to ensure they only accept correct values?
+  # * Transform input data automatically into the right format?
+  # * Have clear, enforced visibility rules?
+  # * Handle their own default values intelligently?
+  # * Tell you when they change?
+  # * Distinguish between required arguments and optional settings?
   #
-  # Can be included directly with default method names or customized via {Domainic.Attributer}.
+  # That's exactly what `Domainic::Attributer` does! It provides a declarative way to define and manage attributes
+  # in your Ruby classes, ensuring data integrity and clear interfaces. It's particularly valuable for:
   #
-  # @example Basic usage with default method names
-  #   class Person
+  # * Domain models and value objects
+  # * Service objects and command patterns
+  # * Configuration objects
+  # * Any class where attribute behavior matters
+  #
+  # Think of it as giving your attributes a brain - they know what they want, how they should behave, and
+  # they're not afraid to speak up when something's not right!
+  #
+  # @see file:docs/USAGE.md Usage Guide
+  # @abstract Can be included directly with default method names or customized via {.Attributer}
+  #
+  # @example Basic usage
+  #   class SuperDev
   #     include Domainic::Attributer
   #
-  #     argument :name
-  #     option :age
+  #     argument :code_name, String
+  #
+  #     option :power_level, Integer, default: 9000
+  #     option :favorite_gem do
+  #       validate_with ->(val) { val.to_s.end_with?('ruby') }
+  #       coerce_with ->(val) { val.to_s.downcase }
+  #       non_nilable
+  #     end
   #   end
   #
-  # @example Custom method names
-  #   class Person
-  #     include Domainic.Attributer(argument: :param, option: :opt)
+  #   dev = SuperDev.new('RubyNinja', favorite_gem: 'RAILS_RUBY')
+  #   # => #<SuperDev:0x00000001083aeb58 @code_name="RubyNinja", @favorite_gem="rails_ruby", @power_level=9000>
   #
-  #     param :name
-  #     opt :age
-  #   end
+  #   dev.favorite_gem # => "rails_ruby"
+  #   dev.power_level = 9001 # => 9001
+  #   dev.power_level = 'over 9000'
+  #   # `SuperDev#power_level`: has invalid value: "over 9000" (ArgumentError)
   #
   # @author {https://aaronmallen.me Aaron Allen}
   # @since 0.1.0
   module Attributer
     class << self
-      # Create a customized Attributer module.
+      # Create a customized Attributer module
+      #
+      # @!visibility private
+      # @api private
       #
       # @param argument [Symbol, String] custom name for the argument method
       # @param option [Symbol, String] custom name for the option method
+      #
       # @return [Module] configured Attributer module
       # @rbs (?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> Module
       def call(argument: :argument, option: :option)
@@ -55,9 +81,13 @@ module Domainic
         end
       end
 
-      # Handle direct module inclusion.
+      # Handle direct module inclusion
+      #
+      # @!visibility private
+      # @api private
       #
       # @param base [Class, Module] the including class/module
+      #
       # @return [void]
       # @rbs (untyped base) -> void
       def included(base)
@@ -67,10 +97,11 @@ module Domainic
 
       private
 
-      # Configure base class with Attributer functionality.
+      # Configure base class with Attributer functionality
       #
       # @param base [Class, Module] the target class/module
-      # @param options [Hash] method name customization options
+      # @param options [Hash{Symbol => String, Symbol}] method name customization options
+      #
       # @return [void]
       # @rbs (untyped base, ?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> void
       def include_attributer(base, **options)
@@ -79,10 +110,11 @@ module Domainic
         inject_custom_methods!(base, **options)
       end
 
-      # Set up custom method names.
+      # Set up custom method names
       #
       # @param base [Class, Module] the target class/module
-      # @param options [Hash] method name customization options
+      # @param options [Hash{Symbol => String, Symbol}] method name customization options
+      #
       # @return [void]
       # @rbs (untyped base, ?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> void
       def inject_custom_methods!(base, **options)
@@ -96,17 +128,46 @@ module Domainic
     end
   end
 
-  # Create a customized Attributer module.
-  #
-  # Provides a convenient way to include Attributer with customized method names.
+  # Provides a convenient way to include {Attributer} with customized method names
   #
-  # @example
+  # @example Customizing method names
   #   class Person
   #     include Domainic.Attributer(argument: :param, option: :opt)
+  #
+  #     param :name, String
+  #     opt :age, Integer
   #   end
   #
-  # @param options [Hash] method name customization options
-  # @return [Module] configured Attributer module
+  #   Person.respond_to?(:argument) # => false
+  #   Person.respond_to?(:param)  # => true
+  #   Person.respond_to?(:option) # => false
+  #   Person.respond_to?(:opt)  # => true
+  #
+  #   person = Person.new('Alice', age: 30)
+  #   # => #<Person:0x000000010865d188 @age=30, @name="Alice">
+  #
+  # @example Turning off a method
+  #
+  #   class Person
+  #     include Domainic.Attributer(argument: nil)
+  #
+  #     option :name, String
+  #     option :age, Integer
+  #   end
+  #
+  #   Person.respond_to?(:argument)  # => false
+  #   Person.respond_to?(:option) # => true
+  #
+  #   person = Person.new(name: 'Alice', age: 30)
+  #   # => #<Person:0x000000010865d188 @age=30, @name="Alice">
+  #
+  # @param options [Hash{Symbol => String, Symbol, nil}] method name customization options
+  # @option options [String, Symbol, nil] :argument custom name for the {Attributer::ClassMethods#argument argument}
+  #   method. Set to `nil` to disable the method entirely
+  # @option options [String, Symbol, nil] :option custom name for the {Attributer::ClassMethods#option option}
+  #   method. Set to `nil` to disable the method entirely
+  #
+  # @return [Module] the configured {Attributer} module
   # @rbs (?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> Module
   def self.Attributer(**options) # rubocop:disable Naming/MethodName
     Domainic::Attributer.call(**options)