musa-dsl 0.42.1 → 0.42.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 613cf84af52f6eb5dcfd399b94417f1e175242f32f8dc7cb2ab6452ebb58e9d0
-  data.tar.gz: 2a19dc6002ab89ae77f973d8a4405de380e73230bbd3f986d240071f654d505d
+  metadata.gz: 12fab469b50ab2d8c92ce166859645d8c30ad655e2ae339aa9b8c0254cc59253
+  data.tar.gz: 87aa5596a08c21f0b17ed7f6758b708a3473f9e8078020b7cf564b2149f6823a
 SHA512:
-  metadata.gz: e61a579a8c116af3e420ec7c98756734a7b00252981a8b42a2fe8472fd18bea679793fa879ab2dc1e279558472b55ba55bcdd7d1cab5889bf39af204db3b461f
-  data.tar.gz: b1678d001558905ed9939580849e48e8ef5a79c3d3131959e46f0d2c4505c77b1030c91bc6c156cc650b1e42bd1b7d32d978bc730fb14e576b8b29a0e0b552d5
+  metadata.gz: 38b45b016289a63870ada189d4ea91f9749754997ad4e250b5d24b1ea47c001741696e71eef8ce13dfeb4e6753caf213f970861fbbff2edbcee8f18504a9e03e
+  data.tar.gz: 6a14e6306e5f3945fa5e5febfa223fd1aece1cbff1d0ed8533a5a54231646bfddf96489a572d8aae1adbeb6b0dbbaee1f3aa1ef9effa8095c051378b145bde9a

data/docs/subsystems/sequencer.md

@@ -102,6 +102,71 @@ every 1/4r do ... end
 at 0.5 do ... end
 ```
 
+## Control Callbacks: `on_stop` vs `after`
+
+The control objects returned by `every`, `play`, `play_timed`, and `move` support two types of callbacks with different semantics:
+
+- **`on_stop`**: Cleanup callback — fires **always** when the control terminates, whether naturally or via manual `.stop`. Use for resource cleanup, state updates, logging.
+- **`after`**: Continuation callback — fires **only on natural termination** (duration reached, series exhausted, till exceeded, condition failed). **NOT** called when `.stop` is used. Use for chaining sections, scheduling follow-up events.
+
+| Termination cause | `on_stop` fires? | `after` fires? |
+|---|---|---|
+| Manual `.stop` | Yes | **No** |
+| Duration reached | Yes | Yes |
+| Till position exceeded | Yes | Yes |
+| Condition failed | Yes | Yes |
+| Series exhausted (play) | Yes | Yes |
+| Nil interval (every, one-shot) | Yes | Yes |
+
+### Examples
+
+```ruby
+# Safe section chaining — .stop won't cause relaunch
+ctrl = every 1r do
+  # ... play pattern ...
+end
+
+ctrl.on_stop { puts "Pattern stopped (any reason)" }
+ctrl.after { launch :next_section }  # Only on natural end
+
+# Later: manual stop does NOT trigger :next_section
+ctrl.stop
+```
+
+```ruby
+# Play with on_stop for cleanup
+ctrl = play melody do |note:, duration:|
+  voice.note(note, duration: duration)
+end
+
+ctrl.on_stop { voice.all_notes_off }  # Always cleanup
+ctrl.after { launch :next_phrase }     # Only if melody finishes naturally
+```
+
+```ruby
+# Move with after for continuation
+ctrl = move from: 0, to: 127, duration: 4r, every: 1/4r do |v|
+  midi_cc(7, v.round)
+end
+
+ctrl.on_stop { puts "Fade ended" }     # Any reason
+ctrl.after { launch :next_section }     # Only if fade completes
+```
+
+### Parameter form
+
+`on_stop` and `after` can also be passed as parameters:
+
+```ruby
+every 1r, on_stop: proc { cleanup }, after: proc { continue } do
+  # ...
+end
+
+play melody, on_stop: proc { cleanup } do |note:|
+  # ...
+end
+```
+
 ## API Reference
 
 **Complete API documentation:**

data/lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb

@@ -48,9 +48,10 @@ module Musa::Sequencer
         if control.stopped? || duration_exceeded || till_exceeded || condition_failed || interval.nil?
           control.do_on_stop.each(&:call)
 
-          control.do_after.each do |do_after|
-            # _numeric_at position + (interval || 0) + do_after[:bars], control, &do_after[:block]
-            _numeric_at position + do_after[:bars], control, &do_after[:block]
+          unless control.stopped?
+            control.do_after.each do |do_after|
+              _numeric_at position + do_after[:bars], control, &do_after[:block]
+            end
           end
         else
           _numeric_at control._start_position + control._execution_counter * interval, control do
@@ -77,8 +78,8 @@ module Musa::Sequencer
     #
     # ## Callbacks
     #
-    # - **on_stop**: Called when loop stops (any reason)
-    # - **after**: Called after loop stops, with optional delay in bars
+    # - **on_stop**: Called when loop stops (any reason, including manual stop)
+    # - **after**: Called only on natural termination (duration/till/condition/nil-interval), NOT on manual stop
     #
     # ## Execution Tracking
     #
@@ -169,7 +170,7 @@ module Musa::Sequencer
         @condition_block = block
       end
 
-      # Registers callback for when loop stops.
+      # Registers callback for when loop stops (any reason, including manual stop).
       #
       # @yield stop callback block
       #
@@ -180,9 +181,10 @@ module Musa::Sequencer
         @do_on_stop << block
       end
 
-      # Registers callback to execute after loop stops.
+      # Registers callback to execute after loop terminates naturally.
+      # NOT called on manual stop (.stop).
       #
-      # @param bars [Numeric, nil] delay in bars after stop (default: 0)
+      # @param bars [Numeric, nil] delay in bars after natural termination (default: 0)
       # @yield after callback block
       #
       # @return [void]

data/lib/musa-dsl/sequencer/base-sequencer-implementation-move.rb

@@ -235,8 +235,10 @@ module Musa::Sequencer
                                 on_stop: on_stop, after_bars: after_bars, after: after)
 
       control.on_stop do
-        control.do_after.each do |do_after|
-          _numeric_at position + do_after[:bars], control, &do_after[:block]
+        unless control.manually_stopped?
+          control.do_after.each do |do_after|
+            _numeric_at position + do_after[:bars], control, &do_after[:block]
+          end
         end
       end
 
@@ -324,7 +326,7 @@ module Musa::Sequencer
             #
             # Do we need stop?
             #
-            control.stop if stop.all?
+            control.every_control.stop if stop.all?
 
             #
             # Calculate effective values and next_values applying the parameter function
@@ -527,6 +529,7 @@ module Musa::Sequencer
         super parent
 
         @every_control = EveryControl.new(self, duration: duration, till: till)
+        @manually_stopped = false
 
         @do_on_stop = []
         @do_after = []
@@ -540,7 +543,7 @@ module Musa::Sequencer
         end
       end
 
-      # Registers callback for when movement stops.
+      # Registers callback for when movement stops (any reason, including manual stop).
       #
       # @yield stop callback block
       #
@@ -550,9 +553,10 @@ module Musa::Sequencer
         @do_on_stop << block
       end
 
-      # Registers callback to execute after movement stops.
+      # Registers callback to execute after movement terminates naturally.
+      # NOT called on manual stop (.stop).
       #
-      # @param bars [Numeric, nil] delay in bars after stop (default: 0)
+      # @param bars [Numeric, nil] delay in bars after natural termination (default: 0)
       # @yield after callback block
       #
       # @return [void]
@@ -565,14 +569,26 @@ module Musa::Sequencer
         @do_after << { bars: bars.rationalize, block: block }
       end
 
-      # Stops movement.
+      # Stops movement manually.
+      #
+      # Sets manually_stopped flag before delegating to every_control.
+      # After callbacks will NOT fire on manual stop.
       #
       # @return [void]
       #
       def stop
+        @manually_stopped = true
         @every_control.stop
       end
 
+      # Checks if movement was stopped manually (via .stop).
+      #
+      # @return [Boolean] true if manually stopped
+      #
+      def manually_stopped?
+        @manually_stopped
+      end
+
       # Checks if movement is stopped.
       #
       # @return [Boolean] true if stopped

data/lib/musa-dsl/sequencer/base-sequencer-implementation-play-timed.rb

@@ -124,9 +124,12 @@ module Musa::Sequencer
           end
         end
       else
+        control.do_on_stop.each(&:call)
 
-        control.do_after.each do |do_after|
-          _numeric_at position + do_after[:bars], control, &do_after[:block]
+        unless control.stopped?
+          control.do_after.each do |do_after|
+            _numeric_at position + do_after[:bars], control, &do_after[:block]
+          end
         end
       end
     end
@@ -165,7 +168,7 @@ module Musa::Sequencer
         self.after after_bars, &after if after
       end
 
-      # Registers callback for when playback stops.
+      # Registers callback for when playback stops (any reason, including manual stop).
       #
       # @yield stop callback block
       #
@@ -176,9 +179,10 @@ module Musa::Sequencer
         @do_on_stop << block
       end
 
-      # Registers callback to execute after playback completes.
+      # Registers callback to execute after playback terminates naturally
+      # (series exhausted). NOT called on manual stop (.stop).
       #
-      # @param bars [Numeric, nil] delay in bars after completion (default: 0)
+      # @param bars [Numeric, nil] delay in bars after natural termination (default: 0)
       # @yield after callback block
       #
       # @return [void]

data/lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb

@@ -203,10 +203,14 @@ module Musa::Sequencer
           end
         end
       else
-        control2 = EventHandler.new control
+        control.do_on_stop.each(&:call)
 
-        control.do_after.each do |do_after|
-          _numeric_at position + do_after[:bars], control2, &do_after[:block]
+        unless control.stopped?
+          control2 = EventHandler.new control
+
+          control.do_after.each do |do_after|
+            _numeric_at position + do_after[:bars], control2, &do_after[:block]
+          end
         end
       end
 
@@ -252,21 +256,26 @@ module Musa::Sequencer
     #
     # @api private
     class PlayControl < EventHandler
-      # @return [Array<Hash>] after callbacks with delays
+      # @return [Array<Proc>] callbacks when play stops (any reason, including manual stop)
+      attr_reader :do_on_stop
+      # @return [Array<Hash>] after callbacks with delays (only on natural termination)
       attr_reader :do_after
 
-      # Creates play control with optional after callback.
+      # Creates play control with optional callbacks.
       #
       # @param parent [EventHandler] parent event handler
+      # @param on_stop [Proc, nil] stop callback (fires on any termination)
       # @param after_bars [Rational, nil] delay for after callback
-      # @param after [Proc, nil] after callback block
+      # @param after [Proc, nil] after callback block (fires only on natural termination)
       #
       # @api private
-      def initialize(parent, after_bars: nil, after: nil)
+      def initialize(parent, on_stop: nil, after_bars: nil, after: nil)
         super parent
 
+        @do_on_stop = []
         @do_after = []
 
+        @do_on_stop << on_stop if on_stop
         after(after_bars, &after) if after
       end
 
@@ -322,7 +331,19 @@ module Musa::Sequencer
         @continuation_sequencer&.continuation_play(@continuation_parameters)
       end
 
-      # Registers callback to execute after play completes.
+      # Registers callback for when play stops (any reason, including manual stop).
+      #
+      # @yield stop callback block
+      #
+      # @return [void]
+      #
+      # @api private
+      def on_stop(&block)
+        @do_on_stop << block
+      end
+
+      # Registers callback to execute after play completes naturally
+      # (series exhausted). Not called on manual stop.
       #
       # @param bars [Numeric, nil] delay in bars after completion (default: 0)
       # @yield after callback block

data/lib/musa-dsl/sequencer/base-sequencer-implementation.rb

@@ -39,19 +39,15 @@ module Musa::Sequencer
           command = queue.shift
           @timeslots.delete position_to_run if queue.empty?
 
-          if command.key?(:parent_control) && !command[:parent_control].stopped?
-            @event_handlers.push command[:parent_control]
-
-            @tick_mutex.synchronize do
-              command[:block]&.call *command[:value_parameters], **command[:key_parameters]
-            end
-
-            @event_handlers.pop
-          else
-            @tick_mutex.synchronize do
-              command[:block]&.call *command[:value_parameters], **command[:key_parameters]
-            end
+          push_parent = command.key?(:parent_control) && !command[:parent_control].stopped?
+
+          @event_handlers.push(command[:parent_control]) if push_parent
+
+          @tick_mutex.synchronize do
+            command[:block]&.call *command[:value_parameters], **command[:key_parameters]
           end
+
+          @event_handlers.pop if push_parent
         end
       end
 

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

@@ -622,8 +622,9 @@ module Musa
       # @param serie [Series] series to play
       # @param mode [Symbol] running mode (:at, :wait, :neumalang)
       # @param parameter [Symbol, nil] duration parameter name from serie values
-      # @param after_bars [Numeric, nil] schedule block after play finishes
-      # @param after [Proc, nil] block to execute after play finishes
+      # @param on_stop [Proc, nil] callback when play stops (any reason, including manual stop)
+      # @param after_bars [Numeric, nil] delay for after callback
+      # @param after [Proc, nil] callback after play completes naturally (NOT on manual stop)
       # @param context [Object, nil] context for neumalang processing
       # @param mode_args [Hash] additional mode-specific parameters
       # @yield [value] block executed for each serie value
@@ -666,6 +667,7 @@ module Musa
       def play(serie,
                mode: nil,
                parameter: nil,
+               on_stop: nil,
                after_bars: nil,
                after: nil,
                context: nil,
@@ -674,7 +676,7 @@ module Musa
 
         mode ||= :wait
 
-        control = PlayControl.new @event_handlers.last, after_bars: after_bars, after: after
+        control = PlayControl.new @event_handlers.last, on_stop: on_stop, after_bars: after_bars, after: after
         @event_handlers.push control
 
         _play serie.instance, control, context, mode: mode, parameter: parameter, **mode_args, &block
@@ -683,10 +685,10 @@ module Musa
 
         @playing << control
 
-        control.after do
+        control.on_stop do
           @playing.delete control
         end
-        
+
         control
       end
       
@@ -780,12 +782,6 @@ module Musa
         control = PlayTimedControl.new(@event_handlers.last,
                                        on_stop: on_stop, after_bars: after_bars, after: after)
 
-        control.on_stop do
-          control.do_after.each do |do_after|
-            _numeric_at position + do_after[:bars], control, &do_after[:block]
-          end
-        end
-
         @event_handlers.push control
 
         _play_timed(timed_serie.instance, at, control, &block)
@@ -794,7 +790,7 @@ module Musa
 
         @playing << control
 
-        control.after do
+        control.on_stop do
           @playing.delete control
         end
 
@@ -876,7 +872,7 @@ module Musa
 
         @everying << control
 
-        control.after do
+        control.on_stop do
           @everying.delete control
         end
 
@@ -1005,7 +1001,7 @@ module Musa
 
         @moving << control
 
-        control.after do
+        control.on_stop do
           @moving.delete control
         end
 

data/lib/musa-dsl/sequencer/sequencer-dsl.rb

@@ -641,9 +641,12 @@ module Musa
         # Wraps BaseSequencer#play, evaluating block in DSL context.
         #
         # @param value_parameters [Array] parameters (series, etc.)
-        # @param key_parameters [Hash] keyword parameters
+        # @param key_parameters [Hash] keyword parameters (on_stop:, after:, after_bars:, mode:, etc.)
         # @yield block to execute for each element
         # @return [PlayControl] control object
+        #
+        # @see BaseSequencer#play for full parameter documentation
+        # @note on_stop: fires on any termination; after: fires only on natural termination (NOT on manual .stop)
         def play(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -657,9 +660,12 @@ module Musa
         # Wraps BaseSequencer#play_timed, evaluating block in DSL context.
         #
         # @param value_parameters [Array] parameters (timed series, etc.)
-        # @param key_parameters [Hash] keyword parameters
+        # @param key_parameters [Hash] keyword parameters (on_stop:, after:, after_bars:, at:)
         # @yield block to execute for each element
         # @return [PlayTimedControl] control object
+        #
+        # @see BaseSequencer#play_timed for full parameter documentation
+        # @note on_stop: fires on any termination; after: fires only on natural termination (NOT on manual .stop)
         def play_timed(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -674,9 +680,12 @@ module Musa
         # Uses SmartProcBinder to apply parameters before with.
         #
         # @param value_parameters [Array] parameters (interval, etc.)
-        # @param key_parameters [Hash] keyword parameters
+        # @param key_parameters [Hash] keyword parameters (duration:, till:, condition:, on_stop:, after:, after_bars:)
         # @yield block to execute each iteration
         # @return [EveryControl] control object
+        #
+        # @see BaseSequencer#every for full parameter documentation
+        # @note on_stop: fires on any termination; after: fires only on natural termination (NOT on manual .stop)
         def every(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -691,9 +700,12 @@ module Musa
         # Wraps BaseSequencer#move, evaluating block in DSL context.
         #
         # @param value_parameters [Array] parameters (from, to, etc.)
-        # @param key_parameters [Hash] keyword parameters
+        # @param key_parameters [Hash] keyword parameters (every:, from:, to:, step:, duration:, till:, on_stop:, after:, after_bars:, etc.)
         # @yield block to execute each iteration with current value
         # @return [MoveControl] control object
+        #
+        # @see BaseSequencer#move for full parameter documentation
+        # @note on_stop: fires on any termination; after: fires only on natural termination (NOT on manual .stop)
         def move(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 

data/lib/musa-dsl/version.rb

@@ -1,3 +1,3 @@
 module Musa
-  VERSION = '0.42.1'.freeze
+  VERSION = '0.42.2'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: musa-dsl
 version: !ruby/object:Gem::Version
-  version: 0.42.1
+  version: 0.42.2
 platform: ruby
 authors:
 - Javier Sánchez Yeste