musa-dsl 0.30.2 → 0.41.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,45 @@ 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
+      #
+      # @return [void]
       def initialize(content, attributes = nil)
         @content = content
         @attributes = attributes || {}
@@ -26,13 +175,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 +245,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 +277,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 +355,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,12 +392,30 @@ 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
 
         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,
@@ -132,23 +431,46 @@ 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
+        #
+        # @return [void]
+        #
+        # @api private
         def initialize(content, attributes)
           super()
           @element = OptionElement.new(content, attributes)
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -164,12 +486,25 @@ 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
+        #
+        # @return [void]
+        #
+        # @api private
         def initialize(attributes, &block)
           @attributes = attributes
           @block = block
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -188,12 +523,25 @@ 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
+        #
+        # @return [void]
+        #
+        # @api private
         def initialize(node, &block)
           @node = node
           @block = block
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -207,13 +555,26 @@ 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
+        #
+        # @return [void]
+        #
+        # @api private
         def initialize(node1, node2)
           @node1 = node1
           @node2 = node2
           super()
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -231,13 +592,26 @@ 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
+        #
+        # @return [void]
+        #
+        # @api private
         def initialize(node, after)
           @node = node
           @after = after
           super()
         end
 
+        # @api private
         def _options(parent: nil, &condition)
           parent ||= []
 
@@ -251,7 +625,19 @@ 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)
+        #
+        # @return [void]
+        #
+        # @api private
         def initialize(node, max = nil)
           @node = node
           @max = max
@@ -259,6 +645,7 @@ module Musa
           super()
         end
 
+        # @api private
         def _options(parent: nil, depth: nil, &condition)
           parent ||= []
           depth ||= 0