musa-dsl 0.41.0 → 0.42.0

data/lib/musa-dsl/series/base-series.rb

@@ -187,251 +187,55 @@ module Musa
 
     include Constructors
 
-    # Serie module factory providing configurable serie modules.
+    # Serie mixins for building serie implementations.
     #
-    # Creates modules dynamically based on requirements:
+    # Provides composable modules for serie classes:
     #
-    # - **Serie.base**: Minimal module without dependencies
-    # - **Serie.with**: Configured module with source/sources/block
+    # - {Base} - Core functionality without dependencies
+    # - {WithSource} - Single upstream serie dependency
+    # - {WithSources} - Multiple upstream serie dependencies
+    # - {WithBlock} - Simple proc storage
+    # - {WithSmartBlock} - SmartProcBinder-wrapped proc
     #
-    # ## Factory Pattern
-    #
-    # Serie.with generates modules at runtime with specific features:
+    # ## Usage Pattern
     #
     # ```ruby
-    # # Generate module with source support
-    # include Serie.with(source: true, source_as: :upstream)
+    # class MySerie
+    #   include Serie::Base
+    #   include Serie::WithSource
     #
-    # # Now has @source, #upstream, #upstream= methods
-    # ```
+    #   def initialize(source)
+    #     self.source = source
+    #     init
+    #     mark_as_prototype!
+    #   end
     #
-    # ## Configuration Options
+    #   private def _next_value
+    #     @source.next_value&.transform
+    #   end
+    # end
+    # ```
     #
-    # - **source**: Single upstream serie dependency
-    # - **sources**: Multiple upstream serie dependencies
-    # - **block**: Block/proc attribute
-    # - **smart_block**: SmartProcBinder-wrapped block
+    # ## Custom Accessor Names
     #
-    # ## Musical Applications
+    # Use `alias` to create custom accessor names:
     #
-    # Used internally by serie implementations to declare dependencies
-    # and automatically handle prototype/instance propagation.
+    # ```ruby
+    # class MySerie
+    #   include Serie::Base
+    #   include Serie::WithSource
+    #   alias upstream source
+    #   alias upstream= source=
+    # end
+    # ```
     #
-    # @see SerieImplementation Core serie protocol
+    # @see Base Core serie module
+    # @see WithSource Single source dependency
+    # @see WithSources Multiple sources dependency
+    # @see WithBlock Simple proc storage
+    # @see WithSmartBlock SmartProcBinder-wrapped proc
     # @see Prototyping Prototype/instance state management
-    #
-    # @api private
     module Serie
-      # Creates base serie module without dependencies.
-      #
-      # Minimal module for series that generate values without upstream
-      # sources (e.g., array-backed series, value generators).
-      #
-      # @return [Module] base module with SerieImplementation
-      #
-      # @example Base serie
-      #   class SimpleSerie
-      #     include Serie.base
-      #
-      #     def _next_value
-      #       # Generate value
-      #     end
-      #   end
-      #
-      # @api private
-      def self.base
-        Module.new do
-          include SerieImplementation
-
-          def has_source; false; end
-          private def mandatory_source; false; end
-
-          def has_sources; false; end
-          private def mandatory_sources; false; end
-        end
-      end
-
-      # Creates configurable serie module with specified features.
-      #
-      # Factory method generating modules with:
-      #
-      # - Single source dependency (source: true)
-      # - Multiple sources dependency (sources: true)
-      # - Block attribute (block: true, smart_block: true)
-      #
-      # ## Source Support
-      #
-      # **source: true** adds:
-      #
-      # - `@source` instance variable
-      # - `#source` getter (or custom name via source_as:)
-      # - `#source=` setter with state validation
-      # - Automatic prototype/instance propagation
-      #
-      # ## Sources Support
-      #
-      # **sources: true** adds:
-      #
-      # - `@sources` instance variable (Hash or Array)
-      # - `#sources` getter/setter
-      # - Automatic state resolution from all sources
-      #
-      # ## Block Support
-      #
-      # **block: true** - Simple proc attribute
-      # **smart_block: true** - SmartProcBinder-wrapped block
-      #
-      # ## State Propagation
-      #
-      # Sources automatically propagate state:
-      #
-      # - Setting source to :prototype → marks self as :prototype
-      # - Setting source to :instance → marks self as :instance
-      # - Cloning propagates through source/sources
-      #
-      # @param source [Boolean] add single source dependency
-      # @param source_as [Symbol, nil] custom name for source attribute
-      # @param private_source [Boolean, nil] make source methods private
-      # @param mandatory_source [Boolean, nil] require source to be set
-      # @param sources [Boolean] add multiple sources dependency
-      # @param sources_as [Symbol, nil] custom name for sources attribute
-      # @param private_sources [Boolean, nil] make sources methods private
-      # @param mandatory_sources [Boolean, nil] require sources to be set
-      # @param smart_block [Boolean] add SmartProcBinder block support
-      # @param block [Boolean] add simple block support
-      # @param block_as [Symbol, nil] custom name for block attribute
-      #
-      # @return [Module] configured module with SerieImplementation
-      #
-      # @example Serie with single source
-      #   class ReverseSerie
-      #     include Serie.with(source: true)
-      #
-      #     def _next_value
-      #       # Process source.next_value
-      #     end
-      #   end
-      #
-      # @example Serie with block
-      #   class MapSerie
-      #     include Serie.with(source: true, smart_block: true)
-      #
-      #     def _next_value
-      #       value = source.next_value
-      #       value ? @block.call(value) : nil
-      #     end
-      #   end
-      #
-      # @api private
-      def self.with(source: false,
-                    source_as: nil,
-                    private_source: nil,
-                    mandatory_source: nil,
-                    sources: false,
-                    sources_as: nil,
-                    private_sources: nil,
-                    mandatory_sources: nil,
-                    smart_block: false,
-                    block: false,
-                    block_as: nil)
-
-        source_as ||= :source
-        source_setter = (source_as.to_s + '=').to_sym
-        _mandatory_source = source if mandatory_source.nil?
-
-        sources_as ||= :sources
-        sources_setter = (sources_as.to_s + '=').to_sym
-        _mandatory_sources = sources if mandatory_sources.nil?
-
-        block_as ||= :proc
-        block_setter = (block_as.to_s + '=').to_sym
-
-        Module.new do
-          include SerieImplementation
-
-          if source
-            private def has_source; true; end
-            define_method(:mandatory_source) { _mandatory_source }
-            private :mandatory_source
-
-            define_method source_as do
-              @source
-            end
-
-            define_method source_setter do |serie|
-              unless @source.nil? || @source.undefined? || serie.state == @source.state
-                raise ArgumentError, "New serie for #{source_as} should be a #{@state} instead of a #{serie.state}"
-              end
-
-              @source = serie
-              mark_regarding! @source
-            end
-
-            if private_source
-              private source_as
-              private source_setter
-            end
-          else
-            private def has_source; false; end
-            private def mandatory_source; false; end
-          end
-
-          if sources
-            private def has_sources; true; end
-            define_method(:mandatory_sources) { _mandatory_sources }
-            private :mandatory_source
-
-            define_method sources_as do
-              @sources
-            end
-
-            define_method sources_setter do |series|
-              unless series.is_a?(Hash) || series.is_a?(Array)
-                raise ArgumentError, "New series for #{sources_as} should be a Hash or an Array instead of a #{series.class.name}"
-              end
-
-              @sources = series
-              try_to_resolve_undefined_state_if_needed
-            end
-
-            if private_sources
-              private sources_as
-              private sources_setter
-            end
-          else
-            private def has_sources; false; end
-            private def mandatory_sources; false; end
-          end
-
-          if smart_block
-            define_method block_as do |&block|
-              if block
-                @block = Extension::SmartProcBinder::SmartProcBinder.new(block)
-              else
-                @block.proc
-              end
-            end
-
-            define_method block_setter do |block|
-              @block = Extension::SmartProcBinder::SmartProcBinder.new(block)
-            end
-
-          elsif block
-            define_method block_as do |&block|
-              if block
-                @block = block
-              else
-                @block
-              end
-            end
-
-            define_method block_setter do |block|
-              @block = block
-            end
-          end
-        end
-      end
-
       # Prototype/instance state management for Series.
       #
       # Implements the prototype/instance pattern enabling reusable serie
@@ -651,14 +455,14 @@ module Musa
 
         # Converts serie and dependencies to prototype state.
         #
-        # Called automatically during cloning. By default, handles @source and
-        # @sources attributes automatically. Subclasses can override to add
+        # Called automatically during cloning. By default, handles +@source+ and
+        # +@sources+ attributes automatically. Subclasses can override to add
         # custom prototyping logic.
         #
         # ## Default Behavior
         #
-        # - Calls `.prototype` on @source if present
-        # - Calls `.prototype` on all @sources elements (Array or Hash)
+        # - Calls +.prototype+ on +@source+ if present
+        # - Calls +.prototype+ on all +@sources+ elements (Array or Hash)
         #
         # @return [void]
         #
@@ -677,13 +481,13 @@ module Musa
         # Converts serie and dependencies to instance state.
         #
         # Called automatically during instance creation. By default, handles
-        # @source and @sources attributes automatically. Subclasses can
+        # +@source+ and +@sources+ attributes automatically. Subclasses can
         # override to add custom instancing logic.
         #
         # ## Default Behavior
         #
-        # - Calls `.instance` on @source if present
-        # - Calls `.instance` on all @sources elements (Array or Hash)
+        # - Calls +.instance+ on +@source+ if present
+        # - Calls +.instance+ on all +@sources+ elements (Array or Hash)
         #
         # @return [void]
         #
@@ -801,7 +605,7 @@ module Musa
         # Attempts to resolve undefined state from sources.
         #
         # Called automatically before state queries. Resolves state based on
-        # @source and @sources dependencies:
+        # +@source+ and +@sources+ dependencies:
         #
         # - All sources :prototype → :prototype
         # - All sources :instance → :instance
@@ -1314,6 +1118,212 @@ module Musa
       end
 
       private_constant :SerieImplementation
+
+      # Base module for all Serie implementations.
+      #
+      # Provides the core Serie functionality without source or block support.
+      # Include this module in classes that don't need source dependencies.
+      #
+      # @example Basic usage
+      #   class MySerie
+      #     include Serie::Base
+      #
+      #     def initialize
+      #       init
+      #       mark_as_prototype!
+      #     end
+      #
+      #     private def _next_value
+      #       # implementation
+      #     end
+      #   end
+      #
+      # @see WithSource For series with single source dependency
+      # @see WithSources For series with multiple source dependencies
+      module Base
+        include SerieImplementation
+
+        private def has_source; false; end
+        private def mandatory_source; false; end
+        private def has_sources; false; end
+        private def mandatory_sources; false; end
+      end
+
+      # Mixin for series with single source dependency.
+      #
+      # Provides `source` and `source=` accessors for series that depend on
+      # one upstream source serie.
+      #
+      # @example Usage
+      #   class ProcessorSerie
+      #     include Serie::Base
+      #     include Serie::WithSource
+      #
+      #     def initialize(source)
+      #       self.source = source
+      #       init
+      #     end
+      #   end
+      #
+      # @example Custom accessor name using alias
+      #   class MyCustomSerie
+      #     include Serie::Base
+      #     include Serie::WithSource
+      #     alias my_source source
+      #     alias my_source= source=
+      #   end
+      #
+      # @see WithSources For multiple source dependencies
+      module WithSource
+        private def has_source; true; end
+        private def mandatory_source; true; end
+
+        # @return [Serie, nil] the upstream source serie
+        def source
+          @source
+        end
+
+        # Sets the source serie.
+        #
+        # @param serie [Serie] source serie (must match current state)
+        # @raise [ArgumentError] if state mismatch between source and this serie
+        def source=(serie)
+          unless @source.nil? || @source.undefined? || serie.state == @source.state
+            raise ArgumentError, "New serie for source should be a #{@state} instead of a #{serie.state}"
+          end
+          @source = serie
+          mark_regarding! @source
+        end
+      end
+
+      # Mixin for series with multiple source dependencies.
+      #
+      # Provides `sources` and `sources=` accessors for series that depend on
+      # multiple upstream series (as Array or Hash).
+      #
+      # @example Usage with Array
+      #   class MergeSerie
+      #     include Serie::Base
+      #     include Serie::WithSources
+      #
+      #     def initialize(*series)
+      #       self.sources = series
+      #       init
+      #     end
+      #   end
+      #
+      # @example Usage with Hash
+      #   class NamedSourcesSerie
+      #     include Serie::Base
+      #     include Serie::WithSources
+      #
+      #     def initialize(melody:, rhythm:)
+      #       self.sources = { melody: melody, rhythm: rhythm }
+      #       init
+      #     end
+      #   end
+      #
+      # @see WithSource For single source dependency
+      module WithSources
+        private def has_sources; true; end
+        private def mandatory_sources; true; end
+
+        # @return [Array<Serie>, Hash{Symbol => Serie}, nil] upstream source series
+        def sources
+          @sources
+        end
+
+        # Sets the sources series.
+        #
+        # @param series [Array<Serie>, Hash{Symbol => Serie}] source series
+        # @raise [ArgumentError] if series is not a Hash or Array
+        def sources=(series)
+          unless series.is_a?(Hash) || series.is_a?(Array)
+            raise ArgumentError, "New series for sources should be a Hash or an Array instead of a #{series.class.name}"
+          end
+          @sources = series
+          send(:try_to_resolve_undefined_state_if_needed)
+        end
+      end
+
+      # Mixin for series with block/proc attribute (simple version).
+      #
+      # Provides `proc` accessor for series that use a Proc directly
+      # without SmartProcBinder wrapping.
+      #
+      # @example Usage
+      #   class MapperSerie
+      #     include Serie::Base
+      #     include Serie::WithBlock
+      #
+      #     def initialize(&block)
+      #       self.proc = block
+      #       init
+      #     end
+      #   end
+      #
+      # @see WithSmartBlock For SmartProcBinder-wrapped blocks
+      module WithBlock
+        # Gets or sets the proc.
+        #
+        # @overload proc
+        #   @return [Proc, nil] the stored proc
+        # @overload proc(&block)
+        #   @param block [Proc] block to store
+        #   @return [Proc] the stored block
+        def proc(&block)
+          block ? (@block = block) : @block
+        end
+
+        # Sets the proc directly.
+        #
+        # @param block [Proc] block to store
+        def proc=(block)
+          @block = block
+        end
+      end
+
+      # Mixin for series with SmartProcBinder-wrapped block attribute.
+      #
+      # Similar to {WithBlock} but wraps procs in SmartProcBinder for
+      # flexible parameter binding.
+      #
+      # @example Usage
+      #   class SmartMapperSerie
+      #     include Serie::Base
+      #     include Serie::WithSmartBlock
+      #
+      #     def initialize(&block)
+      #       self.proc = block
+      #       init
+      #     end
+      #   end
+      #
+      # @see WithBlock For simple proc storage without wrapping
+      # @see Extension::SmartProcBinder::SmartProcBinder
+      module WithSmartBlock
+        # Gets or sets the proc with SmartProcBinder wrapping.
+        #
+        # @overload proc
+        #   @return [Proc, nil] the underlying proc (unwrapped)
+        # @overload proc(&block)
+        #   @param block [Proc] block to wrap and store
+        #   @return [Extension::SmartProcBinder::SmartProcBinder] the wrapped binder
+        def proc(&block)
+          if block
+            @block = Extension::SmartProcBinder::SmartProcBinder.new(block)
+          else
+            @block&.proc
+          end
+        end
+
+        # Sets the proc with SmartProcBinder wrapping.
+        #
+        # @param block [Proc] block to wrap and store
+        def proc=(block)
+          @block = Extension::SmartProcBinder::SmartProcBinder.new(block)
+        end
+      end
     end
   end
 end

data/lib/musa-dsl/series/buffer-serie.rb

@@ -57,7 +57,8 @@ module Musa
     end
 
     class SyncBufferSerie
-      include Series::Serie.with(source: true)
+      include Series::Serie::Base
+      include Series::Serie::WithSource
 
       def initialize(serie)
         self.source = serie
@@ -97,7 +98,7 @@ module Musa
       end
 
       class Buffer
-        include Series::Serie.base
+        include Series::Serie::Base
 
         def initialize(history)
           @history = history
@@ -145,7 +146,8 @@ module Musa
       # modo fill_on_restart: cuando una serie hace restart, las demás no se ven afectadas porque siguen recibiendo
       # todos los elementos de la serie original
 
-      include Series::Serie.with(source: true)
+      include Series::Serie::Base
+      include Series::Serie::WithSource
 
       def initialize(serie)
         self.source = serie
@@ -243,10 +245,13 @@ module Musa
       end
 
       class Buffer
-        include Series::Serie.with(source: true, private_source: true)
+        include Series::Serie::Base
+        include Series::Serie::WithSource
+
+        private :source, :source=
 
         def initialize(base)
-          self.source = base
+          send(:source=, base)
           init
         end
 

data/lib/musa-dsl/series/hash-or-array-serie-splitter.rb

@@ -47,7 +47,8 @@ module Musa
     end
 
     class Splitter
-      include Series::Serie.with(source: true)
+      include Series::Serie::Base
+      include Series::Serie::WithSource
       include Enumerable
 
       private def has_source; true; end
@@ -74,7 +75,7 @@ module Musa
       # @param key_or_index [Symbol, Integer] hash key or array index
       #
       # @return [Split] component serie
-      def [](key_or_index)
+      def get(key_or_index)
         raise "Can't get a component because Splitter is a prototype. To get a component you need a Splitter instance." unless instance?
 
         if @series.key?(key_or_index)
@@ -84,6 +85,8 @@ module Musa
         end
       end
 
+      alias_method :[], :get
+
       # Iterates over component series.
       #
       # @yield [key, split] for hash mode, [split] for array mode
@@ -233,7 +236,7 @@ module Musa
       private_constant :SplitterProxy
 
       class Split
-        include Series::Serie.base
+        include Series::Serie::Base
 
         def initialize(proxy, key_or_index)
           @proxy = proxy