musa-dsl 0.40.0 → 0.41.0

data/lib/musa-dsl/generative/rules.rb

@@ -149,6 +149,8 @@ module Musa
       #     cut 'validate' { |obj| prune if invalid?(obj) }
       #     ended_when { |obj| complete?(obj) }
       #   end
+      #
+      # @return [void]
       def initialize(&block)
         @dsl = RulesEvalContext.new(&block)
       end
@@ -257,6 +259,7 @@ module Musa
         # @return [Array<CutRule>] cut rules
         attr_reader :_grow_rules, :_ended_when, :_cut_rules
 
+        # @return [void]
         # @api private
         def initialize(&block)
           @_grow_rules = []
@@ -296,10 +299,24 @@ module Musa
           self
         end
 
+        # Checks if end condition is defined.
+        #
+        # @return [Boolean] true if ended_when was called
+        #
+        # @api private
         def _has_ending?
           !@_ended_when.nil?
         end
 
+        # Evaluates end condition for object.
+        #
+        # @param object [Object] object to check
+        # @param history [Array] object history
+        # @param parameters [Hash] additional parameters
+        #
+        # @return [Boolean] true if object should end
+        #
+        # @api private
         def _ended?(object, history, **parameters)
           if @_ended_when
             with object, history, **parameters, &@_ended_when
@@ -311,11 +328,21 @@ module Musa
         class GrowRule
           attr_reader :name
 
+          # @param name [String] rule name
+          #
+          # @return [void]
           def initialize(name, &block)
             @name = name
             @block = block
           end
 
+          # Generates possible branched objects.
+          #
+          # @param object [Object] object to branch
+          # @param history [Array] object history
+          # @param parameters [Hash] additional parameters
+          #
+          # @return [Array<Object>] branched objects
           def generate_possibilities(object, history, **parameters)
             # TODO: optimize context using only one instance for all genereate_possibilities calls
             context = GrowRuleEvalContext.new
@@ -329,10 +356,16 @@ module Musa
 
             attr_reader :_branches
 
+            # @return [void]
             def initialize
               @_branches = []
             end
 
+            # Records a branched object.
+            #
+            # @param object [Object] branched object
+            #
+            # @return [self]
             def branch(object)
               @_branches << object
               self
@@ -347,11 +380,21 @@ module Musa
         class CutRule
           attr_reader :reason
 
+          # @param reason [String] rejection reason
+          #
+          # @return [void]
           def initialize(reason, &block)
             @reason = reason
             @block = block
           end
 
+          # Checks if object should be rejected.
+          #
+          # @param object [Object] object to check
+          # @param history [Array] object history
+          # @param parameters [Hash] additional parameters
+          #
+          # @return [Array<String>, nil] rejection reasons or nil if not rejected
           def rejects?(object, history, **parameters)
             # TODO: optimize context using only one instance for all rejects? checks
             context = CutRuleEvalContext.new
@@ -367,10 +410,16 @@ module Musa
 
             attr_reader :_secondary_reasons
 
+            # @return [void]
             def initialize
               @_secondary_reasons = []
             end
 
+            # Marks object for pruning.
+            #
+            # @param secondary_reason [String, nil] additional reason detail
+            #
+            # @return [self]
             def prune(secondary_reason = nil)
               @_secondary_reasons << secondary_reason
               self
@@ -399,6 +448,11 @@ module Musa
       class Node
         attr_reader :parent, :children, :object, :rejected
 
+        # @param object [Object, nil] node object
+        # @param parent [Node, nil] parent node
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(object = nil, parent = nil)
           @parent = parent

data/lib/musa-dsl/generative/variatio.rb

@@ -143,6 +143,8 @@ module Musa
       #     field :y, [:a, :b]
       #     constructor { |x:, y:| { x: x, y: y } }
       #   end
+      #
+      # @return [void]
       def initialize(instance_name, &block)
         raise ArgumentError, 'instance_name should be a symbol' unless instance_name.is_a?(Symbol)
         raise ArgumentError, 'block is needed' unless block
@@ -259,6 +261,11 @@ module Musa
 
       private
 
+      # Generates evaluation tree for parameter calculation.
+      #
+      # @param fieldset [Fieldset] fieldset to process
+      #
+      # @return [A, nil] root node of evaluation tree
       def generate_eval_tree_A(fieldset)
         root = nil
         current = nil
@@ -279,6 +286,11 @@ module Musa
         root
       end
 
+      # Generates evaluation tree for attribute application.
+      #
+      # @param fieldset [Fieldset] fieldset to process
+      #
+      # @return [B] root node of attribute tree
       def generate_eval_tree_B(fieldset)
         affected_field_names = []
         inner = []
@@ -298,12 +310,19 @@ module Musa
         attr_reader :parameter_name, :options
         attr_accessor :inner
 
+        # @param parameter_name [Symbol] parameter name
+        # @param options [Array] option values
+        #
+        # @return [void]
         def initialize(parameter_name, options)
           @parameter_name = parameter_name
           @options = options
           @inner = nil
         end
 
+        # Calculates all parameter combinations.
+        #
+        # @return [Array<Hash>] parameter combination hashes
         def calc_parameters
           unless @calc_parameters
             if inner
@@ -320,16 +339,19 @@ module Musa
       private_constant :A
 
       class A1 < A
+        # @return [void]
         def initialize(parameter_name, options)
           super parameter_name, options
 
           @own_parameters = @options.collect { |option| { @parameter_name => option } }
         end
 
+        # @return [Array<Hash>] own parameter combinations
         def calc_own_parameters
           @own_parameters
         end
 
+        # @return [String] string representation
         def inspect
           "A1 name: #{@parameter_name}, options: #{@options}, inner: #{@inner || 'nil'}"
         end
@@ -340,6 +362,11 @@ module Musa
       private_constant :A1
 
       class A2 < A
+        # @param parameter_name [Symbol] parameter name
+        # @param options [Array] option values
+        # @param subcomponent [A] nested tree
+        #
+        # @return [void]
         def initialize(parameter_name, options, subcomponent)
           super parameter_name, options
 
@@ -361,10 +388,12 @@ module Musa
           @own_parameters = result
         end
 
+        # @return [Array<Hash>] own parameter combinations
         def calc_own_parameters
           @own_parameters
         end
 
+        # @return [String] string representation
         def inspect
           "A2 name: #{@parameter_name}, options: #{@options}, subcomponent: #{@subcomponent}, inner: #{@inner || 'nil'}"
         end
@@ -383,6 +412,13 @@ module Musa
       class B
         attr_reader :parameter_name, :options, :affected_field_names, :blocks, :inner
 
+        # @param parameter_name [Symbol] parameter name
+        # @param options [Array] option values
+        # @param affected_field_names [Array<Symbol>] field names affected
+        # @param inner [Array<B>] nested B nodes
+        # @param blocks [Array<Proc>] with_attributes blocks
+        #
+        # @return [void]
         def initialize(parameter_name, options, affected_field_names, inner, blocks)
           @parameter_name = parameter_name
           @options = options
@@ -392,6 +428,12 @@ module Musa
           @procedures = blocks.collect { |proc| Musa::Extension::SmartProcBinder::SmartProcBinder.new proc }
         end
 
+        # Runs attribute application for this node.
+        #
+        # @param parameters_with_depth [Hash] parameters with nesting depth
+        # @param parent_parameters [Hash, nil] parent context parameters
+        #
+        # @return [void]
         def run(parameters_with_depth, parent_parameters = nil)
           parent_parameters ||= {}
 
@@ -417,6 +459,7 @@ module Musa
           end
         end
 
+        # @return [String] string representation
         def inspect
           "B name: #{@parameter_name}, options: #{@options}, affected_field_names: #{@affected_field_names}, blocks_size: #{@blocks.size}, inner: #{@inner}"
         end
@@ -435,6 +478,10 @@ module Musa
         # @return [Fieldset] defined fieldset
         attr_reader :_fieldset
 
+        # @param name [Symbol] fieldset name
+        # @param options [Array, Range, nil] fieldset options
+        #
+        # @return [void]
         # @api private
         def initialize(name, options = nil, &block)
           @_fieldset = Fieldset.new name, options.arrayfy.explode_ranges
@@ -446,6 +493,8 @@ module Musa
         #
         # @param name [Symbol] field name
         # @param options [Array, Range, nil] field option values
+        #
+        # @return [void]
         # @api private
         def field(name, options = nil)
           @_fieldset.components << Field.new(name, options.arrayfy.explode_ranges)
@@ -455,7 +504,10 @@ module Musa
         #
         # @param name [Symbol] fieldset name
         # @param options [Array, Range, nil] fieldset option values
+        #
         # @yield fieldset DSL block
+        #
+        # @return [void]
         # @api private
         def fieldset(name, options = nil, &block)
           fieldset_context = FieldsetContext.new name, options, &block
@@ -465,6 +517,8 @@ module Musa
         # Adds attribute modification block.
         #
         # @yield attribute modification block
+        #
+        # @return [void]
         # @api private
         def with_attributes(&block)
           @_fieldset.with_attributes << block
@@ -481,6 +535,7 @@ module Musa
         # @return [Proc, nil] finalize block
         attr_reader :_constructor, :_finalize
 
+        # @return [void]
         # @api private
         def initialize(&block)
           @_constructor = nil
@@ -492,6 +547,8 @@ module Musa
         # Defines object constructor.
         #
         # @yield constructor block receiving field values
+        #
+        # @return [void]
         # @api private
         def constructor(&block)
           @_constructor = block
@@ -500,6 +557,8 @@ module Musa
         # Defines finalize block.
         #
         # @yield finalize block receiving completed object
+        #
+        # @return [void]
         # @api private
         def finalize(&block)
           @_finalize = block
@@ -512,6 +571,7 @@ module Musa
         attr_reader :name
         attr_accessor :options
 
+        # @return [String] string representation
         def inspect
           "Field #{@name} options: #{@options}"
         end
@@ -520,6 +580,10 @@ module Musa
 
         private
 
+        # @param name [Symbol] field name
+        # @param options [Array] option values
+        #
+        # @return [void]
         def initialize(name, options)
           @name = name
           @options = options
@@ -532,6 +596,7 @@ module Musa
         attr_reader :name, :with_attributes, :components
         attr_accessor :options
 
+        # @return [String] string representation
         def inspect
           "Fieldset #{@name} options: #{@options} components: #{@components}"
         end
@@ -540,6 +605,10 @@ module Musa
 
         private
 
+        # @param name [Symbol] fieldset name
+        # @param options [Array, nil] option values
+        #
+        # @return [void]
         def initialize(name, options)
           @name = name
           @options = options || [nil]

data/lib/musa-dsl/midi/midi-recorder.rb

@@ -79,6 +79,8 @@ module Musa
     # @see https://github.com/javier-sy/midi-events MIDIEvents documentation
     class MIDIRecorder
       # @param sequencer [Musa::Sequencer::Sequencer] provides the musical position for each recorded message.
+      #
+      # @return [void]
       def initialize(sequencer)
         @sequencer = sequencer
         @midi_parser = MIDIParser.new
@@ -179,6 +181,8 @@ module Musa
         #
         # @param position [Rational] sequencer position when captured.
         # @param message [MIDIEvents::Event] parsed MIDI event.
+        #
+        # @return [void]
         def initialize(position, message)
           @position = position
           @message = message

data/lib/musa-dsl/midi/midi-voices.rb

@@ -97,6 +97,8 @@ module Musa
       # @param output [#puts, nil] anything responding to `puts` that accepts `MIDIEvents::Event`s (typically a MIDICommunications output).
       # @param channels [Array<Numeric>, Range, Numeric] list of MIDI channels to control. Ranges are expanded automatically.
       # @param do_log [Boolean] enables info level logs per emitted message.
+      #
+      # @return [void]
       def initialize(sequencer:, output:, channels:, do_log: nil)
         do_log ||= false
 
@@ -200,6 +202,8 @@ module Musa
       # @param output [#puts, nil]
       # @param channel [Integer] MIDI channel number (0-15).
       # @param name [String, nil] human friendly identifier.
+      #
+      # @return [void]
       def initialize(sequencer:, output:, channel:, name: nil, do_log: nil)
         do_log ||= false
 
@@ -337,6 +341,8 @@ module Musa
       class ControllersControl
         # @param output [#puts] MIDI output.
         # @param channel [Integer] MIDI channel number.
+        #
+        # @return [void]
         def initialize(output, channel)
           @output = output
           @channel = channel
@@ -368,6 +374,8 @@ module Musa
         #
         # @param controller_number_or_symbol [Integer, Symbol] CC number or well-known alias (see +@controller_map+).
         # @param value [Integer] byte value that will be clamped to 0-127.
+        #
+        # @return [Integer] clamped value
         def []=(controller_number_or_symbol, value)
           number = number_of(controller_number_or_symbol)
           value ||= 0
@@ -429,6 +437,8 @@ module Musa
         # @param velocity [Numeric, Array<Numeric>] on velocity (can be per-note).
         # @param duration [Numeric, nil] duration in bars or nil for infinite.
         # @param velocity_off [Numeric, Array<Numeric>] release velocity.
+        #
+        # @return [void]
         def initialize(voice, pitch:, velocity: nil, duration: nil, velocity_off: nil)
           raise ArgumentError, "MIDIVoice: note duration should be nil or Numeric: #{duration} (#{duration.class})" unless duration.nil? || duration.is_a?(Numeric)
 

data/lib/musa-dsl/music/chords.rb

@@ -429,32 +429,41 @@ module Musa
         Chord.new(@root.octave(octave), @scale, chord_definition, @move, @duplicate, source_notes_map)
       end
 
-      # Creates new chord with positions moved to different octaves.
+      # Creates new chord with positions moved to different octaves, or returns current move settings.
       #
-      # Relocates specific chord positions to different octaves while keeping
-      # other positions unchanged. Multiple positions can be moved at once.
-      # Merges with existing moves.
+      # When called with arguments, relocates specific chord positions to different
+      # octaves while keeping other positions unchanged. Multiple positions can be
+      # moved at once. Merges with existing moves.
+      #
+      # When called without arguments, returns the current move settings hash.
       #
       # @param octaves [Hash{Symbol => Integer}] position to octave offset mapping
-      # @return [Chord] new chord with moved positions
+      # @return [Chord, Hash] new chord with moved positions, or current move settings if no arguments
       #
       # @example Move root down, seventh up
       #   chord.move(root: -1, seventh: 1)
       #
       # @example Drop voicing (move third and seventh down)
       #   chord.move(third: -1, seventh: -1)
+      #
+      # @example Get current move settings
+      #   chord.move  # => { root: -1 }
       def move(**octaves)
+        return @move if octaves.empty?
+
         Chord.new(@root, @scale, @chord_definition, @move.merge(octaves), @duplicate, @source_notes_map)
       end
 
-      # Creates new chord with positions duplicated in other octaves.
+      # Creates new chord with positions duplicated in other octaves, or returns current duplicate settings.
       #
-      # Adds copies of specific chord positions in different octaves.
-      # Original positions remain at their current octave.
+      # When called with arguments, adds copies of specific chord positions in
+      # different octaves. Original positions remain at their current octave.
       # Merges with existing duplications.
       #
+      # When called without arguments, returns the current duplicate settings hash.
+      #
       # @param octaves [Hash{Symbol => Integer, Array<Integer>}] position to octave(s)
-      # @return [Chord] new chord with duplicated positions
+      # @return [Chord, Hash] new chord with duplicated positions, or current duplicate settings if no arguments
       #
       # @example Duplicate root two octaves down
       #   chord.duplicate(root: -2)
@@ -464,10 +473,46 @@ module Musa
       #
       # @example Duplicate multiple positions
       #   chord.duplicate(root: -1, fifth: 1)
+      #
+      # @example Get current duplicate settings
+      #   chord.duplicate  # => { root: -1 }
       def duplicate(**octaves)
+        return @duplicate if octaves.empty?
+
         Chord.new(@root, @scale, @chord_definition, @move, @duplicate.merge(octaves), @source_notes_map)
       end
 
+      # Finds this chord in other scales.
+      #
+      # Searches through scale kinds matching the given metadata criteria to find
+      # all scales that contain this chord. Returns new chord instances, each with
+      # its containing scale as context.
+      #
+      # @param roots [Range, Array, nil] pitch offsets to search (default: full octave)
+      # @param metadata [Hash] metadata filters for scale kinds (family:, brightness:, etc.)
+      # @return [Array<Chord>] this chord in different scale contexts
+      #
+      # @example Find G major triad in diatonic scales
+      #   g_triad = c_major.dominant.chord
+      #   g_triad.in_scales(family: :diatonic)
+      #
+      # @example Find chord in scales with specific brightness
+      #   g7.in_scales(brightness: -1..1)
+      #
+      # @example Iterate over results
+      #   g7.in_scales(family: :greek_modes).each do |chord|
+      #     scale = chord.scale
+      #     degree = scale.degree_of_chord(chord)
+      #     puts "#{scale.kind.class.id} on #{scale.root_pitch}: degree #{degree}"
+      #   end
+      #
+      # @see Musa::Scales::Scale#chord_on
+      # @see Musa::Scales::ScaleSystemTuning#chords_of
+      def in_scales(roots: nil, **metadata)
+        tuning = @scale&.kind&.tuning || @root.scale.kind.tuning
+        tuning.chords_of(self, roots: roots, **metadata)
+      end
+
       # Checks chord equality.
       #
       # Chords are equal if they have the same notes and chord definition.