parsanol 3.0.0

data/lib/parsanol/builder_callbacks.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Module for streaming builder callbacks.
+  # Include this module in your builder class to receive callbacks
+  # during single-pass parsing with the streaming builder API.
+  #
+  # The streaming builder API allows maximum performance by eliminating
+  # intermediate AST construction. Instead, callbacks are invoked as
+  # parsing progresses, allowing you to construct custom output directly.
+  #
+  # @example Basic string collector
+  #   class StringCollector
+  #     include Parsanol::BuilderCallbacks
+  #
+  #     def initialize
+  #       @strings = []
+  #     end
+  #
+  #     def on_string(value, offset, length)
+  #       @strings << value
+  #     end
+  #
+  #     def finish
+  #       @strings
+  #     end
+  #   end
+  #
+  #   grammar = Parsanol::Native.serialize_grammar(parser.root)
+  #   builder = StringCollector.new
+  #   result = Parsanol::Native.parse_with_builder(grammar, input, builder)
+  #   # result: ["hello", "world"]
+  #
+  # @example Building a typed AST
+  #   class AstBuilder
+  #     include Parsanol::BuilderCallbacks
+  #
+  #     def initialize
+  #       @stack = []
+  #       @current_hash = nil
+  #       @current_key = nil
+  #     end
+  #
+  #     def on_hash_start(size = nil)
+  #       @stack.push(@current_hash) if @current_hash
+  #       @current_hash = {}
+  #     end
+  #
+  #     def on_hash_end(size)
+  #       finished = @current_hash
+  #       @current_hash = @stack.pop
+  #       if @current_hash && @current_key
+  #         @current_hash[@current_key] = finished
+  #         @current_key = nil
+  #       end
+  #       finished
+  #     end
+  #
+  #     def on_hash_key(key)
+  #       @current_key = key
+  #     end
+  #
+  #     def on_string(value, offset, length)
+  #       if @current_hash && @current_key
+  #         @current_hash[@current_key] = value
+  #         @current_key = nil
+  #       end
+  #     end
+  #
+  #     def finish
+  #       @current_hash
+  #     end
+  #   end
+  #
+  module BuilderCallbacks
+    # Called when parsing starts.
+    #
+    # @param input [String] The input being parsed
+    # @return [void]
+    def on_start(input); end
+
+    # Called when parsing succeeds.
+    #
+    # @return [void]
+    def on_success; end
+
+    # Called when parsing fails.
+    #
+    # @param message [String] The error message
+    # @return [void]
+    def on_error(message); end
+
+    # Called when a string value is matched.
+    #
+    # @param value [String] The matched string value
+    # @param offset [Integer] Byte offset in the original input
+    # @param length [Integer] Length of the matched string in bytes
+    # @return [void]
+    def on_string(value, offset, length); end
+
+    # Called when an integer value is matched.
+    #
+    # @param value [Integer] The matched integer value
+    # @return [void]
+    def on_int(value); end
+
+    # Called when a float value is matched.
+    #
+    # @param value [Float] The matched float value
+    # @return [void]
+    def on_float(value); end
+
+    # Called when a boolean value is matched.
+    #
+    # @param value [Boolean] The matched boolean value
+    # @return [void]
+    def on_bool(value); end
+
+    # Called when a nil/null value is matched.
+    #
+    # @return [void]
+    def on_nil; end
+
+    # Called when starting to parse a hash/object.
+    # Use this to initialize state for collecting key-value pairs.
+    #
+    # @param size [Integer, nil] Expected number of entries (may be nil)
+    # @return [void]
+    def on_hash_start(size = nil); end
+
+    # Called when finishing parsing a hash/object.
+    #
+    # @param size [Integer] Actual number of entries
+    # @return [void]
+    def on_hash_end(size); end
+
+    # Called when a hash key is encountered.
+    # The next value callback(s) will provide the value for this key.
+    #
+    # @param key [String] The hash key name
+    # @return [void]
+    def on_hash_key(key); end
+
+    # Called when a hash value is about to be parsed.
+    # Called after on_hash_key for the corresponding value.
+    #
+    # @param key [String] The hash key name
+    # @return [void]
+    def on_hash_value(key); end
+
+    # Called when starting to parse an array.
+    # Use this to initialize state for collecting array elements.
+    #
+    # @param size [Integer, nil] Expected number of elements (may be nil)
+    # @return [void]
+    def on_array_start(size = nil); end
+
+    # Called when an array element is about to be parsed.
+    #
+    # @param index [Integer] The index of the element
+    # @return [void]
+    def on_array_element(index); end
+
+    # Called when finishing parsing an array.
+    #
+    # @param size [Integer] Actual number of elements
+    # @return [void]
+    def on_array_end(size); end
+
+    # Called when starting to parse a named rule.
+    #
+    # @param name [String] The rule name
+    # @return [void]
+    def on_named_start(name); end
+
+    # Called when finishing parsing a named rule.
+    #
+    # @param name [String] The rule name
+    # @return [void]
+    def on_named_end(name); end
+
+    # Called when parsing is complete.
+    # Override this method to return your final constructed result.
+    #
+    # @return [Object] The final result of the builder
+    def finish; end
+  end
+
+  # Built-in builders for common use cases
+  module Builders
+    # Debug builder that collects all events as strings.
+    # Useful for understanding the parsing flow.
+    class DebugBuilder
+      include BuilderCallbacks
+
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      def on_start(input)
+        @events << "start: #{input.inspect}"
+      end
+
+      def on_success
+        @events << "success"
+      end
+
+      def on_error(message)
+        @events << "error: #{message}"
+      end
+
+      def on_string(value, offset, length)
+        @events << "string: #{value.inspect} @ #{offset}(#{length})"
+      end
+
+      def on_int(value)
+        @events << "int: #{value}"
+      end
+
+      def on_float(value)
+        @events << "float: #{value}"
+      end
+
+      def on_bool(value)
+        @events << "bool: #{value}"
+      end
+
+      def on_nil
+        @events << "nil"
+      end
+
+      def on_hash_start(size = nil)
+        @events << "hash_start(#{size.inspect})"
+      end
+
+      def on_hash_end(size)
+        @events << "hash_end(#{size})"
+      end
+
+      def on_hash_key(key)
+        @events << "hash_key: #{key.inspect}"
+      end
+
+      def on_hash_value(key)
+        @events << "hash_value: #{key.inspect}"
+      end
+
+      def on_array_start(size = nil)
+        @events << "array_start(#{size.inspect})"
+      end
+
+      def on_array_element(index)
+        @events << "array_element[#{index}]"
+      end
+
+      def on_array_end(size)
+        @events << "array_end(#{size})"
+      end
+
+      def on_named_start(name)
+        @events << "named_start: #{name}"
+      end
+
+      def on_named_end(name)
+        @events << "named_end: #{name}"
+      end
+
+      def finish
+        @events.join("\n")
+      end
+    end
+
+    # Builder that collects all string values.
+    class StringCollector
+      include BuilderCallbacks
+
+      attr_reader :strings
+
+      def initialize
+        @strings = []
+      end
+
+      def on_start(input); end
+
+      def on_success; end
+
+      def on_error(message); end
+
+      def on_string(value, offset, length)
+        @strings << value
+      end
+
+      def finish
+        @strings
+      end
+    end
+
+    # Builder that counts nodes by type.
+    class NodeCounter
+      include BuilderCallbacks
+
+      attr_reader :counts
+
+      def initialize
+        @counts = Hash.new(0)
+      end
+
+      def on_start(input); end
+
+      def on_success; end
+
+      def on_error(message); end
+
+      def on_string(value, offset, length)
+        @counts[:string] += 1
+      end
+
+      def on_int(value)
+        @counts[:int] += 1
+      end
+
+      def on_float(value)
+        @counts[:float] += 1
+      end
+
+      def on_bool(value)
+        @counts[:bool] += 1
+      end
+
+      def on_nil
+        @counts[:nil] += 1
+      end
+
+      def on_hash_start(size = nil)
+        @counts[:hash] += 1
+      end
+
+      def on_array_start(size = nil)
+        @counts[:array] += 1
+      end
+
+      def on_named_start(name)
+        @counts[:named] += 1
+      end
+
+      def finish
+        @counts
+      end
+    end
+  end
+end

data/lib/parsanol/cause.rb

@@ -0,0 +1,101 @@
+module Parsanol
+  # Represents a cause why a parse did fail. A lot of these objects are
+  # constructed - not all of the causes turn out to be failures for the whole
+  # parse. 
+  #
+  class Cause
+    def initialize(message, source, pos, children)
+      @message, @source, @pos, @children, @context =
+        message, source, pos, children, nil
+    end
+    
+    # @return [String, Array] A string or an array of message pieces that 
+    #   provide failure information. Use #to_s to get a formatted string.
+    attr_reader :message
+    
+    # @return [Parsanol::Source] Source that was parsed when this error 
+    #   happend. Mainly used for line number information.
+    attr_reader :source
+    
+    # Location of the error. 
+    #
+    # @return [Fixnum] Position where the error happened. (character offset)
+    attr_reader :pos 
+    
+    # When this cause is part of a tree of error causes: child nodes for this
+    # node. Very often carries the reasons for this cause. 
+    #
+    # @return [Array<Parsanol::Cause>] A list of reasons for this cause. 
+    def children
+      @children ||= []
+    end
+    
+    # Appends 'at line LINE char CHAR' to the string given. Use +pos+ to
+    # override the position of the +source+. This method returns an object
+    # that can be turned into a string using #to_s.
+    #
+    # @param source [Parsanol::Source] source that was parsed when this error
+    #   happened 
+    # @param pos [Fixnum] position of error
+    # @param str [String, Array<String>] message parts
+    # @param children [Array<Parsanol::Cause>] child nodes for this error tree
+    # @return [Parsanol::Cause] a new instance of {Parsanol::Cause}
+    #
+    def self.format(source, pos, str, children=[])
+      self.new(str, source, pos, children)
+    end
+
+    # Update error message to include context provided by label
+    # Update all child causes too (the same context applies to all causes)
+    def set_label(l)
+      @context = " when parsing #{l}"
+      children.each { |c| c.set_label(l) }
+    end
+
+    def to_s
+      line, column = source.line_and_column(pos)
+      # Allow message to be a list of objects. Join them here, since we now
+      # really need it.
+      Array(message).map { |o|
+        o.respond_to?(:to_slice) ?
+          o.str.inspect :
+          o.to_s }.join + " at line #{line} char #{column}#{@context}."
+    end
+    
+    # Signals to the outside that the parse has failed. Use this in
+    # conjunction with .format for nice error messages. 
+    #
+    def raise(exception_klass=Parsanol::ParseFailed)
+      exception = exception_klass.new(self.to_s, self)
+      Kernel.raise exception
+    end
+
+    # Returns an ascii tree representation of the causes of this node and its
+    # children. 
+    #
+    def ascii_tree
+      StringIO.new.tap { |io| 
+        recursive_ascii_tree(self, io, [true]) }.
+        string
+    end
+
+  private
+    def recursive_ascii_tree(node, stream, curved)
+      append_prefix(stream, curved)
+      stream.puts node.to_s
+
+      node.children.each do |child|
+        last_child = (node.children.last == child)
+
+        recursive_ascii_tree(child, stream, curved + [last_child])
+      end
+    end
+    def append_prefix(stream, curved)
+      return if curved.size < 2
+      curved[1..-2].each do |c|
+        stream.print c ? "   " : "|  "
+      end
+      stream.print curved.last ? "`- " : "|- "
+    end
+  end
+end

data/lib/parsanol/context.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Provides a context for tree transformations to run in. The context allows
+# accessing each of the bindings in the bindings hash as local method.
+#
+# Example: 
+#
+#   ctx = Context.new(:a => :b)
+#   ctx.instance_eval do 
+#     a # => :b
+#   end
+#
+# @api private
+class Parsanol::Context
+  include Parsanol
+
+  def initialize(bindings)
+    bindings.each do |key, value|
+      singleton_class.send(:define_method, key) { value }
+      instance_variable_set("@#{key}", value)
+    end
+  end
+end

data/lib/parsanol/convenience.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class Parsanol::Atoms::Base
+  
+  # Packages the common idiom
+  #    
+  #    begin
+  #      tree = parser.parse('something')
+  #    rescue Parsanol::ParseFailed => error
+  #      puts parser.parse_failure_cause.ascii_tree
+  #    end
+  #
+  # into a convenient method.
+  #
+  # Usage:
+  #   
+  #   require 'parslet'
+  #   require 'parsanol/convenience'
+  #   
+  #   class FooParser < Parsanol::Parser
+  #     rule(:foo) { str('foo') }
+  #     root(:foo)
+  #   end
+  #   
+  #   FooParser.new.parse_with_debug('bar')
+  #
+  # @see Parsanol::Atoms::Base#parse
+  #
+  def parse_with_debug str, opts={}
+    parse str, opts
+  rescue Parsanol::ParseFailed => error
+    puts error.parse_failure_cause.ascii_tree
+  end
+
+end

data/lib/parsanol/edit_tracker.rb

@@ -0,0 +1,107 @@
+# Edit tracking for GPeg-style incremental parsing
+# Based on the GPeg paper: "Fast Incremental PEG Parsing" (Yedidia, SLE 2021)
+#
+# Tracks edits to the input as [position, delta] pairs and enables lazy shifting
+# of cached intervals without rebuilding the entire cache (O(1) edit cost).
+#
+class Parsanol::EditTracker
+  # An edit operation: insertion (+delta) or deletion (-delta) at a position
+  class Edit
+    attr_reader :position, :delta
+
+    def initialize(position, delta)
+      @position = position
+      @delta = delta
+    end
+
+    def to_s
+      if @delta > 0
+        "Insert(#{@delta} chars at #{@position})"
+      else
+        "Delete(#{-@delta} chars at #{@position})"
+      end
+    end
+  end
+
+  def initialize
+    @edits = []  # List of edits in chronological order
+  end
+
+  # Record an insertion at position
+  # @param position [Integer] Where the insertion occurred
+  # @param length [Integer] Number of characters inserted
+  def insert(position, length)
+    @edits << Edit.new(position, length)
+  end
+
+  # Record a deletion at position
+  # @param position [Integer] Where the deletion occurred
+  # @param length [Integer] Number of characters deleted
+  def delete(position, length)
+    @edits << Edit.new(position, -length)
+  end
+
+  # Shift an interval based on accumulated edits
+  # Returns the shifted interval [low', high') or nil if interval is invalidated
+  #
+  # An interval is invalidated if any edit overlaps with it, as the cached
+  # parse result is no longer valid.
+  #
+  # @param low [Integer] Interval start position
+  # @param high [Integer] Interval end position (exclusive)
+  # @return [Array<Integer>, nil] Shifted [low, high) or nil if invalidated
+  def shift_interval(low, high)
+    shifted_low = low
+    shifted_high = high
+
+    @edits.each do |edit|
+      # Skip zero-length edits (no-ops)
+      next if edit.delta == 0
+
+      # Check if edit overlaps with current interval
+      # Edit overlaps if it occurs within [shifted_low, shifted_high)
+      if edit.position >= shifted_low && edit.position < shifted_high
+        # Edit inside interval - invalidate
+        return nil
+      elsif edit.position < shifted_low
+        # Edit before interval - shift both boundaries
+        shifted_low += edit.delta
+        shifted_high += edit.delta
+      elsif edit.position >= shifted_high
+        # Edit after interval - no shift needed
+        # Continue to next edit
+      end
+
+      # Sanity check: ensure interval remains valid
+      return nil if shifted_low < 0 || shifted_high < shifted_low
+    end
+
+    [shifted_low, shifted_high]
+  end
+
+  # Check if interval needs invalidation (overlaps with any edit)
+  # @param low [Integer] Interval start position
+  # @param high [Integer] Interval end position (exclusive)
+  # @return [Boolean] true if interval should be invalidated
+  def invalidates?(low, high)
+    shift_interval(low, high).nil?
+  end
+
+  # Clear all recorded edits
+  def clear
+    @edits.clear
+  end
+
+  # Number of edits tracked
+  def size
+    @edits.size
+  end
+
+  # Check if any edits have been recorded
+  def empty?
+    @edits.empty?
+  end
+
+  # Get all edits (for debugging)
+  attr_reader :edits
+end