parsanol 1.3.13-arm-linux

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,122 @@
+# frozen_string_literal: true
+
+# Represents a cause why a parse did fail. Stores information about
+# parse failure including:
+# - message: Human-readable error description
+# - source: The source object being parsed
+# - position: Byte position where error occurred
+# - children: Nested causes (for deeper context)
+#
+# @example
+#   cause = Parsanol::Cause.new(
+#     "Expected at least one",
+#     source,
+#     5
+#   )
+#   cause.children  # => []
+#   cause.to_s  # => "Expected at least one"
+#
+module Parsanol
+  class Cause
+    # @return [Array<String>] Error message parts
+    attr_reader :message
+
+    # @return [Parsanol::Source] Source being parsed
+    attr_reader :source
+
+    # @return [Integer] Byte position where error occurred
+    attr_reader :position
+
+    # Alias for position (API compatibility)
+    alias pos position
+
+    # @return [Array<Cause>] Child causes
+    attr_reader :children
+
+    # Creates a new cause for parse failure
+    #
+    # @param message [String, Array<String>] Error description
+    # @param source [Parsanol::Source] Source being parsed
+    # @param position [Integer] Byte position where error occurred
+    # @param children [Array<Cause>] Nested causes (optional)
+    def initialize(message, source, position, children = [])
+      @message = Array(message)
+      @source = source
+      @position = position
+      @children = children.nil? ? [] : children
+      @parsing_label = nil
+    end
+
+    # Factory method for creating a cause
+    #
+    # @param source [Parsanol::Source] source being parsed
+    # @param position [Integer] Byte position where error occurred
+    # @param message [String, Array<String>] Error description
+    # @param children [Array<Cause>] Nested causes
+    # @return [Cause] New cause instance
+    def self.format(source, position, message, children = [])
+      new(message, source, position, children)
+    end
+
+    # Associates a label with this cause for parsing context
+    #
+    # @param label [String] Description of what was being parsed
+    # @return [void]
+    def set_label(label)
+      @parsing_label = " while parsing #{label}"
+      @children.each { |c| c.set_label(label) }
+    end
+
+    # Formats this cause as a human-readable string
+    #
+    # @return [String] Formatted error message
+    def to_s
+      line_num, col_num = @source.line_and_column(@position)
+
+      formatted_msg = @message.map do |msg|
+        msg.respond_to?(:to_slice) ? msg.content.inspect : msg.to_s
+      end.join
+
+      "#{formatted_msg} at line #{line_num} char #{col_num}#{@parsing_label}."
+    end
+
+    # Generates a tree-style visualization of error causes
+    #
+    # @return [String] ASCII tree representation
+    def ascii_tree
+      output = StringIO.new
+      build_tree_recursive(self, output, [true])
+      output.string
+    end
+
+    # Raises a ParseFailed exception with this cause's information
+    #
+    # @raise [Parsanol::ParseFailed] Always
+    def raise
+      exc = Parsanol::ParseFailed.new(to_s, self)
+      Kernel.raise exc
+    end
+
+    private
+
+    def build_tree_recursive(node, stream, prefix_flags)
+      render_prefix(stream, prefix_flags)
+      stream.puts node.to_s
+
+      node.children.each do |child|
+        is_last_child = (node.children.last == child)
+        build_tree_recursive(child, stream, prefix_flags + [is_last_child])
+      end
+    end
+
+    def render_prefix(stream, prefix_flags)
+      return if prefix_flags.size < 2
+
+      prefix_flags[1..-2].each do |is_last|
+        stream.print is_last ? "   " : "|  "
+      end
+
+      stream.print prefix_flags.last ? "`- " : "|- "
+    end
+  end
+end

data/lib/parsanol/context.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Execution context for tree transformation rules.
+# Provides a clean interface for accessing bound variables within transformation blocks.
+#
+# @example
+#   ctx = Parsanol::Context.new(name: 'Alice', value: 42)
+#   ctx.instance_eval { name }  # => 'Alice'
+#   ctx.instance_eval { @value }  # => 42
+#
+# Inspired by Parslet (MIT License).
+module Parsanol
+  class Context
+    include Parsanol
+
+    # Creates a new context with the given bindings.
+    # Each binding becomes accessible as both a method and an instance variable.
+    #
+    # @param bindings [Hash] variable name => value pairs
+    def initialize(bindings)
+      bindings.each_pair do |key, val|
+        # Define accessor method on singleton class
+        define_singleton_method(key) { val }
+        # Also set as instance variable for @-style access
+        instance_variable_set("@#{key}", val)
+      end
+    end
+
+    private
+
+    # Defines a method on the object's singleton class.
+    #
+    # @param name [Symbol, String] method name
+    # @yield block to execute when method is called
+    def define_singleton_method(name, &)
+      singleton_class.define_method(name, &)
+    end
+  end
+end

data/lib/parsanol/convenience.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Debug helper for parser development.
+# Adds a convenient method to Parsanol::Atoms::Base for debugging parse failures.
+#
+# @example
+#   class MyParser < Parsanol::Parser
+#     rule(:foo) { str('foo') }
+#     root(:foo)
+#   end
+#
+#   # Instead of writing rescue blocks:
+#   MyParser.new.parse_with_debug('invalid')
+#   # Prints the error tree automatically and returns nil
+#
+# Inspired by Parslet (MIT License).
+module Parsanol
+  module Atoms
+    class Base
+      # Parses input and automatically displays error information on failure.
+      # This is a convenience method for development and debugging.
+      # Unlike #parse, this method catches ParseFailed and prints debug info.
+      #
+      # @param input [String] the input to parse
+      # @param options [Hash] options passed to #parse
+      # @return [Object] parse result on success, nil on failure
+      def parse_with_debug(input, options = {})
+        parse(input, options)
+      rescue Parsanol::ParseFailed => e
+        # Display the error tree for debugging
+        puts e.parse_failure_cause.ascii_tree
+        nil
+      end
+    end
+  end
+end

data/lib/parsanol/edit_tracker.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# 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).
+#
+module Parsanol
+  class 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.positive?
+          "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.zero?
+
+        # 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.negative? || 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
+end