musa-dsl 0.30.2 → 0.40.0

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

@@ -2,36 +2,301 @@ require 'logger'
 require_relative '../core-ext/inspect-nice'
 
 module Musa
+  # Logging utilities for Musa DSL.
+  #
+  # Provides a specialized logger that integrates with the sequencer to display
+  # musical position information alongside standard log messages.
+  #
+  # ## Purpose
+  #
+  # When working with sequenced musical compositions, it's crucial to know at
+  # what point in musical time events occur. This logger automatically prepends
+  # the sequencer's current position (in bars) to each log entry, making
+  # debugging and monitoring much more intuitive.
+  #
+  # ## Integration with Sequencer
+  #
+  # The logger reads the sequencer's position at the moment each log message
+  # is generated. Since positions are typically Rational numbers representing
+  # bars (e.g., 4/4 = 1 bar), the InspectNice refinement ensures they display
+  # in a readable decimal format.
+  #
+  # ## Common Use Cases
+  #
+  # - Debugging sequencer timing issues
+  # - Monitoring MIDI output events with their musical timestamps
+  # - Tracking series evaluation progress
+  # - Logging voice state changes during playback
+  # - Performance analysis and timing verification
+  #
+  # @example Complete workflow
+  #   require 'musa-dsl'
+  #
+  #   # Setup
+  #   sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+  #   logger = Musa::Logger::Logger.new(sequencer: sequencer)
+  #   logger.level = Logger::INFO
+  #
+  #   # In your composition
+  #   sequencer.at 0 do
+  #     logger.info "Composition started"
+  #   end
+  #
+  #   sequencer.at 4 do
+  #     logger.info "First phrase complete"
+  #   end
+  #
+  #   sequencer.run
+  #
+  #   # Output:
+  #   #  0.000: [INFO] Composition started
+  #   #  4.000: [INFO] First phrase complete
+  #
+  # @see Musa::Logger::Logger
+  # @see Musa::Sequencer::Sequencer
+  # @see Musa::Extension::InspectNice
   module Logger
+    # Custom logger that displays sequencer position with log messages.
+    #
+    # This logger extends Ruby's standard Logger class to prepend the current
+    # sequencer position to each log message, making it easy to track events
+    # in musical time during composition and playback.
+    #
+    # ## Features
+    #
+    # - Automatic sequencer position formatting in log output
+    # - Configurable position precision (integer and decimal digits)
+    # - Conditional formatting (position only shown when sequencer is provided)
+    # - Uses InspectNice refinements for better Rational display
+    # - Defaults to STDERR output with WARN level
+    #
+    # ## Log Format
+    #
+    # The formatted log output follows this pattern:
+    #
+    #     [position]: [LEVEL] [progname] message
+    #
+    # Where:
+    #
+    # - `position` is the sequencer position (only if sequencer provided)
+    # - `LEVEL` is the severity level (omitted for DEBUG)
+    # - `progname` is the program/module name (optional)
+    # - `message` is the actual log message
+    #
+    # @example Basic usage without sequencer
+    #   require 'musa-dsl'
+    #
+    #   logger = Musa::Logger::Logger.new
+    #   logger.warn "Something happened"
+    #   # Output: [WARN] Something happened
+    #
+    # @example With sequencer integration
+    #   require 'musa-dsl'
+    #
+    #   sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+    #   logger = Musa::Logger::Logger.new(sequencer: sequencer)
+    #
+    #   sequencer.at 4.5r do
+    #     logger.info "Note played"
+    #   end
+    #
+    #   sequencer.run
+    #
+    #   # Output:  4.500: [INFO] Note played
+    #
+    # @example With custom position format
+    #   require 'musa-dsl'
+    #
+    #   sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+    #
+    #   # 5 integer digits, 2 decimal places
+    #   logger = Musa::Logger::Logger.new(
+    #     sequencer: sequencer,
+    #     position_format: 5.2
+    #   )
+    #   logger.level = Logger::DEBUG
+    #
+    #   # At position 123.456:
+    #   sequencer.at 123.456r do
+    #     logger.debug "Debugging info"
+    #   end
+    #
+    #   sequencer.run
+    #
+    #   # Output:  123.46: Debugging info
+    #
+    # @example With program name
+    #   require 'musa-dsl'
+    #
+    #   sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+    #   logger = Musa::Logger::Logger.new(sequencer: sequencer)
+    #   logger.level = Logger::INFO
+    #
+    #   sequencer.at 4.5r do
+    #     logger.info('MIDIVoice') { "Playing note 60" }
+    #   end
+    #
+    #   sequencer.run
+    #
+    #   # Output:  4.500: [INFO] [MIDIVoice] Playing note 60
+    #
+    # @example Real-world scenario with multiple components
+    #   require 'musa-dsl'
+    #
+    #   sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+    #   logger = Musa::Logger::Logger.new(sequencer: sequencer)
+    #   logger.level = Logger::DEBUG
+    #
+    #   # Different components log at different times
+    #   sequencer.at 0 do
+    #     logger.info('Transport') { "Starting playback" }
+    #   end
+    #
+    #   sequencer.at 1.5r do
+    #     logger.debug('Series') { "Evaluating next value" }
+    #   end
+    #
+    #   sequencer.at 2.25r do
+    #     logger.warn('MIDIVoice') { "Note overflow detected" }
+    #   end
+    #
+    #   sequencer.run
+    #
+    #   # Output:
+    #   #  0.000: [INFO] [Transport] Starting playback
+    #   #  1.500: [Series] Evaluating next value
+    #   #  2.250: [WARN] [MIDIVoice] Note overflow detected
+    #
+    # @example Changing log level dynamically
+    #   require 'musa-dsl'
+    #
+    #   sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+    #   logger = Musa::Logger::Logger.new(sequencer: sequencer)
+    #   logger.level = Logger::DEBUG  # Show all messages
+    #
+    #   # Later, reduce verbosity
+    #   logger.level = Logger::WARN  # Only warnings and errors
+    #
+    # @see Musa::Sequencer::Sequencer
+    # @see Musa::Extension::InspectNice
+    # @note The logger inherits all standard Ruby Logger methods (debug, info, warn, error, fatal).
+    # @note Position values are formatted as floating point for readability, even though
+    #   the sequencer internally uses Rational numbers.
     class Logger < ::Logger
       using Musa::Extension::InspectNice
 
+      # Creates a new logger with optional sequencer integration.
+      #
+      # @param sequencer [Musa::Sequencer::Sequencer, nil] sequencer whose position
+      #   will be displayed in log messages. When nil, position is not shown.
+      # @param position_format [Numeric, nil] format specification for position display.
+      #   The integer part specifies the number of digits before the decimal point,
+      #   and the decimal part (×10) specifies digits after the decimal point.
+      #   Defaults to 3.3 (3 integer digits, 3 decimal places).
+      #
+      # @example Position format examples
+      #   require 'musa-dsl'
+      #
+      #   sequencer = Musa::Sequencer::Sequencer.new(4, 24)
+      #
+      #   # Different formats for position display:
+      #   # 3.3 => "  4.500" (3 digits, 3 decimals) - default
+      #   # 5.2 => "  123.46" (5 digits, 2 decimals)
+      #   # 2.0 => "  4" (2 digits, no decimals)
+      #   # 4.4 => "   4.5000" (4 digits, 4 decimals)
+      #
+      #   logger_compact = Musa::Logger::Logger.new(sequencer: sequencer, position_format: 2.0)
+      #   logger_precise = Musa::Logger::Logger.new(sequencer: sequencer, position_format: 4.4)
+      #
+      # @note The logger outputs to STDERR by default with level set to WARN.
+      # @note Uses InspectNice refinements for better formatting of Rationals and Hashes.
+      # @note The sequencer's position is read at log time, not at event scheduling time.
+      #   This means the position reflects when the log message is actually generated.
       def initialize(sequencer: nil, position_format: nil)
         super STDERR, level: WARN
 
+        # Store sequencer reference for position queries in formatter
         @sequencer = sequencer
-        @position_format = position_format || 3.3
 
+        # Store position format specification
+        @position_format = position_format || 3.3
 
+        # Custom formatter that integrates sequencer position with log messages.
+        #
+        # This proc is called by Ruby's Logger for each log entry. It captures
+        # @sequencer and @position_format from the enclosing scope to format
+        # messages with musical timing information.
+        #
+        # The formatter constructs messages in the format:
+        #   [position]: [LEVEL] [progname] message
+        #
+        # Position calculation:
+        #
+        # - Splits position_format into integer and decimal parts
+        # - Example: 3.3 => 3 integer digits + 3 decimal digits
+        # - Formats sequencer position with calculated precision
+        # - Right-aligns position in the allocated width
+        #
+        # Severity handling:
+        #
+        # - DEBUG level: severity not shown in output
+        # - Other levels: shown as [WARN], [INFO], [ERROR], [FATAL]
+        #
+        # Spacing:
+        #
+        # - Adds separator space only if position, level, or progname are present
+        # - Empty messages output just a newline
+        #
+        # @param severity [String] log level (DEBUG, INFO, WARN, ERROR, FATAL)
+        # @param time [Time] timestamp of the log event (not used in current implementation)
+        # @param progname [String, nil] program/component name
+        # @param msg [String, nil] the actual log message
+        # @return [String] formatted log line with newline
         self.formatter = proc do |severity, time, progname, msg|
+          # Omit severity label for DEBUG level
           level = "[#{severity}] " unless severity == 'DEBUG'
 
           if msg
+            # Calculate and format sequencer position if available
             position = if @sequencer
+                         # Extract integer and decimal digit counts from position_format
+                         # e.g., 3.3 => integer_digits=3, decimal_digits=3
                          integer_digits = @position_format.to_i
                          decimal_digits = ((@position_format - integer_digits) * 10).round
 
-                         "%#{integer_digits + decimal_digits + 1}s: " % ("%.#{decimal_digits}f" % sequencer.position.to_f)
+                         # Format position: total width includes digits + decimal point + ': '
+                         # Right-aligned to keep positions visually aligned in logs
+                         "%#{integer_digits + decimal_digits + 1}s: " % ("%.#{decimal_digits}f" % @sequencer.position.to_f)
                        end
 
+            # Wrap progname in brackets if provided
             progname = "[#{progname}]" if progname
 
+            # Construct final message with conditional spacing
             "#{position}#{level}#{progname}#{' ' if position || level || progname}#{msg}\n"
           else
+            # Empty message case
             "\n"
           end
         end
       end
+
+      # Override level getter to handle encoding compatibility issues.
+      #
+      # Ruby's Logger (>= 1.7.0) has an encoding bug in level_override that causes
+      # Encoding::CompatibilityError when mixing UTF-8 strings from Musa with
+      # Logger's BINARY (ASCII-8BIT) internal strings.
+      #
+      # This override catches the encoding error and returns the level directly
+      # from the instance variable, bypassing the buggy level_override method.
+      #
+      # @return [Integer] current log level (DEBUG=0, INFO=1, WARN=2, ERROR=3, FATAL=4)
+      def level
+        super
+      rescue Encoding::CompatibilityError
+        # Bypass level_override and return raw level
+        @level
+      end
     end
   end
 end

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

@@ -1,15 +1,157 @@
 require 'matrix'
 
+require_relative '../datasets/v'
 require_relative '../datasets/p'
 require_relative '../sequencer'
 
 module Musa
-  module Matrix
-    ## TODO should exist this module?
-  end
-
   module Extension
+    # Refinements for Array and Matrix classes to support musical structure conversions.
+    #
+    # These refinements add methods to convert between matrix representations and
+    # Musa's P (point sequence) format, which is used extensively in the DSL for
+    # representing musical gestures and trajectories.
+    #
+    # ## Background
+    #
+    # In Musa DSL, musical gestures are often represented as sequences of points
+    # in multidimensional space, where dimensions can represent time, pitch, velocity,
+    # or other musical parameters. The P format provides a compact representation
+    # suitable for sequencer playback and transformation.
+    #
+    # ## Matrix to P Conversion
+    #
+    # A matrix of points (rows = time steps, columns = parameters) can be converted
+    # to P format where:
+    #
+    # - One dimension represents time (usually the first column)
+    # - Other dimensions represent musical parameters
+    # - Each P is an array extended with P module
+    # - The P contains alternating values (arrays extended with V) and durations (numbers):
+    #   [value1, duration1, value2, duration2, ..., valueN].extend(P)
+    #
+    # ## Use Cases
+    #
+    # - Converting recorded MIDI data to playable sequences
+    # - Transforming algorithmic compositions from matrix form to time-based sequences
+    # - Merging fragmented musical gestures that share connection points
+    # - Decomposing complex trajectories into simpler monotonic segments
+    #
+    # @example Basic matrix conversion
+    #   using Musa::Extension::Matrix
+    #
+    #   # Matrix: [time, pitch]
+    #   matrix = Matrix[[0, 60], [1, 62], [2, 64]]
+    #   p_sequences = matrix.to_p(time_dimension: 0)
+    #   # Returns an array with one P:
+    #   #   [[60], 1, [62], 1, [64]].extend(P)
+    #   # Where [60], [62], [64] are arrays extended with V module
+    #
+    # @example Multi-dimensional musical parameters
+    #   using Musa::Extension::Matrix
+    #
+    #   # Matrix: [time, pitch, velocity]
+    #   matrix = Matrix[[0, 60, 100], [0.5, 62, 110], [1, 64, 120]]
+    #   p_sequences = matrix.to_p(time_dimension: 0, keep_time: false)
+    #   # Returns an array with one P:
+    #   #   [[60, 100], 0.5, [62, 110], 0.5, [64, 120]].extend(P)
+    #   # Time dimension removed, used only for duration calculation
+    #
+    # @example Condensing connected matrices
+    #   using Musa::Extension::Matrix
+    #
+    #   # Two phrases that connect at [1, 62]
+    #   phrase1 = Matrix[[0, 60], [1, 62]]
+    #   phrase2 = Matrix[[1, 62], [2, 64], [3, 65]]
+    #
+    #   [phrase1, phrase2].to_p(time_dimension: 0)
+    #   # Returns an array with one P (merged):
+    #   #   [[60], 1, [62], 1, [64], 1, [65]].extend(P)
+    #   # Both phrases merged into one continuous sequence
+    #
+    # @see Musa::Datasets::P
+    # @see Musa::Datasets::V
+    # @note These refinements must be activated with `using Musa::Extension::Matrix`
+    #   in the scope where you want to use them.
+    #
+    # ## Methods Added
+    #
+    # ### Array
+    # - {Array#indexes_of_values} - Creates a hash mapping values to their indices
+    # - {Array#to_p} - Converts an array of matrices to P sequences
+    # - {Array#condensed_matrices} - Condenses matrices that share common boundary rows
+    #
+    # ### Matrix
+    # - {::Matrix#to_p} - Converts a matrix to P format (see examples in module documentation)
+    # - {::Matrix#_rows} - Provides direct access to internal rows array (private API)
     module Matrix
+      # @!method indexes_of_values
+      #   Creates a hash mapping values to their indices in the array.
+      #
+      #   This method scans the array and builds an inverted index where each
+      #   unique value maps to an array of positions where it appears.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Matrix`.
+      #
+      #   @return [Hash{Object => Array<Integer>}] hash where keys are array values
+      #     and values are arrays of indices.
+      #
+      #   @example
+      #     using Musa::Extension::Matrix
+      #     [10, 20, 10, 30, 20].indexes_of_values
+      #     # => { 10 => [0, 2], 20 => [1, 4], 30 => [3] }
+      class ::Array; end
+
+      # @!method to_p(time_dimension:, keep_time: nil)
+      #   Converts an array of matrices to an array of P sequences.
+      #
+      #   This method processes each matrix in the array, first condensing matrices
+      #   that share common endpoints, then converting each resulting matrix to
+      #   P (point sequence) format.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Matrix`.
+      #
+      #   @param time_dimension [Integer] index of the dimension to treat as time.
+      #   @param keep_time [Boolean, nil] whether to preserve the time dimension in the output.
+      #     When false or nil, the time dimension is removed and used only for duration calculations.
+      #
+      #   @return [Array<Musa::Datasets::P>] array of P sequences, one per condensed matrix.
+      #
+      #   @example Converting array of matrices
+      #     using Musa::Extension::Matrix
+      #     matrices = [Matrix[[0, 60], [1, 62]], Matrix[[2, 64], [3, 65]]]
+      #     result = matrices.to_p(time_dimension: 0)
+      #     # Returns array of P sequences, one per matrix (or merged if they connect)
+      #
+      #   @see #condensed_matrices
+      #   @see ::Matrix#to_p
+      class ::Array; end
+
+      # @!method condensed_matrices
+      #   Condenses matrices that share common boundary rows.
+      #
+      #   This method merges matrices that have matching first or last rows,
+      #   effectively connecting musical gestures that share endpoints. This is
+      #   particularly useful for creating continuous trajectories from fragmented
+      #   matrix segments.
+      #
+      #   The algorithm compares each matrix with all previously processed matrices,
+      #   looking for matches at either the beginning or end of the row sequence.
+      #   When a match is found, the matrices are merged.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Matrix`.
+      #
+      #   @return [Array<::Matrix>] condensed array of matrices with shared boundaries merged.
+      #
+      #   @example
+      #     using Musa::Extension::Matrix
+      #     # Matrix A ends where Matrix B begins -> they merge
+      #     a = Matrix[[0, 60], [1, 62]]
+      #     b = Matrix[[1, 62], [2, 64]]
+      #     [a, b].condensed_matrices
+      #     # => [Matrix[[0, 60], [1, 62], [2, 64]]]
+      class ::Array; end
+
       refine Array do
         def indexes_of_values
           indexes = {}
@@ -66,6 +208,113 @@ module Musa
         end
       end
 
+      # @!method to_p(time_dimension:, keep_time: nil)
+      #   Converts a matrix to one or more P (point sequence) representations.
+      #
+      #   This method decomposes the matrix into directional segments based on the
+      #   time dimension, then converts each segment into a P sequence format suitable
+      #   for representing musical gestures in Musa DSL.
+      #
+      #   A P sequence is an array extended with the P module, containing alternating
+      #   value arrays (extended with V module) and numeric time deltas:
+      #   [value1, delta1, value2, delta2, ..., valueN].extend(P)
+      #   where each value is an array extended with V module.
+      #
+      #   The decomposition process identifies monotonic segments in the time dimension,
+      #   handling cases where the temporal ordering might have reversals or
+      #   non-linearities.
+      #
+      #   @note This method is added to Matrix via refinement. Requires `using Musa::Extension::Matrix`.
+      #
+      #   @param time_dimension [Integer] index of the dimension representing time (typically 0).
+      #   @param keep_time [Boolean, nil] if true, the time dimension is preserved in each point;
+      #     if false/nil, it's removed and used only for computing deltas.
+      #
+      #   @return [Array<Musa::Datasets::P>] array of P sequences, one per directional segment.
+      #
+      #   @example Basic conversion
+      #     using Musa::Extension::Matrix
+      #     matrix = Matrix[[0, 60], [1, 62], [2, 64]]
+      #     result = matrix.to_p(time_dimension: 0)
+      #     # => Array with one P object:
+      #     #    [[60], 1, [62], 1, [64]].extend(P)
+      #     # Each value like [60] is extended with V module
+      #
+      #   @example Keeping time dimension
+      #     using Musa::Extension::Matrix
+      #     matrix = Matrix[[0, 60, 100], [1, 62, 110], [2, 64, 120]]
+      #     result = matrix.to_p(time_dimension: 0, keep_time: true)
+      #     # => Array with one P object:
+      #     #    [[0, 60, 100], 1, [1, 62, 110], 1, [2, 64, 120]].extend(P)
+      #     # Time dimension kept in each value array
+      #
+      #   @see Musa::Datasets::P
+      #   @see Musa::Datasets::V
+      #   
+      #   @api public
+      class ::Matrix; end
+
+      # @!method _rows
+      #   Provides direct access to the internal rows array of the matrix.
+      #
+      #   This is a utility method used primarily by {Array#condensed_matrices}
+      #   to manipulate matrix rows when merging matrices with shared boundaries.
+      #
+      #   @note This method is added to Matrix via refinement. Requires `using Musa::Extension::Matrix`.
+      #
+      #   @return [Array<Array>] the internal @rows instance variable.
+      #
+      #   @api private
+      #   @note This method accesses Ruby's Matrix internals and should be used with caution.
+      class ::Matrix; end
+
+      # @!method decompose(array, time_dimension)
+      # Decomposes an array of points into directional segments based on a time dimension.
+      #
+      # This private method analyzes the array to find monotonic (non-decreasing)
+      # sequences in the specified time dimension. It scans bidirectionally from
+      # each point to discover maximal segments where time progresses consistently.
+      #
+      # The algorithm:
+      #
+      # 1. Groups points by their time values
+      # 2. Iterates through time values in sorted order
+      # 3. For each unprocessed index, scans backward and forward
+      # 4. Collects points while time is non-decreasing
+      # 5. Returns segments with 2+ points
+      #
+      # @param array [Array<Array>] array of point arrays (each point is an array of coordinates).
+      # @param time_dimension [Integer] index of the dimension representing time.
+      #
+      # @return [Array<Array<Array>>] array of directional segments, each segment
+      #   being an array of points.
+      #
+      # @example
+      #   # Points with time in dimension 0
+      #   points = [[0, 10], [1, 20], [0.5, 15], [2, 30]]
+      #   decompose(points, 0)
+      #   # => [[[1, 20], [0.5, 15], [0, 10]], [[0, 10], [0.5, 15], [1, 20], [2, 30]]]
+      #   # Two segments: one going backward in time, one forward
+      #
+      # @todo POTENTIAL LOGIC INCONSISTENCY: Review the direction logic in backward and forward scans.
+      #   - Line 300 comment: "Scan backward... while time is non-decreasing"
+      #   - Line 306 code: `while i >= 0 && array[i][time_dimension] >= xx`
+      #   - Line 316 comment: "Scan forward... while time is non-decreasing"
+      #   - Line 322 code: `while i < array.size && array[i][time_dimension] >= xx`
+      #   Both scans use `>= xx`, which seems contradictory. When scanning backward
+      #   (decreasing indices), for "non-decreasing time" we might expect `<= xx`
+      #   (times getting smaller or equal as we go back in indices). Currently both
+      #   directions use the same comparison operator.
+      #   IMPLEMENT TESTS to verify expected behavior with various input patterns and
+      #   confirm whether this is intentional or a bug. Test cases should include:
+      #   - Forward-only monotonic sequences
+      #   - Backward-only monotonic sequences
+      #   - Mixed direction sequences
+      #   - The example documented above
+      #
+      # @api private
+      class ::Matrix; end
+
       refine ::Matrix do
         def to_p(time_dimension:, keep_time: nil)
           decompose(self.to_a, time_dimension).collect do |points|
@@ -105,10 +354,9 @@ module Musa
 
           x_dim_values_indexes.keys.sort.each do |value|
             x_dim_values_indexes[value].each do |index|
-              #
-              # hacia un lado
-              #
+              # Scan in both directions from this point to find monotonic segments
               unless used_indexes.include?(index)
+                # Scan backward (decreasing indices) while time is non-decreasing
                 i = index
                 xx = array[i][time_dimension]
 
@@ -124,9 +372,7 @@ module Musa
 
                 directional_segments << a if a.size > 1
 
-                #
-                # y hacia el otro
-                #
+                # Scan forward (increasing indices) while time is non-decreasing
                 i = index
                 xx = array[i][time_dimension]