musa-dsl 0.40.0 → 0.42.0

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

@@ -166,6 +166,8 @@ module Musa
       #
       # @param content [Object] element content
       # @param attributes [Hash, nil] element attributes
+      #
+      # @return [void]
       def initialize(content, attributes = nil)
         @content = content
         @attributes = attributes || {}
@@ -367,10 +369,12 @@ module Musa
         # @param index [Integer] option index
         #
         # @return [Node] option converted to node
-        def [](index)
+        def get(index)
           options[index].to_serie.to_node
         end
 
+        alias_method :[], :get
+
         # Converts options to series.
         #
         # Generates options and converts them to a {Musa::Series::Serie}.
@@ -406,6 +410,14 @@ module Musa
 
         protected
 
+        # Generates condition block from simplified arguments.
+        #
+        # @param attribute [Symbol, nil] attribute to check
+        # @param after_collect_operation [Symbol, nil] operation on collected values
+        # @param comparison_method [Symbol, nil] comparison method to apply
+        # @param comparison_value [Object, nil] value to compare against
+        #
+        # @return [Proc, nil] condition block or nil if arguments incomplete
         def generate_simple_condition_block(attribute = nil,
                                             after_collect_operation = nil,
                                             comparison_method = nil,
@@ -451,6 +463,9 @@ module Musa
 
         # @param content [Object] node content
         # @param attributes [Hash] node attributes
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(content, attributes)
           super()
@@ -482,6 +497,9 @@ module Musa
       class BlockNode < Node
         # @param attributes [Hash] node attributes
         # @yield [parent, attributes] block to generate content
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(attributes, &block)
           @attributes = attributes
@@ -516,6 +534,9 @@ module Musa
       class ConditionNode < Node
         # @param node [Node] node to filter
         # @yield [option] condition block
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(node, &block)
           @node = node
@@ -545,6 +566,9 @@ module Musa
       class OrNode < Node
         # @param node1 [Node] first alternative
         # @param node2 [Node] second alternative
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(node1, node2)
           @node1 = node1
@@ -579,6 +603,9 @@ module Musa
       class NextNode < Node
         # @param node [Node] first node in sequence
         # @param after [Node] node to follow
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(node, after)
           @node = node
@@ -609,6 +636,9 @@ module Musa
       class RepeatNode < Node
         # @param node [Node] node to repeat
         # @param max [Integer, nil] maximum repetitions (nil = infinite)
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(node, max = nil)
           @node = node

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

@@ -97,7 +97,7 @@ module Musa
     # Implements {Musa::Series::Serie} interface for integration with series operations.
     class Markov
       # TODO: adapt to series prototyping
-      include Musa::Series::Serie.base
+      include Musa::Series::Serie::Base
 
       # Creates Markov chain generator.
       #
@@ -113,6 +113,8 @@ module Musa
       #     start: :a,
       #     finish: :x
       #   )
+      #
+      # @return [void]
       def initialize(transitions:, start:, finish: nil, random: nil)
         @transitions = transitions.clone.freeze
 

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
@@ -377,10 +385,12 @@ module Musa
         end
 
         # @return [Integer, nil] last value assigned to the controller.
-        def [](controller_number_or_symbol)
+        def get(controller_number_or_symbol)
           @controller[number_of(controller_number_or_symbol)]
         end
 
+        alias_method :[], :get
+
         # Resolves a controller reference to its MIDI CC number.
         #
         # @param controller_number_or_symbol [Integer, Symbol] CC number or alias.
@@ -429,6 +439,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/chord-definition.rb

@@ -1,5 +1,3 @@
-require 'set'
-
 module Musa
   # Chord construction and manipulation framework.
   #
@@ -115,10 +113,14 @@ module Musa
       # @example
       #   ChordDefinition[:maj]   # => <ChordDefinition :maj>
       #   ChordDefinition[:min7]  # => <ChordDefinition :min7>
-      def self.[](name)
+      def self.get(name)
         @definitions[name]
       end
 
+      class << self
+        alias_method :[], :get
+      end
+
       # Registers a new chord definition.
       #
       # Creates and registers a chord definition with specified intervals and features.
@@ -150,7 +152,7 @@ module Musa
         definition.features.each { |k, v| @features_by_value[v] = k }
 
         @feature_keys ||= Set[]
-        features.keys.each { |feature_name| @feature_keys << feature_name }
+        features.each_key { |feature_name| @feature_keys << feature_name }
 
         self
       end
@@ -267,7 +269,7 @@ module Musa
 
       # Checks if chord fits within a scale.
       #
-      # @param scale [Scale] scale to check against
+      # @param scale [Scales::Scale] scale to check against
       # @param chord_root_pitch [Integer] chord root pitch
       # @return [Boolean] true if all chord notes are in scale
       #

data/lib/musa-dsl/music/chord-definitions.rb

@@ -1,5 +1,42 @@
 require_relative 'chord-definition'
 
+# Standard chord definitions for Western harmony.
+#
+# This file registers the common chord types used in Western music theory,
+# organized by size (number of notes) and quality (major, minor, etc.).
+#
+# ## Chord Categories
+#
+# ### Triads (3 notes)
+# - **Major** (:maj) - Root, major 3rd, perfect 5th (0-4-7)
+# - **Minor** (:min) - Root, minor 3rd, perfect 5th (0-3-7)
+# - **Diminished** (:dim) - Root, minor 3rd, diminished 5th (0-3-6)
+# - **Augmented** (:aug) - Root, major 3rd, augmented 5th (0-4-8)
+#
+# ### Seventh Chords (4 notes)
+# - **Major 7th** (:maj7) - Major triad + major 7th (0-4-7-11)
+# - **Minor 7th** (:min7) - Minor triad + minor 7th (0-3-7-10)
+# - **Dominant 7th** (:dom7) - Major triad + minor 7th (0-4-7-10)
+#
+# ### Extended Chords (5+ notes)
+# - **9th chords**: :maj9, :min9, :dom9
+# - **11th chords**: :maj11, :min11
+# - **13th chords**: :maj13, :min13
+#
+# ## Usage
+#
+# Chords are accessed via scale notes using the {Musa::Scales::NoteInScale#chord} method:
+#
+#     scale = Scales.et12[440.0].major[60]
+#     scale.tonic.chord                    # Major triad (default)
+#     scale.tonic.chord :seventh           # Major 7th
+#     scale.dominant.chord :seventh        # Dominant 7th
+#     scale.tonic.chord quality: :minor    # Minor triad
+#
+# @see Musa::Chords::ChordDefinition.register How chords are registered
+# @see Musa::Chords::Chord How to build and use chords
+# @see Musa::Scales::NoteInScale#chord Building chords from scale notes
+
 # TODO trasladar los acordes de https://en.wikipedia.org/wiki/Chord_notation
 
 # TRIADS