musa-dsl 0.30.2 → 0.40.0

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

@@ -1,9 +1,126 @@
 module Musa
+  # Generative grammar system for creating formal grammars with combinatorial generation.
+  #
+  # GenerativeGrammar provides a DSL for defining formal grammars that can generate
+  # all possible combinations of terminal and non-terminal symbols according to
+  # production rules. Similar to context-free grammars in formal language theory.
+  #
+  # ## Core Concepts
+  #
+  # - **Nodes (N)**: Terminal or block nodes with content and attributes
+  # - **Proxy Nodes (PN)**: Placeholder nodes for recursive grammar definitions
+  # - **Operators**: Combine nodes to form production rules
+  #   - `|` (or): Alternative/choice between nodes
+  #   - `+` (next): Concatenation/sequence of nodes
+  # - **Modifiers**:
+  #   - `repeat(min:, max:)`: Repeat node multiple times
+  #   - `limit(&block)`: Filter options by condition
+  # - **Options**: Generate all valid combinations matching the grammar
+  #
+  # ## Grammar Definition Process
+  #
+  # 1. Define terminal nodes with N(content, **attributes)
+  # 2. Combine nodes using operators (|, +)
+  # 3. Add repetition and limits as needed
+  # 4. Use PN() for recursive grammars
+  # 5. Call .options to generate all valid combinations
+  #
+  # ## Musical Applications
+  #
+  # - Generate melodic patterns with rhythmic constraints
+  # - Create harmonic progressions with voice leading rules
+  # - Produce variations of musical motifs
+  # - Build algorithmic composition structures
+  #
+  # @example Simple sequence with alternatives
+  #   include Musa::GenerativeGrammar
+  #
+  #   a = N('a', size: 1)
+  #   b = N('b', size: 1)
+  #   c = N('c', size: 1)
+  #
+  #   # Grammar: (a or b) repeated 3 times, then c
+  #   grammar = (a | b).repeat(3) + c
+  #
+  #   # Generate all possibilities
+  #   grammar.options(content: :join)
+  #   # => ["aaac", "aabc", "abac", "abbc", "baac", "babc", "bbac", "bbbc"]
+  #
+  # @example Grammar with constraints
+  #   a = N('a', size: 1)
+  #   b = N('b', size: 1)
+  #
+  #   # Limit: total size must equal 3
+  #   grammar = (a | b).repeat.limit { |o| o.collect { |_| _.attributes[:size] }.sum == 3 }
+  #
+  #   # Filter options where size <= 4
+  #   grammar.options(content: :join) { |o| o.collect { |e| e.attributes[:size] }.sum <= 4 }
+  #   # => ["aaa", "aab", "aba", "abb", "baa", "bab", "bba", "bbb"]
+  #
+  # @example Recursive grammar using proxy nodes
+  #   a = N('a', size: 1)
+  #   b = N('b', size: 1)
+  #   c = N('c', size: 1)
+  #
+  #   # Create proxy for recursion
+  #   dp = PN()
+  #
+  #   # Grammar: (c + dp) or (a or b), limit size to 3
+  #   d = (c + dp | (a | b)).repeat.limit(:size, :sum, :==, 3)
+  #
+  #   # Assign recursive reference
+  #   dp.node = d
+  #
+  #   d.options(:size, :sum, :<=, 4, content: :join)
+  #   # => ["cca", "ccb", "caa", "cab", "cba", "cbb", "aca", "acb", ...]
+  #
+  # @example Block nodes for dynamic content
+  #   a = N(color: :blue) { |parent| 'hola' }
+  #   b = N(color: :red) { |parent, attributes|
+  #     OptionElement.new('adios', final: true, **attributes)
+  #   }
+  #
+  #   grammar = (a | b).repeat(2)
+  #   grammar.options
+  #   # => [["hola", "hola"], ["hola", "adios"], ["adios", "hola"], ["adios", "adios"]]
+  #
+  # @see N Method to create terminal/block nodes
+  # @see PN Method to create proxy nodes for recursion
+  # @see Musa::Series::Serie Series conversion for grammar options
+  # @see https://en.wikipedia.org/wiki/Formal_grammar Formal grammar (Wikipedia)
+  # @see https://en.wikipedia.org/wiki/Context-free_grammar Context-free grammar (Wikipedia)
+  # @see https://en.wikipedia.org/wiki/Generative_grammar Generative grammar (Wikipedia)
   module GenerativeGrammar
     # TODO: refactor & reorganize regarding use of include Musa::GenerativeGrammar problems as default consumption mode (it forces the consumer to have new public methods -P, PN- and class names -OptionElement-)
 
     extend self
 
+    # Creates a terminal or block node.
+    #
+    # Nodes are the basic building blocks of grammars. They can be:
+    #
+    # - **Terminal nodes**: Fixed content with attributes
+    # - **Block nodes**: Dynamic content generated by block
+    #
+    # @param content [Object, nil] terminal content (if no block given)
+    # @param attributes [Hash] attributes attached to node
+    #
+    # @yieldparam parent [Array<OptionElement>] parent elements in generation
+    # @yieldparam attributes [Hash] node attributes
+    # @yieldreturn [Object, OptionElement] generated content or element
+    #
+    # @return [Implementation::FinalNode, Implementation::BlockNode] created node
+    #
+    # @example Terminal node
+    #   n = N('a', size: 1)
+    #
+    # @example Block node
+    #   n = N(color: :blue) { |parent| "hello" }
+    #
+    # @example Block returning OptionElement
+    #   n = N(type: :special) { |parent, attrs|
+    #     OptionElement.new('value', **attrs)
+    #   }
     def N(content = nil, **attributes, &block)
       if block_given? && content.nil?
         Implementation::BlockNode.new(attributes, &block)
@@ -12,13 +129,43 @@ module Musa
       end
     end
 
+    # Creates a proxy node for recursive grammars.
+    #
+    # Proxy nodes act as placeholders that can be assigned later,
+    # enabling recursive and self-referential grammar definitions.
+    #
+    # @return [Implementation::ProxyNode] proxy node
+    #
+    # @example Recursive grammar
+    #   a = N('a')
+    #   b = N('b')
+    #
+    #   # Create proxy
+    #   proxy = PN()
+    #
+    #   # Define grammar referencing itself through proxy
+    #   grammar = a + proxy | b
+    #
+    #   # Assign recursive reference
+    #   proxy.node = grammar
     def PN
       Implementation::ProxyNode.new
     end
 
+    # Container for generated option elements.
+    #
+    # Wraps content and attributes for each element in a generated option.
+    # Used internally when generating grammar options.
+    #
+    # @attr_reader content [Object] element content
+    # @attr_reader attributes [Hash] element attributes
     class OptionElement
       attr_reader :content, :attributes
 
+      # Creates option element.
+      #
+      # @param content [Object] element content
+      # @param attributes [Hash, nil] element attributes
       def initialize(content, attributes = nil)
         @content = content
         @attributes = attributes || {}
@@ -26,13 +173,54 @@ module Musa
     end
 
     module Implementation
+      # Base node class for grammar elements.
+      #
+      # Provides core operations for combining and transforming nodes.
+      # All node types (FinalNode, BlockNode, OrNode, etc.) inherit from this.
+      #
+      # @api private
       class Node
+        # Creates alternation between this node and another.
+        #
+        # Generates options where either this node or the other is chosen.
+        #
+        # @param other [Node] alternative node
+        #
+        # @return [OrNode] alternation node
+        #
+        # @example
+        #   a = N('a')
+        #   b = N('b')
+        #   ab = a.or(b)  # or a | b
         def or(other)
           OrNode.new(self, other)
         end
 
         alias_method :|, :or
 
+        # Repeats this node with optional min/max bounds.
+        #
+        # Generates options with different repetition counts of this node.
+        # Without bounds, generates infinite options (use with limit).
+        #
+        # @param exactly [Integer, nil] exact repetition count
+        # @param min [Integer, nil] minimum repetitions
+        # @param max [Integer, nil] maximum repetitions
+        #
+        # @return [Node] node with repetition
+        #
+        # @raise [ArgumentError] if both exactly and min/max are specified
+        #
+        # @example Fixed repetition
+        #   a = N('a')
+        #   aaa = a.repeat(3)         # exactly 3 times
+        #   aaa = a.repeat(exactly: 3)  # same
+        #
+        # @example Bounded repetition
+        #   a_range = a.repeat(min: 2, max: 4)  # 2, 3, or 4 times
+        #
+        # @example Unbounded (use with limit)
+        #   a_any = a.repeat.limit { |o| o.size <= 5 }
         def repeat(exactly = nil, min: nil, max: nil)
           raise ArgumentError, 'Only exactly value or min/max values are allowed' if exactly && (min || max)
 
@@ -55,6 +243,30 @@ module Musa
           end
         end
 
+        # Limits generated options by condition.
+        #
+        # Filters options to only those satisfying the given condition.
+        # Can use simplified arguments or custom block.
+        #
+        # @param attribute [Symbol, nil] attribute to check (simplified form)
+        # @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
+        #
+        # @yieldparam option [Array<OptionElement>] option to evaluate
+        # @yieldreturn [Boolean] true if option should be included
+        #
+        # @return [ConditionNode] limited node
+        #
+        # @raise [ArgumentError] if both simplified arguments and block given
+        #
+        # @example Block form
+        #   grammar = (a | b).repeat.limit { |o|
+        #     o.collect { |e| e.attributes[:size] }.sum == 3
+        #   }
+        #
+        # @example Simplified form
+        #   grammar = (a | b).repeat.limit(:size, :sum, :==, 3)
         def limit(attribute = nil, after_collect_operation = nil, comparison_method = nil, comparison_value = nil, &block)
           raise ArgumentError, 'Cannot use simplified arguments and yield block at the same time' if (attribute || after_collect_operation || comparison_method || comparison_value) && @block
 
@@ -63,12 +275,61 @@ module Musa
           ConditionNode.new(self, &block)
         end
 
+        # Creates sequence of this node followed by another.
+        #
+        # Generates options with this node's content followed by the other's.
+        #
+        # @param other [Node] node to follow
+        #
+        # @return [NextNode] sequence node
+        #
+        # @example
+        #   a = N('a')
+        #   b = N('b')
+        #   ab = a.next(b)  # or a + b
         def next(other)
           NextNode.new(self, other)
         end
 
         alias_method :+, :next
 
+        # Generates all options from this grammar node.
+        #
+        # Produces all valid combinations matching the grammar definition.
+        # Can filter with condition and control output format.
+        #
+        # @param attribute [Symbol, nil] attribute for filtering (simplified)
+        # @param after_collect_operation [Symbol, nil] operation on collected values
+        # @param comparison_method [Symbol, nil] comparison method
+        # @param comparison_value [Object, nil] value to compare against
+        # @param raw [Boolean] if true, return raw OptionElement arrays
+        # @param content [Symbol] how to extract content (:itself, :join, etc.)
+        #
+        # @yieldparam option [Array<OptionElement>] option to evaluate
+        # @yieldreturn [Boolean] true if option should be included
+        #
+        # @return [Array] generated options
+        #
+        # @raise [ArgumentError] if simplified arguments and block both given
+        # @raise [ArgumentError] if raw and content both specified
+        #
+        # @example Basic usage
+        #   grammar = (a | b).repeat(2)
+        #   grammar.options
+        #   # => [["a", "a"], ["a", "b"], ["b", "a"], ["b", "b"]]
+        #
+        # @example With content formatting
+        #   grammar.options(content: :join)
+        #   # => ["aa", "ab", "ba", "bb"]
+        #
+        # @example With filtering
+        #   grammar.options { |o| o.size == 2 }
+        #
+        # @example Simplified filtering
+        #   grammar.options(:size, :sum, :<=, 4, content: :join)
+        #
+        # @example Raw OptionElements
+        #   grammar.options(raw: true)
         def options(attribute = nil,
                     after_collect_operation = nil,
                     comparison_method = nil,
@@ -92,16 +353,34 @@ module Musa
           end
         end
 
+        # Counts number of options generated by this node.
+        #
+        # @return [Integer] option count
         def size
           options.size
         end
 
         alias_method :length, :size
 
+        # Gets option at index as series node.
+        #
+        # @param index [Integer] option index
+        #
+        # @return [Node] option converted to node
         def [](index)
           options[index].to_serie.to_node
         end
 
+        # Converts options to series.
+        #
+        # Generates options and converts them to a {Musa::Series::Serie}.
+        #
+        # @param flatten [Boolean] flatten nested series
+        #
+        # @yieldparam option [Array<OptionElement>] option to evaluate
+        # @yieldreturn [Boolean] true if option should be included
+        #
+        # @return [Musa::Series::Serie] series of options
         def to_serie(flatten: true, &condition)
           serie = _options(&condition).collect { |o| o.collect(&:content) }.to_serie(of_series: true).merge
           serie = serie.flatten if flatten
@@ -111,6 +390,16 @@ module Musa
 
         alias_method :s, :to_serie
 
+        # Internal method to generate option arrays.
+        #
+        # @param parent [Array<OptionElement>, nil] parent elements
+        #
+        # @yieldparam option [Array<OptionElement>] option to evaluate
+        # @yieldreturn [Boolean] true if option should be included
+        #
+        # @return [Array<Array<OptionElement>>] option arrays
+        #
+        # @api private
         def _options(parent: nil, &condition)
           raise NotImplementedError
         end
@@ -132,23 +421,43 @@ module Musa
         end
       end
 
+      # Proxy node for recursive grammar references.
+      #
+      # Acts as placeholder that delegates to assigned node.
+      # Enables recursive and self-referential grammars.
+      #
+      # @api private
       class ProxyNode < Node
+        # @return [Node, nil] assigned node
         attr_accessor :node
 
+        # @api private
         def _options(parent: nil, &condition)
           @node._options parent: parent, &condition
         end
       end
 
+      # Terminal node with fixed content.
+      #
+      # Represents a leaf node in the grammar tree with constant content.
+      #
+      # @attr_reader content [Object] node content
+      # @attr_reader attributes [Hash] node attributes
+      #
+      # @api private
       class FinalNode < Node
         attr_reader :content
         attr_reader :attributes
 
+        # @param content [Object] node content
+        # @param attributes [Hash] node attributes
+        # @api private
         def initialize(content, attributes)
           super()
           @element = OptionElement.new(content, attributes)
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -164,12 +473,22 @@ module Musa
         end
       end
 
+      # Node with dynamic content generated by block.
+      #
+      # Executes block at generation time to produce content.
+      # Block receives parent elements and attributes.
+      #
+      # @api private
       class BlockNode < Node
+        # @param attributes [Hash] node attributes
+        # @yield [parent, attributes] block to generate content
+        # @api private
         def initialize(attributes, &block)
           @attributes = attributes
           @block = block
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -188,12 +507,22 @@ module Musa
         end
       end
 
+      # Node that filters child node options by condition.
+      #
+      # Applies condition block to filter generated options.
+      # Created by {Node#limit}.
+      #
+      # @api private
       class ConditionNode < Node
+        # @param node [Node] node to filter
+        # @yield [option] condition block
+        # @api private
         def initialize(node, &block)
           @node = node
           @block = block
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -207,13 +536,23 @@ module Musa
         end
       end
 
+      # Node representing alternation between two nodes.
+      #
+      # Generates options from either node1 or node2.
+      # Created by {Node#or} or `|` operator.
+      #
+      # @api private
       class OrNode < Node
+        # @param node1 [Node] first alternative
+        # @param node2 [Node] second alternative
+        # @api private
         def initialize(node1, node2)
           @node1 = node1
           @node2 = node2
           super()
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -231,13 +570,23 @@ module Musa
         end
       end
 
+      # Node representing sequence of two nodes.
+      #
+      # Generates options with node followed by after.
+      # Created by {Node#next} or `+` operator.
+      #
+      # @api private
       class NextNode < Node
+        # @param node [Node] first node in sequence
+        # @param after [Node] node to follow
+        # @api private
         def initialize(node, after)
           @node = node
           @after = after
           super()
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -251,7 +600,16 @@ module Musa
         end
       end
 
+      # Node representing repetition of a node.
+      #
+      # Generates options with different repetition counts.
+      # Created by {Node#repeat}.
+      #
+      # @api private
       class RepeatNode < Node
+        # @param node [Node] node to repeat
+        # @param max [Integer, nil] maximum repetitions (nil = infinite)
+        # @api private
         def initialize(node, max = nil)
           @node = node
           @max = max
@@ -259,6 +617,7 @@ module Musa
           super()
         end
 
+        # @api private
         def _options(parent: nil, depth: nil, &condition)
           parent ||= []
           depth ||= 0

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

@@ -1,13 +1,118 @@
 require_relative '../series'
 
 module Musa
-
-  # TODO: adapt to series prototyping
-
+  
+  
+  # Markov chain generator for stochastic sequence generation.
+  #
+  # Implements Markov chains that generate sequences of states based on
+  # probabilistic transition rules. Each state transitions to the next
+  # based on defined probabilities, creating pseudo-random but structured
+  # sequences.
+  #
+  # ## Theory
+  #
+  # A Markov chain is a stochastic model describing a sequence of possible
+  # events where the probability of each event depends only on the state
+  # attained in the previous event (memoryless property).
+  #
+  # ## Transition Types
+  #
+  # - **Array**: Equal probability between all options
+  #   - `{ a: [:b, :c] }` → 50% chance of :b, 50% chance of :c
+  #
+  # - **Hash**: Weighted probabilities
+  #   - `{ a: { b: 0.2, c: 0.8 } }` → 20% :b, 80% :c
+  #   - Probabilities are normalized (don't need to sum to 1.0)
+  #
+  # - **Proc**: Algorithmic transitions based on history
+  #   - `{ a: proc { |history| history.size.even? ? :b : :c } }`
+  #   - Proc receives full history and returns next state
+  #
+  # ## Musical Applications
+  #
+  # - Generate melodic sequences with style-based transitions
+  # - Create rhythmic patterns with probabilistic variation
+  # - Produce chord progressions with weighted likelihood
+  # - Build dynamic musical structures with emergent behavior
+  #
+  # @example Equal probability transitions
+  #   markov = Musa::Markov::Markov.new(
+  #     start: :a,
+  #     finish: :x,
+  #     transitions: {
+  #       a: [:b, :c],      # 50/50 chance
+  #       b: [:a, :c],
+  #       c: [:a, :b, :x]
+  #     }
+  #   ).i
+  #
+  #   markov.to_a  # => [:a, :c, :b, :a, :b, :c, :x]
+  #
+  # @example Weighted probability transitions
+  #   markov = Musa::Markov::Markov.new(
+  #     start: :a,
+  #     finish: :x,
+  #     transitions: {
+  #       a: { b: 0.2, c: 0.8 },  # 20% b, 80% c
+  #       b: { a: 0.3, c: 0.7 },  # 30% a, 70% c
+  #       c: [:a, :b, :x]         # Equal probability
+  #     }
+  #   ).i
+  #
+  # @example Algorithmic transitions with history
+  #   markov = Musa::Markov::Markov.new(
+  #     start: :a,
+  #     finish: :x,
+  #     transitions: {
+  #       a: { b: 0.2, c: 0.8 },
+  #       # Transition based on history length
+  #       b: proc { |history| history.size.even? ? :a : :c },
+  #       c: [:a, :b, :x]
+  #     }
+  #   ).i
+  #
+  # @example Musical pitch transitions
+  #   # Create melodic sequence with style-based transitions
+  #   melody = Musa::Markov::Markov.new(
+  #     start: 60,  # Middle C
+  #     finish: nil,  # Infinite
+  #     transitions: {
+  #       60 => { 62 => 0.4, 64 => 0.3, 59 => 0.3 },  # C → D/E/B
+  #       62 => { 60 => 0.3, 64 => 0.4, 67 => 0.3 },  # D → C/E/G
+  #       64 => [60, 62, 65, 67],                      # E → C/D/F/G
+  #       # ... more transitions
+  #     }
+  #   ).i.max_size(16).to_a
+  #
+  # @see Musa::Series::Serie Series interface for chaining operations
+  # @see Musa::Extension::SmartProcBinder Smart procedure binding for history-based transitions
+  # @see https://en.wikipedia.org/wiki/Markov_chain Markov chain (Wikipedia)
+  # @see https://en.wikipedia.org/wiki/Stochastic_process Stochastic process (Wikipedia)
+  # @see https://en.wikipedia.org/wiki/Markov_chain#Music Markov chains in music (Wikipedia)
   module Markov
+    # Markov chain serie generator.
+    #
+    # Generates sequences of states following probabilistic transition rules.
+    # Implements {Musa::Series::Serie} interface for integration with series operations.
     class Markov
+      # TODO: adapt to series prototyping
       include Musa::Series::Serie.base
 
+      # Creates Markov chain generator.
+      #
+      # @param transitions [Hash] state transition rules
+      #   Keys are states, values are next state definitions (Array, Hash, or Proc)
+      # @param start [Object] initial state
+      # @param finish [Object, nil] terminal state (nil for infinite)
+      # @param random [Random, Integer, nil] random number generator or seed
+      #
+      # @example
+      #   markov = Markov.new(
+      #     transitions: { a: [:b, :c], b: [:a, :c], c: [:a, :b, :x] },
+      #     start: :a,
+      #     finish: :x
+      #   )
       def initialize(transitions:, start:, finish: nil, random: nil)
         @transitions = transitions.clone.freeze
 
@@ -23,17 +128,39 @@ module Musa
         init
       end
 
+      # @return [Object] starting state
       attr_accessor :start
+
+      # @return [Object, nil] finishing state (nil for infinite)
       attr_accessor :finish
+
+      # @return [Random] random number generator
       attr_accessor :random
+
+      # @return [Hash] transition rules (frozen)
       attr_accessor :transitions
 
+      # Initializes serie instance state.
+      #
+      # @api private
       private def _init
         @current = nil
         @finished = false
         @history = []
       end
 
+      # Generates next value in Markov chain.
+      #
+      # Selects next state based on current state's transition rules.
+      # Handles Array (equal probability), Hash (weighted), and Proc (algorithmic)
+      # transitions.
+      #
+      # @return [Object, nil] next state, or nil if finished
+      #
+      # @raise [RuntimeError] if no transition defined for current state
+      # @raise [ArgumentError] if transition type is not Array, Hash, or Proc
+      #
+      # @api private
       private def _next_value
         if @finished
           @current = nil
@@ -75,6 +202,9 @@ module Musa
         @current
       end
 
+      # Checks if Markov chain is infinite.
+      #
+      # @return [Boolean] true if no finish state defined
       def infinite?
         @finish.nil?
       end