domainic-attributer 0.1.0

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

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/attribute'
+require 'domainic/attributer/dsl/attribute_builder/option_parser'
+require 'domainic/attributer/undefined'
+
+module Domainic
+  module Attributer
+    module DSL
+      # A class responsible for configuring attributes through a fluent interface.
+      #
+      # This class provides a rich DSL for configuring attributes with support for
+      # default values, coercion, validation, visibility controls, and change tracking.
+      # It uses method chaining to allow natural, declarative attribute definitions.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class AttributeBuilder
+        # @rbs @base: __todo__
+        # @rbs @options: OptionParser::result
+
+        # Initialize a new AttributeBuilder.
+        #
+        # @param base [Class, Module] the class or module to build the attribute in
+        # @param attribute_name [String, Symbol] the name of the attribute
+        # @param attribute_type [String, Symbol] the type of attribute
+        # @param type_validator [Proc, Object, nil] optional type validator
+        # @param options [Hash] additional options for attribute configuration
+        # @yield configuration block for additional attribute settings
+        #
+        # @return [void]
+        # @rbs (
+        #   __todo__ base,
+        #   String | Symbol attribute_name,
+        #   String | Symbol attribute_type,
+        #   ?Attribute::Validator::handler? type_validator,
+        #   OptionParser::options options,
+        #   ) ? { (?) [self: AttributeBuilder] -> void } -> void
+        def initialize(base, attribute_name, attribute_type, type_validator = Undefined, **options, &block)
+          @base = base
+          # @type var options: OptionParser::options
+          @options = OptionParser.parse!(attribute_name, attribute_type, options)
+          @options[:validators] << type_validator if type_validator != Undefined
+          instance_exec(&block) if block
+        end
+
+        # Builds and finalizes the attribute.
+        #
+        # @return [Attribute] the configured attribute
+        # @rbs () -> Attribute
+        def build!
+          options = @options.compact
+                            .reject { |_, value| value == Undefined || (value.respond_to?(:empty?) && value.empty?) }
+          Attribute.new(@base, **options) # steep:ignore InsufficientKeywordArguments
+        end
+
+        # Configure value coercion.
+        #
+        # @param proc_symbol [Proc, Symbol, nil] optional coercion handler
+        # @yield optional coercion block
+        #
+        # @return [self] the builder for method chaining
+        # @rbs (?(Attribute::Coercer::proc | Object)? proc_symbol) ?{ (untyped value) -> untyped } -> self
+        def coerce_with(proc_symbol = Undefined, &block)
+          handler = proc_symbol == Undefined ? block : proc_symbol #: Attribute::Coercer::handler
+          @options[:coercers] << handler
+          self
+        end
+        alias coerce coerce_with
+
+        # Configure default value.
+        #
+        # @param value_or_proc [Object, Proc, nil] optional default value or generator
+        # @yield optional default value generator block
+        #
+        # @return [self] the builder for method chaining
+        # @rbs (?untyped? value_or_proc) ?{ (?) -> untyped } -> self
+        def default(value_or_proc = Undefined, &block)
+          @options[:default] = value_or_proc == Undefined ? block : value_or_proc
+          self
+        end
+        alias default_generator default
+        alias default_value default
+
+        # Set attribute description.
+        #
+        # @param text [String] the description text
+        #
+        # @return [self] the builder for method chaining
+        # @rbs (String? text) -> self
+        def description(text)
+          @options[:description] = text
+          self
+        end
+        alias desc description
+
+        # Mark attribute as non-nilable.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def non_nilable
+          @options[:nilable] = false
+          self
+        end
+        alias non_nil non_nilable
+        alias non_null non_nilable
+        alias non_nullable non_nilable
+        alias not_nil non_nilable
+        alias not_nilable non_nilable
+        alias not_null non_nilable
+        alias not_nullable non_nilable
+
+        # Configure change callback.
+        #
+        # @param proc [Proc, nil] optional callback handler
+        # @yield optional callback block
+        #
+        # @return [self] the builder for method chaining
+        # @rbs (?Attribute::Callback::handler? proc) ?{ (untyped old_value, untyped new_value) -> void } -> self
+        def on_change(proc = Undefined, &block)
+          handler = proc == Undefined ? block : proc #: Attribute::Callback::handler
+          @options[:callbacks] << handler
+          self
+        end
+
+        # Set private visibility for both read and write.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def private
+          private_read
+          private_write
+        end
+
+        # Set private visibility for read.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def private_read
+          @options[:read] = :private
+          self
+        end
+
+        # Set private visibility for write.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def private_write
+          @options[:write] = :private
+          self
+        end
+
+        # Set protected visibility for both read and write.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def protected
+          protected_read
+          protected_write
+        end
+
+        # Set protected visibility for read.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def protected_read
+          @options[:read] = :protected
+          self
+        end
+
+        # Set protected visibility for write.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def protected_write
+          @options[:write] = :protected
+          self
+        end
+
+        # Set public visibility for both read and write.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def public
+          public_read
+          public_write
+        end
+
+        # Set public visibility for read.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def public_read
+          @options[:read] = :public
+          self
+        end
+
+        # Set public visibility for write.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def public_write
+          @options[:write] = :public
+          self
+        end
+
+        # Mark attribute as required.
+        #
+        # @return [self] the builder for method chaining
+        # @rbs () -> self
+        def required
+          @options[:required] = true
+          self
+        end
+
+        # Configure value validation.
+        #
+        # @param object_or_proc [Object, Proc, nil] optional validation handler
+        # @yield optional validation block
+        #
+        # @return [self] the builder for method chaining
+        # @rbs (?Attribute::Validator::handler? object_or_proc) ?{ (untyped value) -> boolish } -> self
+        def validate_with(object_or_proc = Undefined, &block)
+          handler = object_or_proc == Undefined ? block : object_or_proc #: Attribute::Validator::handler
+          @options[:validators] << handler
+          self
+        end
+        alias validate validate_with
+        alias validates validate_with
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Attributer
+    module DSL
+      # 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.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Initializer
+        # @rbs @argument_attributes: Array[Attribute]
+        # @rbs @attributes: AttributeSet
+        # @rbs @base: Object
+        # @rbs @option_attributes: Array[Attribute]
+
+        # Initialize a new Initializer.
+        #
+        # @param base [Object] the instance being initialized
+        #
+        # @return [void]
+        # @rbs (Object base) -> void
+        def initialize(base)
+          @base = base
+          @attributes ||= @base.class.send(:__attributes__)
+        end
+
+        # 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.
+        #
+        # @param arguments [Array] positional arguments to assign
+        # @param keyword_arguments [Hash] keyword arguments to assign
+        #
+        # @raise [ArgumentError] if required arguments are missing
+        # @return [void]
+        # @rbs (*untyped arguments, **untyped keyword_arguments) -> void
+        def assign!(*arguments, **keyword_arguments)
+          validate_positional_arguments!(arguments)
+          apply_arguments(arguments)
+          apply_options!(keyword_arguments)
+        end
+
+        private
+
+        # Access to the current attribute set.
+        #
+        # @return [AttributeSet] the attribute set for this instance
+        attr_reader :attributes #: AttributeSet
+
+        # Apply positional arguments to their attributes.
+        #
+        # @param arguments [Array] the positional arguments to apply
+        #
+        # @return [void]
+        # @rbs (Array[untyped]) -> void
+        def apply_arguments(arguments)
+          argument_attributes.each_with_index do |attribute, index|
+            value = arguments.length > index ? arguments[index] : Undefined
+            assign_value(attribute.name, value)
+          end
+        end
+
+        # Apply keyword arguments to their attributes.
+        #
+        # @param options [Hash] the keyword options to apply
+        #
+        # @return [void]
+        # @rbs (Hash[String | Symbol, untyped]) -> void
+        def apply_options!(options)
+          options = options.transform_keys(&:to_sym)
+
+          option_attributes.each do |attribute|
+            if options.key?(attribute.name)
+              assign_value(attribute.name, options[attribute.name])
+            else
+              assign_value(attribute.name, Undefined)
+            end
+          end
+        end
+
+        # Get all argument attributes.
+        #
+        # @return [Array<Attribute>] the argument attributes
+        # @rbs () -> Array[Attribute]
+        def argument_attributes
+          @argument_attributes ||= attributes.select { |_, attribute| attribute.signature.argument? }.attributes
+        end
+
+        # Assign a value to an attribute.
+        #
+        # @param attribute_name [Symbol] the name of the attribute
+        # @param value [Object] the value to assign
+        #
+        # @return [void]
+        def assign_value(attribute_name, value)
+          @base.send(:"#{attribute_name}=", value)
+        end
+
+        # Get all option attributes.
+        #
+        # @return [Array<Attribute>] the option attributes
+        # @rbs () -> Array[Attribute]
+        def option_attributes
+          @option_attributes ||= attributes.select { |_, attribute| attribute.signature.option? }.attributes
+        end
+
+        # Validate that all required positional arguments are provided.
+        #
+        # @param arguments [Array] the arguments to validate
+        #
+        # @raise [ArgumentError] if required arguments are missing
+        # @return [void]
+        # @rbs (Array[untyped]) -> void
+        def validate_positional_arguments!(arguments)
+          required = argument_attributes.reject(&:default?)
+          return unless arguments.length < required.length
+
+          raise ArgumentError, "wrong number of arguments (given #{arguments.length}, expected #{required.length}+)"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Attributer
+    module DSL
+      # 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.
+      #
+      # @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.
+        #
+        # @param base [Class, Module] the class to inject methods into
+        # @param attribute [Attribute] the attribute to create methods for
+        #
+        # @return [void]
+        # @rbs (__todo__ base, Attribute attribute) -> void
+        def self.inject!(base, attribute)
+          new(base, attribute).inject!
+        end
+
+        # Initialize a new MethodInjector.
+        #
+        # @param base [Class, Module] the class to inject methods into
+        # @param attribute [Attribute] the attribute to create methods for
+        #
+        # @return [void]
+        # @rbs (__todo__ base, Attribute attribute) -> void
+        def initialize(base, attribute)
+          @attribute = attribute
+          @base = base
+        end
+
+        # Inject reader and writer methods.
+        #
+        # @return [void]
+        # @rbs () -> void
+        def inject!
+          inject_reader!
+          inject_writer!
+        end
+
+        private
+
+        # 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
+        #
+        # @return [void]
+        # @rbs (Symbol method_name) { (?) [self: untyped] -> void } -> void
+        def define_safe_method(method_name, &)
+          return if @base.method_defined?(method_name) || @base.private_method_defined?(method_name)
+
+          @base.define_method(method_name, &)
+        end
+
+        # Inject the attribute reader method.
+        #
+        # Creates a reader method with the configured visibility.
+        #
+        # @return [void]
+        # @rbs () -> void
+        def inject_reader!
+          @base.attr_reader @attribute.name
+          @base.send(@attribute.signature.read_visibility, @attribute.name)
+        end
+
+        # Inject the attribute writer method.
+        #
+        # Creates a writer method that processes values through the attribute
+        # system before assignment. Sets the configured visibility.
+        #
+        # @return [void]
+        # @rbs () -> void
+        def inject_writer!
+          attribute_name = @attribute.name
+
+          define_safe_method(:"#{attribute_name}=") do |value|
+            attribute = self.class.send(:__attributes__)[attribute_name] # steep:ignore NoMethod
+            attribute.apply!(self, value)
+          end
+
+          @base.send(@attribute.signature.write_visibility, :"#{attribute_name}=")
+        end
+      end
+    end
+  end
+end

data/lib/domainic/attributer/dsl.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/dsl/attribute_builder'
+require 'domainic/attributer/dsl/initializer'
+require 'domainic/attributer/dsl/method_injector'

data/lib/domainic/attributer/instance_methods.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/dsl/initializer'
+
+module Domainic
+  module Attributer
+    # A module providing instance-level attribute functionality.
+    #
+    # 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.
+    #
+    # @example Basic usage
+    #   class Person
+    #     include Domainic::Attributer
+    #
+    #     argument :name
+    #     option :age, default: nil
+    #     option :role, default: 'user', private_read: true
+    #   end
+    #
+    #   person = Person.new('Alice', age: 30)
+    #   person.to_h  # => { name: 'Alice', age: 30 }  # role is private, not included
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    module InstanceMethods
+      # Initialize a new instance with attribute values.
+      #
+      # Handles both positional arguments and keyword options, applying them to their
+      # corresponding attributes. This process includes:
+      # 1. Validating required arguments
+      # 2. Applying default values
+      # 3. Type validation and coercion
+      # 4. Change notifications
+      #
+      # @raise [ArgumentError] if required arguments are missing
+      # @return [void]
+      # @rbs (*untyped arguments, **untyped keyword_arguments) -> void
+      def initialize(...)
+        DSL::Initializer.new(self).assign!(...)
+      end
+
+      # 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.
+      #
+      # @example Basic conversion
+      #   person = Person.new('Alice', age: 30)
+      #   person.to_h  # => { name: 'Alice', age: 30 }
+      #
+      # @return [Hash{Symbol => Object}] hash of attribute names to values
+      # @rbs () -> Hash[Symbol, untyped]
+      def to_hash
+        public = self.class.send(:__attributes__).select { |_, attribute| attribute.signature.public_read? }
+        public.attributes.each_with_object({}) do |attribute, result|
+          result[attribute.name] = public_send(attribute.name)
+        end
+      end
+      alias to_h to_hash
+    end
+  end
+end

data/lib/domainic/attributer/undefined.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Attributer
+    # A singleton object representing an undefined value.
+    #
+    # 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.
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    Undefined = Object.new.tap do |undefined|
+      # Returns self to prevent cloning.
+      #
+      # @return [Undefined] self
+      def undefined.clone(...)
+        self
+      end
+
+      # Returns self to prevent duplication.
+      #
+      # @return [Undefined] self
+      def undefined.dup
+        self
+      end
+
+      # Returns a string representation of the object.
+      #
+      # @return [String] the string 'Undefined'
+      def undefined.inspect
+        to_s
+      end
+
+      # Converts the object to a string.
+      #
+      # @return [String] the string 'Undefined'
+      def undefined.to_s
+        'Undefined'
+      end
+    end.freeze #: Object
+  end
+end

data/lib/domainic/attributer.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/attribute'
+require 'domainic/attributer/attribute_set'
+require 'domainic/attributer/class_methods'
+require 'domainic/attributer/dsl'
+require 'domainic/attributer/instance_methods'
+require 'domainic/attributer/undefined'
+
+module Domainic
+  # Core functionality for defining and managing Ruby class attributes.
+  #
+  # 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.
+  #
+  # Can be included directly with default method names or customized via {Domainic.Attributer}.
+  #
+  # @example Basic usage with default method names
+  #   class Person
+  #     include Domainic::Attributer
+  #
+  #     argument :name
+  #     option :age
+  #   end
+  #
+  # @example Custom method names
+  #   class Person
+  #     include Domainic.Attributer(argument: :param, option: :opt)
+  #
+  #     param :name
+  #     opt :age
+  #   end
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since 0.1.0
+  module Attributer
+    class << self
+      # Create a customized Attributer module.
+      #
+      # @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)
+        Module.new do
+          @argument = argument
+          @option = option
+
+          # @rbs (untyped base) -> void
+          def self.included(base)
+            super
+            Domainic::Attributer.send(:include_attributer, base, argument: @argument, option: @option)
+          end
+        end
+      end
+
+      # Handle direct module inclusion.
+      #
+      # @param base [Class, Module] the including class/module
+      # @return [void]
+      # @rbs (untyped base) -> void
+      def included(base)
+        super
+        base.include(call)
+      end
+
+      private
+
+      # Configure base class with Attributer functionality.
+      #
+      # @param base [Class, Module] the target class/module
+      # @param options [Hash] method name customization options
+      # @return [void]
+      # @rbs (untyped base, ?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> void
+      def include_attributer(base, **options)
+        base.extend(ClassMethods)
+        base.include(InstanceMethods)
+        inject_custom_methods!(base, **options)
+      end
+
+      # Set up custom method names.
+      #
+      # @param base [Class, Module] the target class/module
+      # @param options [Hash] method name customization options
+      # @return [void]
+      # @rbs (untyped base, ?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> void
+      def inject_custom_methods!(base, **options)
+        options.each do |original, custom|
+          base.singleton_class.alias_method(custom, original) unless custom.nil?
+          if (custom.nil? || custom != original) && base.respond_to?(original)
+            base.singleton_class.undef_method(original)
+          end
+        end
+      end
+    end
+  end
+
+  # Create a customized Attributer module.
+  #
+  # Provides a convenient way to include Attributer with customized method names.
+  #
+  # @example
+  #   class Person
+  #     include Domainic.Attributer(argument: :param, option: :opt)
+  #   end
+  #
+  # @param options [Hash] method name customization options
+  # @return [Module] configured Attributer module
+  # @rbs (?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> Module
+  def self.Attributer(**options) # rubocop:disable Naming/MethodName
+    Domainic::Attributer.call(**options)
+  end
+end

data/lib/domainic-attributer.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer'