parsanol 3.0.0

data/lib/parsanol/result_builder.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Base class for efficient result construction.
+  #
+  # ResultBuilder provides specialized construction patterns that avoid
+  # intermediate array allocations by building results directly.
+  #
+  # == Usage
+  #
+  #   builder = ResultBuilder.for(:repetition, context, estimated_size: 10)
+  #   builder.add_element(value1)
+  #   builder.add_element(value2)
+  #   result = builder.build  # Returns LazyResult
+  #
+  # == Builders
+  #
+  # - RepetitionBuilder: For repetition results
+  # - SequenceBuilder: For sequence results
+  # - HashBuilder: For named capture results
+  #
+  class ResultBuilder
+    # Factory method to create appropriate builder.
+    #
+    # @param type [Symbol] Builder type (:repetition, :sequence, :hash)
+    # @param context [Context] Parse context
+    # @param options [Hash] Builder options
+    # @return [ResultBuilder] Appropriate builder instance
+    #
+    def self.for(type, context, **options)
+      case type
+      when :repetition
+        RepetitionBuilder.new(context, **options)
+      when :sequence
+        SequenceBuilder.new(context, **options)
+      when :hash
+        HashBuilder.new(context, **options)
+      else
+        raise ArgumentError, "Unknown builder type: #{type}"
+      end
+    end
+
+    # Initialize builder.
+    #
+    # @param context [Context] Parse context for buffer access
+    #
+    def initialize(context)
+      @context = context
+    end
+
+    # Add element to result (subclasses implement).
+    #
+    # @param value [Object] Value to add
+    # @return [self] For method chaining
+    #
+    def add_element(value)
+      raise NotImplementedError
+    end
+
+    # Build final result (subclasses implement).
+    #
+    # @return [Object] Constructed result
+    #
+    def build
+      raise NotImplementedError
+    end
+
+    # Release resources (subclasses implement).
+    #
+    # @return [void]
+    #
+    def release
+      # Default: no-op
+    end
+  end
+
+  # Builder for repetition results.
+  #
+  # Constructs [:repetition, ...] arrays efficiently.
+  #
+  class RepetitionBuilder < ResultBuilder
+    # Initialize repetition builder.
+    #
+    # @param context [Context] Parse context
+    # @param tag [Symbol] Tag to use (default: :repetition)
+    # @param estimated_size [Integer] Estimated element count
+    #
+    def initialize(context, tag: :repetition, estimated_size: 10)
+      super(context)
+      @tag = tag
+      @buffer = context.acquire_buffer(size: estimated_size + 1)
+      @buffer.push(@tag)
+    end
+
+    # Add element to repetition.
+    #
+    # @param value [Object] Element to add
+    # @return [self]
+    #
+    def add_element(value)
+      @buffer.push(value)
+      self
+    end
+
+    # Build LazyResult.
+    #
+    # @return [LazyResult] Lazy repetition result
+    #
+    def build
+      Parsanol::LazyResult.new(@buffer, @context)
+    end
+
+    # Release buffer on failure.
+    #
+    # @return [void]
+    #
+    def release
+      @context.release_buffer(@buffer) if @buffer
+      @buffer = nil
+    end
+  end
+
+  # Builder for sequence results.
+  #
+  # Constructs [:sequence, ...] arrays efficiently.
+  #
+  class SequenceBuilder < ResultBuilder
+    # Initialize sequence builder.
+    #
+    # @param context [Context] Parse context
+    # @param size [Integer] Expected sequence length
+    #
+    def initialize(context, size: 5)
+      super(context)
+      @buffer = context.acquire_buffer(size: size + 1)
+      @buffer.push(:sequence)
+    end
+
+    # Add element to sequence.
+    #
+    # @param value [Object] Element to add
+    # @return [self]
+    #
+    def add_element(value)
+      @buffer.push(value) if value  # Skip nil values
+      self
+    end
+
+    # Build LazyResult.
+    #
+    # @return [LazyResult] Lazy sequence result
+    #
+    def build
+      Parsanol::LazyResult.new(@buffer, @context)
+    end
+
+    # Release buffer on failure.
+    #
+    # @return [void]
+    #
+    def release
+      @context.release_buffer(@buffer) if @buffer
+      @buffer = nil
+    end
+  end
+
+  # Builder for hash results (named captures).
+  #
+  # Constructs hashes directly without intermediate arrays.
+  #
+  class HashBuilder < ResultBuilder
+    # Initialize hash builder.
+    #
+    # @param context [Context] Parse context
+    #
+    def initialize(context)
+      super(context)
+      @hash = {}
+    end
+
+    # Add key-value pair.
+    #
+    # @param key [Symbol] Hash key
+    # @param value [Object] Hash value
+    # @return [self]
+    #
+    def add_pair(key, value)
+      @hash[key] = value
+      self
+    end
+
+    # Build hash result.
+    #
+    # @return [Hash] Constructed hash
+    #
+    def build
+      @hash
+    end
+
+    # Release resources (hash cleanup).
+    #
+    # @return [void]
+    #
+    def release
+      @hash = nil
+    end
+  end
+end

data/lib/parsanol/result_stream.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Streaming result iterator for memory-efficient parsing.
+  #
+  # Provides an Enumerable interface over parse results, allowing
+  # incremental processing without materializing the entire tree.
+  # Uses depth-first traversal to minimize memory usage.
+  #
+  # == Motivation
+  #
+  # Traditional parsing materializes the entire parse tree in memory:
+  #
+  #   results = parser.parse(large_input)  # Full tree in memory
+  #   results.each { |node| process(node) }
+  #
+  # For large inputs, this can consume significant memory. ResultStream
+  # provides lazy iteration without full tree materialization:
+  #
+  #   stream = ResultStream.new(parser.parse(input))
+  #   stream.each { |node| process(node) }  # Processes incrementally
+  #
+  # == Usage
+  #
+  # Basic iteration:
+  #
+  #   stream = ResultStream.new(parse_tree)
+  #   stream.each { |node| puts node }
+  #
+  # Filtering (leverages Enumerable):
+  #
+  #   stream.select { |node| node.is_a?(Hash) }.each { |hash| process(hash) }
+  #
+  # Mapping:
+  #
+  #   transformed = stream.map { |node| transform(node) }
+  #
+  # == Performance Characteristics
+  #
+  # - Memory: O(tree depth) instead of O(tree size)
+  # - Speed: Minimal overhead (~1-2% vs direct iteration)
+  # - Lazy evaluation: Nodes processed on-demand
+  #
+  # == Integration with Parser
+  #
+  # Can be used directly with parse results:
+  #
+  #   parser = MyParser.new
+  #   result = parser.parse(input)
+  #   stream = ResultStream.new(result)
+  #
+  # Or through the optional stream method on Base:
+  #
+  #   stream = parser.stream(input)  # If available
+  #
+  class ResultStream
+    include Enumerable
+
+    # Creates a new result stream.
+    #
+    # @param tree [Object] Parse tree (Hash, Array, or scalar)
+    def initialize(tree)
+      @tree = tree
+    end
+
+    # Iterates over all nodes in the parse tree.
+    # Uses depth-first traversal to minimize memory usage.
+    #
+    # Traversal order:
+    # 1. Current node (pre-order)
+    # 2. Child nodes (recursive)
+    #
+    # This ensures that:
+    # - Only the current path is kept in memory (stack)
+    # - Parent nodes are yielded before children
+    # - Natural processing order for most use cases
+    #
+    # @yield [node] Each node in the tree
+    # @yieldparam node [Object] Current node (Hash, Array, or scalar)
+    # @return [Enumerator] if no block given
+    #
+    # @example Basic iteration
+    #   stream.each { |node| puts node.class }
+    #
+    # @example Lazy enumeration
+    #   enum = stream.each  # Returns Enumerator
+    #   enum.next           # Get next node
+    #
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      traverse(@tree, &block)
+      self
+    end
+
+    # Filters nodes by type.
+    #
+    # @param klass [Class] Class to filter by
+    # @return [Enumerator] Filtered nodes
+    #
+    # @example Get all hash nodes
+    #   stream.nodes_of_type(Hash)
+    #
+    def nodes_of_type(klass)
+      select { |node| node.is_a?(klass) }
+    end
+
+    # Returns all hash nodes in the tree.
+    #
+    # @return [Enumerator] Hash nodes
+    #
+    # @example
+    #   stream.hashes.each { |h| puts h.keys }
+    #
+    def hashes
+      nodes_of_type(Hash)
+    end
+
+    # Returns all array nodes in the tree.
+    #
+    # @return [Enumerator] Array nodes
+    #
+    # @example
+    #   stream.arrays.each { |a| puts a.size }
+    #
+    def arrays
+      nodes_of_type(Array)
+    end
+
+    # Returns all scalar nodes (non-Hash, non-Array).
+    #
+    # @return [Enumerator] Scalar nodes
+    #
+    # @example
+    #   stream.scalars.each { |s| puts s }
+    #
+    def scalars
+      select { |node| !node.is_a?(Hash) && !node.is_a?(Array) }
+    end
+
+    # Returns nodes matching a predicate at a specific depth.
+    #
+    # @param depth [Integer] Tree depth (0 = root)
+    # @yield [node] Predicate to test each node
+    # @return [Enumerator] Matching nodes
+    #
+    # @example Get all nodes at depth 2
+    #   stream.at_depth(2) { true }
+    #
+    def at_depth(target_depth, &predicate)
+      predicate ||= proc { true }
+      depth_traverse(@tree, 0, target_depth, &predicate)
+    end
+
+    # Counts total nodes in the tree.
+    #
+    # @return [Integer] Total node count
+    #
+    # @example
+    #   stream.count  # => 42
+    #
+    def count
+      counter = 0
+      each { counter += 1 }
+      counter
+    end
+
+    # Returns maximum depth of the tree.
+    #
+    # @return [Integer] Maximum depth
+    #
+    # @example
+    #   stream.max_depth  # => 5
+    #
+    def max_depth
+      find_max_depth(@tree, 0)
+    end
+
+    private
+
+    # Depth-first tree traversal with pre-order visiting.
+    #
+    # @param node [Object] Current node
+    # @yield [node] Each visited node
+    #
+    def traverse(node, &block)
+      # Yield current node first (pre-order)
+      yield node
+
+      # Recursively traverse children
+      case node
+      when Array
+        node.each { |item| traverse(item, &block) }
+      when Hash
+        node.each_value { |value| traverse(value, &block) }
+      end
+      # Scalars have no children, stop here
+    end
+
+    # Depth-aware traversal for filtering by level.
+    #
+    # @param node [Object] Current node
+    # @param current_depth [Integer] Current depth in tree
+    # @param target_depth [Integer] Depth to match
+    # @yield [node] Matching nodes at target depth
+    # @return [Enumerator]
+    #
+    def depth_traverse(node, current_depth, target_depth, &block)
+      return enum_for(:depth_traverse, node, current_depth, target_depth) unless block_given?
+
+      # Check if we're at target depth
+      if current_depth == target_depth && yield(node)
+        return [node].to_enum
+      end
+
+      # Recurse to children if not at target depth yet
+      results = []
+      if current_depth < target_depth
+        case node
+        when Array
+          node.each do |item|
+            depth_traverse(item, current_depth + 1, target_depth, &block).each do |result|
+              results << result
+            end
+          end
+        when Hash
+          node.each_value do |value|
+            depth_traverse(value, current_depth + 1, target_depth, &block).each do |result|
+              results << result
+            end
+          end
+        end
+      end
+
+      results.to_enum
+    end
+
+    # Find maximum depth of tree recursively.
+    #
+    # @param node [Object] Current node
+    # @param current_depth [Integer] Current depth
+    # @return [Integer] Maximum depth from this node
+    #
+    def find_max_depth(node, current_depth)
+      max = current_depth
+
+      case node
+      when Array
+        node.each do |item|
+          depth = find_max_depth(item, current_depth + 1)
+          max = depth if depth > max
+        end
+      when Hash
+        node.each_value do |value|
+          depth = find_max_depth(value, current_depth + 1)
+          max = depth if depth > max
+        end
+      end
+
+      max
+    end
+  end
+end

data/lib/parsanol/rig/rspec.rb

@@ -0,0 +1,52 @@
+RSpec::Matchers.define(:parse) do |input, opts|
+  as = block = nil
+  result = trace = nil
+
+  match do |parser|
+    begin
+      result = parser.parse(input)
+      block ? 
+        block.call(result) : 
+        (as == result || as.nil?)
+    rescue Parsanol::ParseFailed => ex
+      trace = ex.parse_failure_cause.ascii_tree if opts && opts[:trace]
+      false
+    end
+  end
+
+  public_send(respond_to?(:failure_message) ? :failure_message : :failure_message_for_should) do |is|
+    if block
+      "expected output of parsing #{input.inspect}" <<
+      " with #{is.inspect} to meet block conditions, but it didn't"
+    else
+      "expected " << 
+        (as ? 
+          "output of parsing #{input.inspect}"<<
+          " with #{is.inspect} to equal #{as.inspect}, but was #{result.inspect}" : 
+          "#{is.inspect} to be able to parse #{input.inspect}") << 
+        (trace ? 
+          "\n"+trace : 
+          '')
+    end
+  end
+
+  public_send(respond_to?(:failure_message_when_negated) ? :failure_message_when_negated : :failure_message_for_should_not) do |is|
+    if block
+      "expected output of parsing #{input.inspect} with #{is.inspect} not to meet block conditions, but it did"
+    else
+      "expected " << 
+        (as ? 
+          "output of parsing #{input.inspect}"<<
+          " with #{is.inspect} not to equal #{as.inspect}" :
+          
+          "#{is.inspect} to not parse #{input.inspect}, but it did")
+    end
+  end
+
+  # NOTE: This has a nodoc tag since the rdoc parser puts this into 
+  # Object, a thing I would never allow. 
+  chain :as do |expected_output=nil, &my_block|
+    as = expected_output
+    block = my_block
+  end
+end

data/lib/parsanol/rope.rb

@@ -0,0 +1,78 @@
+module Parsanol
+  # Rope data structure for efficient string accumulation.
+  #
+  # Uses deferred concatenation to avoid O(n²) repeated string building.
+  # Segments are accumulated in O(1) time and joined once in O(n) time when
+  # converted to a final string.
+  #
+  # @example Basic usage
+  #   rope = Rope.new
+  #   rope.append('hello')
+  #   rope.append(' ')
+  #   rope.append('world')
+  #   rope.to_s  # => "hello world"
+  #
+  # @example With Slices
+  #   rope = Rope.new
+  #   rope.append(Slice.new(0, 'hello'))
+  #   rope.append(Slice.new(5, ' world'))
+  #   rope.to_s  # => "hello world"
+  #
+  class Rope
+    # Creates a new empty Rope.
+    def initialize
+      @segments = []
+      @frozen = false
+    end
+
+    # Appends a string or Slice to the rope.
+    #
+    # This is an O(1) operation. The segment is stored as-is and will be
+    # joined later when {#to_s} is called.
+    #
+    # @param segment [String, Slice] The segment to append
+    # @return [Rope] self for method chaining
+    # @raise [FrozenError] if rope has been frozen by calling {#to_s}
+    def append(segment)
+      raise FrozenError, "can't modify frozen Rope" if @frozen
+      @segments << segment
+      self
+    end
+
+    # Converts the rope to a final string.
+    #
+    # This is an O(n) operation performed once. After calling this method,
+    # the rope is frozen and cannot be modified further.
+    #
+    # @return [String] The concatenated result of all segments
+    def to_s
+      @frozen = true
+      @segments.join
+    end
+
+    # Checks if the rope is empty (contains no segments).
+    #
+    # @return [Boolean] true if no segments have been appended
+    def empty?
+      @segments.empty?
+    end
+
+    # Estimates the total size of all segments.
+    #
+    # This is an estimate because segments may be Slice objects or other
+    # types that respond to #size or #to_s.
+    #
+    # @return [Integer] The sum of all segment sizes
+    def size
+      @segments.sum { |s| s.respond_to?(:size) ? s.size : s.to_s.size }
+    end
+
+    # Creates a rope from an existing string.
+    #
+    # @param str [String] The string to initialize the rope with
+    # @return [Rope] A new rope containing the string
+    def self.from_string(str)
+      new.tap { |r| r.append(str) unless str.empty? }
+    end
+  end
+end

data/lib/parsanol/scope.rb

@@ -0,0 +1,42 @@
+class Parsanol::Scope
+  # Raised when the accessed slot has never been assigned a value. 
+  #
+  class NotFound < StandardError
+  end
+  
+  class Binding
+    attr_reader :parent
+    
+    def initialize(parent=nil)
+      @parent = parent
+      @hash = Hash.new
+    end
+    
+    def [](k)
+      @hash.has_key?(k) && @hash[k] ||
+        parent && parent[k] or 
+        raise NotFound
+    end
+    def []=(k,v)
+      @hash.store(k,v)
+    end
+  end
+  
+  def [](k)
+    @current[k]
+  end
+  def []=(k,v)
+    @current[k] = v
+  end
+  
+  def initialize
+    @current = Binding.new
+  end
+  
+  def push
+    @current = Binding.new(@current)
+  end
+  def pop
+    @current = @current.parent
+  end
+end