musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/core-ext/deep-copy.rb

@@ -1,12 +1,64 @@
-# Based on https://github.com/adamluzsi/duplicate.rb/blob/master/lib/duplicate.rb
-# Modifications by Javier Sánchez Yeste
+require_relative 'extension'
 
 module Musa
   module Extension
+    # Module providing deep copy functionality for complex object graphs.
+    #
+    # DeepCopy implements recursive copying of objects, handling circular references,
+    # instance variables, singleton class modules, and various Ruby data structures.
+    #
+    # ## Features
+    #
+    # - Handles circular references via object registry
+    # - Preserves singleton class modules (dataset extensions)
+    # - Supports both :dup and :clone methods
+    # - Special handling for Arrays, Hashes, Ranges, Structs, Procs
+    # - Recursively copies instance variables
+    # - Optional freeze control for :clone method
+    #
+    # ## Use Cases
+    #
+    # - Deep copying musical event structures with complex nesting
+    # - Duplicating series configurations without shared state
+    # - Preserving dataset module extensions during copy operations
+    # - Safe duplication of mutable default values
+    #
+    # @example Basic deep copy
+    #   using Musa::Extension::DeepCopy
+    #
+    #   original = { items: [1, 2, 3] }
+    #   copy = original.dup(deep: true)
+    #   copy[:items] << 4
+    #   original[:items]  # => [1, 2, 3] (unchanged)
+    #
+    # @example Preserving modules
+    #   event = { pitch: 60 }.extend(Musa::Datasets::AbsI)
+    #   copy = event.dup(deep: true)
+    #   copy.is_a?(Musa::Datasets::AbsI)  # => true
+    #
+    # @see Arrayfy Uses deep_copy for preserving modules
+    # @see Hashify Uses deep_copy for preserving modules
+    #
+    # Based on https://github.com/adamluzsi/duplicate.rb/blob/master/lib/duplicate.rb
+    #
+    # Modifications by Javier Sánchez Yeste
     module DeepCopy
+      # Main deep copy module providing class methods.
       module DeepCopy
         extend self
 
+        # Creates a deep copy of an object, recursively copying nested structures.
+        #
+        # Uses an object registry to handle circular references, ensuring each
+        # object is copied only once and all references point to the same copy.
+        #
+        # @param object [Object] object to copy.
+        # @param method [Symbol] :dup or :clone.
+        # @param freeze [Boolean, nil] for :clone, whether to freeze the copy.
+        #
+        # @return [Object] deep copy of the object.
+        #
+        # @raise [ArgumentError] if method is not :dup or :clone.
         def deep_copy(object, method: :dup, freeze: nil)
           raise ArgumentError, "deep_copy method can only be :dup or :clone" unless method == :dup || method == :clone
           register = {}
@@ -14,6 +66,22 @@ module Musa
           _deep_copy(register, object, method, freeze)
         end
 
+        # Copies singleton class modules from source to target.
+        #
+        # This is essential for preserving dataset extensions (P, V, AbsI, etc.)
+        # when copying musical data structures. Without this, copied objects
+        # would lose their dataset behaviors.
+        #
+        # @param source [Object] object whose singleton modules to copy.
+        # @param target [Object] object to receive the modules.
+        #
+        # @return [Object] target with modules applied.
+        #
+        # @example
+        #   source = [60, 100].extend(Musa::Datasets::V)
+        #   target = [60, 100]
+        #   DeepCopy.copy_singleton_class_modules(source, target)
+        #   target.is_a?(Musa::Datasets::V)  # => true
         def copy_singleton_class_modules(source, target)
           source.singleton_class.included_modules.each do |m|
             target.extend m unless target.is_a?(m)
@@ -24,6 +92,8 @@ module Musa
 
         protected
 
+        # Retrieves a previously registered copy from the registry.
+        # @api private
         def registered(object, register)
           register[object.__id__]
         end
@@ -173,6 +243,59 @@ module Musa
         end
       end
 
+      # Refinement adding deep copy support to Object#dup and Object#clone.
+      #
+      # Adds a `deep:` keyword parameter to both methods, enabling easy deep copying
+      # without explicit calls to DeepCopy.deep_copy.
+      #
+      # ## Methods Added
+      #
+      # ### Object
+      # - {Object#dup} - Enhanced dup with optional deep copy
+      # - {Object#clone} - Enhanced clone with optional deep copy
+      #
+      # @!method dup(deep: false)
+      #   Enhanced dup with optional deep copy.
+      #
+      #   @note This method is added to Object via refinement. Requires `using Musa::Extension::DeepCopy`.
+      #
+      #   @param deep [Boolean] if true, performs deep copy; if false, standard dup.
+      #
+      #   @return [Object] duplicated object (shallow or deep).
+      #
+      #   @example Shallow dup (default)
+      #     using Musa::Extension::DeepCopy
+      #     arr = [[1, 2]]
+      #     copy = arr.dup
+      #     copy[0] << 3
+      #     arr  # => [[1, 2, 3]] (inner array shared)
+      #
+      #   @example Deep dup
+      #     using Musa::Extension::DeepCopy
+      #     arr = [[1, 2]]
+      #     copy = arr.dup(deep: true)
+      #     copy[0] << 3
+      #     arr  # => [[1, 2]] (inner array independent)
+      class ::Object; end
+
+      # @!method clone(freeze: nil, deep: false)
+      #   Enhanced clone with optional deep copy.
+      #
+      #   @note This method is added to Object via refinement. Requires `using Musa::Extension::DeepCopy`.
+      #
+      #   @param freeze [Boolean, nil] whether to freeze the clone.
+      #   @param deep [Boolean] if true, performs deep copy; if false, standard clone.
+      #
+      #   @return [Object] cloned object (shallow or deep).
+      #
+      #   @example Deep clone with freeze control
+      #     using Musa::Extension::DeepCopy
+      #     hash = { nested: { value: 1 } }
+      #     copy = hash.clone(deep: true, freeze: true)
+      #     copy.frozen?  # => true
+      #     copy[:nested].frozen?  # => true (deep freeze)
+      class ::Object; end
+
       refine Object do
         def dup(deep: false)
           if deep

data/lib/musa-dsl/core-ext/dynamic-proxy.rb

@@ -1,7 +1,40 @@
+require_relative 'extension'
+
 module Musa
   module Extension
+    # Module providing dynamic proxy pattern implementation.
+    #
+    # DynamicProxy allows creating objects that forward all method calls to a
+    # receiver object, which can be set/changed dynamically. This is useful for
+    # lazy initialization, placeholder objects, and delegation patterns.
+    #
+    # ## Features
+    #
+    # - Transparent method forwarding via method_missing
+    # - Dynamic receiver assignment
+    # - Type checking delegation (is_a?, kind_of?, instance_of?)
+    # - Equality delegation (==, eql?)
+    # - Safe handling when receiver is nil
+    #
+    # @example Basic usage
+    #   proxy = Musa::Extension::DynamicProxy::DynamicProxy.new
+    #   proxy.receiver = "Hello"
+    #   proxy.upcase  # => "HELLO" (forwarded to String)
+    #
+    # @example Lazy initialization
+    #   proxy = DynamicProxy.new
+    #   # ... later ...
+    #   proxy.receiver = expensive_object
+    #   proxy.some_method  # Now forwards to expensive_object
     module DynamicProxy
+      # Mixin module providing dynamic proxy behavior.
+      #
+      # This module can be included in classes to add proxy capabilities.
+      # Requires an @receiver instance variable to be set.
       module DynamicProxyModule
+        # Forwards unknown methods to the receiver.
+        #
+        # @raise [NoMethodError] if @receiver is nil or doesn't respond to method.
         def method_missing(method_name, *args, **key_args, &block)
           raise NoMethodError, "Method '#{method_name}' is unknown because self is a DynamicProxy with undefined receiver" unless @receiver
 
@@ -12,52 +45,97 @@ module Musa
           end
         end
 
+        # Declares which methods the proxy responds to.
+        #
+        # @return [Boolean] true if receiver responds to method, false otherwise.
         def respond_to_missing?(method_name, include_private)
           @receiver&.respond_to?(method_name, include_private) || super
         end
 
+        # Checks if the proxy has a receiver assigned.
+        #
+        # @return [Boolean] true if @receiver is not nil.
         def has_receiver?
           !@receiver.nil?
         end
 
+        # Preserve original is_a? for internal use
         alias _is_a? is_a?
 
+        # Delegates is_a? check to receiver or uses original.
+        #
+        # @param klass [Class] class to check against.
+        # @return [Boolean] true if proxy or receiver is instance of klass.
         def is_a?(klass)
           _is_a?(klass) || @receiver&.is_a?(klass)
         end
 
+        # Preserve original kind_of? for internal use
         alias _kind_of? kind_of?
 
+        # Delegates kind_of? check to receiver or uses original.
+        #
+        # @param klass [Class] class to check against.
+        # @return [Boolean] true if proxy or receiver is kind of klass.
         def kind_of?(klass)
           _kind_of?(klass) || @receiver&.is_a?(klass)
         end
 
+        # Preserve original instance_of? for internal use
         alias _instance_of? instance_of?
 
+        # Delegates instance_of? check to receiver or uses original.
+        #
+        # @param klass [Class] class to check against.
+        # @return [Boolean] true if proxy or receiver is instance of klass.
         def instance_of?(klass)
           _instance_of?(klass) || @receiver&.instance_of?(klass)
         end
 
+        # Preserve original == for internal use
         alias _equalequal ==
 
+        # Delegates equality check to receiver or uses original.
+        #
+        # @param object [Object] object to compare with.
+        # @return [Boolean] true if proxy or receiver equals object.
         def ==(object)
           _equalequal(object) || @receiver&.==(object)
         end
 
+        # Preserve original eql? for internal use
         alias _eql? eql?
 
+        # Delegates eql? check to receiver or uses original.
+        #
+        # @param object [Object] object to compare with.
+        # @return [Boolean] true if proxy or receiver eql? object.
         def eql?(object)
           _eql?(object) || @receiver&.eql?(object)
         end
       end
 
+      # Concrete DynamicProxy class ready for instantiation.
+      #
+      # @example
+      #   proxy = DynamicProxy.new
+      #   proxy.receiver = [1, 2, 3]
+      #   proxy.size      # => 3
+      #   proxy.first     # => 1
+      #   proxy.is_a?(Array)  # => true
       class DynamicProxy
         include DynamicProxyModule
 
+        # Creates a new dynamic proxy.
+        #
+        # @param receiver [Object, nil] optional initial receiver object.
         def initialize(receiver = nil)
           @receiver = receiver
         end
 
+        # The object to which methods are delegated.
+        #
+        # @return [Object, nil] current receiver.
         attr_accessor :receiver
       end
     end

data/lib/musa-dsl/core-ext/extension.rb

@@ -0,0 +1,53 @@
+module Musa
+  # Namespace for core Ruby extensions and utilities used throughout Musa DSL.
+  #
+  # This module contains fundamental extensions and helper modules that enhance
+  # Ruby's capabilities for DSL construction and flexible block handling.
+  #
+  # ## Included Modules
+  #
+  # - {With} - Flexible DSL block execution with context switching
+  # - {SmartProcBinder::SmartProcBinder} - Intelligent parameter binding for Procs
+  # - {AttributeBuilder} - DSL-style attribute builder macros
+  # - {DynamicProxy::DynamicProxy} - Dynamic method proxying
+  #
+  # ## Purpose
+  #
+  # These extensions enable Musa DSL's characteristic features:
+  # - Builder pattern with flexible context switching
+  # - Method-style and block-style parameter passing
+  # - Dynamic method generation for DSL syntax
+  # - Intelligent parameter matching and binding
+  #
+  # ## Design Philosophy
+  #
+  # The extensions in this module prioritize:
+  # - **Flexibility**: Supporting multiple calling conventions
+  # - **Transparency**: Minimal interference with normal Ruby behavior
+  # - **Reusability**: General-purpose tools used across Musa DSL
+  #
+  # @example Using With for DSL blocks
+  #   class Builder
+  #     include Musa::Extension::With
+  #
+  #     def initialize(&block)
+  #       @items = []
+  #       with(&block) if block
+  #     end
+  #
+  #     def add(item)
+  #       @items << item
+  #     end
+  #   end
+  #
+  #   builder = Builder.new do
+  #     add :foo  # Executes in Builder's context
+  #   end
+  #
+  # @see With The core DSL block execution module
+  # @see SmartProcBinder Intelligent Proc parameter handling
+  # @see AttributeBuilder DSL attribute builder macros
+  # @see DynamicProxy Dynamic method proxying implementation
+  module Extension
+  end
+end

data/lib/musa-dsl/core-ext/hashify.rb

@@ -1,8 +1,98 @@
+require_relative 'extension'
 require_relative 'deep-copy'
 
 module Musa
   module Extension
+    # Refinement that converts objects, arrays, and hashes into hashes with specified keys.
+    #
+    # This refinement is crucial for normalizing parameters in the DSL, especially when
+    # dealing with musical events that can be specified in multiple formats (positional,
+    # hash-based, or mixed).
+    #
+    # ## Core Behavior
+    #
+    # - **Object**: Creates hash mapping all keys to the same value
+    # - **Array**: Maps keys to array elements in order (consuming array)
+    # - **Hash**: Filters and reorders according to specified keys
+    # - **Preserves singleton class modules** on hash results
+    #
+    # ## Use Cases
+    #
+    # - Converting positional parameters to named parameters
+    # - Normalizing mixed parameter formats in musical events
+    # - Extracting specific keys from larger hashes
+    # - Providing defaults for missing event attributes
+    #
+    # @example Basic object hashification
+    #   using Musa::Extension::Hashify
+    #
+    #   100.hashify(keys: [:velocity, :duration])
+    #   # => { velocity: 100, duration: 100 }
+    #
+    # @example Array to hash
+    #   using Musa::Extension::Hashify
+    #
+    #   [60, 100, 0.5].hashify(keys: [:pitch, :velocity, :duration])
+    #   # => { pitch: 60, velocity: 100, duration: 0.5 }
+    #
+    # @example Hash filtering and reordering
+    #   using Musa::Extension::Hashify
+    #
+    #   { pitch: 60, velocity: 100, channel: 0, duration: 1 }
+    #     .hashify(keys: [:pitch, :velocity])
+    #   # => { pitch: 60, velocity: 100 }
+    #
+    # @example With defaults
+    #   using Musa::Extension::Hashify
+    #
+    #   [60].hashify(keys: [:pitch, :velocity, :duration], default: nil)
+    #   # => { pitch: 60, velocity: nil, duration: nil }
+    #
+    # @example Musical event normalization
+    #   using Musa::Extension::Hashify
+    #
+    #   # User provides just a pitch
+    #   60.hashify(keys: [:pitch, :velocity], default: 64)
+    #   # => { pitch: 60, velocity: 64 }
+    #
+    #   # User provides array [pitch, velocity, duration]
+    #   [62, 90, 0.5].hashify(keys: [:pitch, :velocity, :duration])
+    #   # => { pitch: 62, velocity: 90, duration: 0.5 }
+    #
+    # @see Musa::Datasets Hash-based event structures
+    # @note This refinement must be activated with `using Musa::Extension::Hashify`
+    # @note Singleton class modules (dataset extensions) are preserved on hash results
+    #
+    # ## Methods Added
+    #
+    # ### Object
+    # - {Object#hashify} - Creates a hash mapping all specified keys to this object's value
+    #
+    # ### Array
+    # - {Array#hashify} - Maps array elements to hash keys in order, consuming the array
+    #
+    # ### Hash
+    # - {Hash#hashify} - Filters and reorders hash to include only specified keys, preserving modules
     module Hashify
+      # @!method hashify(keys:, default: nil)
+      #   Creates a hash mapping all specified keys to this object's value.
+      #
+      #   Useful for broadcasting a single value across multiple attributes.
+      #   Nil objects can be replaced with a default value.
+      #
+      #   @note This method is added to Object via refinement. Requires `using Musa::Extension::Hashify`.
+      #
+      #   @param keys [Array<Symbol>] keys for the resulting hash.
+      #   @param default [Object, nil] value to use if self is nil.
+      #
+      #   @return [Hash] hash with all keys mapped to self (or default if nil).
+      #
+      #   @example Single value to multiple keys
+      #     using Musa::Extension::Hashify
+      #     127.hashify(keys: [:velocity, :pressure])
+      #     # => { velocity: 127, pressure: 127 }
+      class ::Object; end
+
       refine Object do
         def hashify(keys:, default: nil)
           keys.collect do |key|
@@ -16,6 +106,36 @@ module Musa
         end
       end
 
+      # @!method hashify(keys:, default: nil)
+      #   Maps array elements to hash keys in order, consuming the array.
+      #
+      #   Elements are assigned to keys sequentially. If the array has fewer elements
+      #   than keys, remaining keys get nil (or default). The array is cloned before
+      #   consumption, so the original is unchanged.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Hashify`.
+      #
+      #   @param keys [Array<Symbol>] keys for the resulting hash (in order).
+      #   @param default [Object, nil] value for keys without corresponding array elements.
+      #
+      #   @return [Hash] hash with keys mapped to array elements in order.
+      #
+      #   @example Basic array mapping
+      #     using Musa::Extension::Hashify
+      #     [60, 100, 0.25].hashify(keys: [:pitch, :velocity, :duration])
+      #     # => { pitch: 60, velocity: 100, duration: 0.25 }
+      #
+      #   @example Fewer elements than keys
+      #     using Musa::Extension::Hashify
+      #     [60, 100].hashify(keys: [:pitch, :velocity, :duration], default: nil)
+      #     # => { pitch: 60, velocity: 100, duration: nil }
+      #
+      #   @example More elements than keys (extras ignored)
+      #     using Musa::Extension::Hashify
+      #     [60, 100, 0.5, :ignored].hashify(keys: [:pitch, :velocity])
+      #     # => { pitch: 60, velocity: 100 }
+      class ::Array; end
+
       refine Array do
         def hashify(keys:, default: nil)
           values = clone
@@ -23,10 +143,51 @@ module Musa
             value = values.shift
             [ key,
               value.nil? ? default : value ]
-          end.to_hash
+          end.to_h
         end
       end
 
+      # @!method hashify(keys:, default: nil)
+      #   Filters and reorders hash to include only specified keys, preserving modules.
+      #
+      #   Creates a new hash with only the requested keys, in the order specified.
+      #   Missing keys get nil (or default). Singleton class modules (like dataset
+      #   extensions) are copied to the result.
+      #
+      #   @note This method is added to Hash via refinement. Requires `using Musa::Extension::Hashify`.
+      #
+      #   @param keys [Array<Symbol>] keys to include in result (order matters).
+      #   @param default [Object, nil] value for keys not present in source hash.
+      #
+      #   @return [Hash] new hash with specified keys, preserving singleton modules.
+      #
+      #   @example Filtering keys
+      #     using Musa::Extension::Hashify
+      #     { pitch: 60, velocity: 100, channel: 0 }
+      #       .hashify(keys: [:pitch, :velocity])
+      #     # => { pitch: 60, velocity: 100 }
+      #
+      #   @example Reordering keys
+      #     using Musa::Extension::Hashify
+      #     { velocity: 100, pitch: 60 }
+      #       .hashify(keys: [:pitch, :velocity])
+      #     # => { pitch: 60, velocity: 100 }
+      #
+      #   @example Adding missing keys with default
+      #     using Musa::Extension::Hashify
+      #     { pitch: 60 }
+      #       .hashify(keys: [:pitch, :velocity], default: 80)
+      #     # => { pitch: 60, velocity: 80 }
+      #
+      #   @example Preserving dataset modules
+      #     using Musa::Extension::Hashify
+      #     event = { pitch: 60, velocity: 100 }.extend(Musa::Datasets::AbsI)
+      #     event.hashify(keys: [:pitch, :velocity])
+      #     # Result also extended with AbsI
+      #
+      #   @note Singleton class modules are preserved via DeepCopy.copy_singleton_class_modules
+      class ::Hash; end
+
       refine Hash do
         def hashify(keys:, default: nil)
           keys.collect do |key|