parsanol 1.0.1-aarch64-linux

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

data/lib/parsanol/error_reporter/contextual.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module ErrorReporter
+    # Enhanced error reporter that uses contextual heuristics to provide
+    # more relevant error messages. Builds on the Deepest reporter by adding
+    # label tracking and intelligent error reset behavior.
+    #
+    # The key insight is that in a sequence of alternatives, the deepest error
+    # from a branch that was partially successful is more meaningful than
+    # errors from branches that failed immediately.
+    #
+    # @example Parser with labeled rules
+    #   class MyParser < Parsanol::Parser
+    #     rule(:expression, label: 'math expression') { ... }
+    #     rule(:term, label: 'number or variable') { ... }
+    #   end
+    #
+    #   # Error messages will include "while parsing math expression"
+    #   # context when expression rule fails deep in parsing
+    #
+    # Inspired by contextual error reporting strategies in modern parsers.
+    #
+    class Contextual < Deepest
+      # Creates a new contextual error reporter.
+      #
+      def initialize
+        @prev_success_pos = 0
+        clear_state
+      end
+
+      # Called when a sequence successfully matches. Resets error tracking
+      # if this success is at or beyond the previous success position.
+      # This ensures we keep errors from "partially successful" branches
+      # rather than early failures in alternative choices.
+      #
+      # @param src [Parsanol::Source] input source
+      # @return [nil]
+      #
+      def succ(src)
+        current_pos = src.pos.bytepos
+        # Only reset if we've made forward progress
+        return if current_pos < @prev_success_pos
+
+        @prev_success_pos = current_pos
+        reset
+        nil
+      end
+
+      # Clears all tracked state for a fresh start.
+      #
+      # @return [void]
+      #
+      def reset
+        @deepest_cause = nil
+        @active_label_pos = -1
+        @active_label_text = nil
+      end
+
+      alias clear_state reset
+
+      # Records an error and applies contextual labeling if the atom has one.
+      # Delegates to parent class for deepest tracking.
+      #
+      # @param atom [Parsanol::Atoms::Base] atom that failed
+      # @param src [Parsanol::Source] input source
+      # @param msg [String, Array] error message
+      # @param nested [Array, nil] child causes
+      # @return [Parsanol::Cause] the error cause
+      #
+      def err(atom, src, msg, nested = nil)
+        cause = super
+
+        # Apply label if the atom has one
+        if atom.respond_to?(:label) && (lbl = atom.label)
+          maybe_update_label(lbl, src.pos.bytepos)
+          cause.set_label(@active_label_text)
+        end
+
+        cause
+      end
+
+      # Updates the active context label if the new position is at or
+      # beyond the current label position. This ensures we track the
+      # label for the deepest/most specific failing construct.
+      #
+      # @param lbl [String] label text
+      # @param byte_pos [Integer] position in input
+      # @return [void]
+      #
+      def maybe_update_label(lbl, byte_pos)
+        return unless byte_pos >= @active_label_pos
+
+        @active_label_pos = byte_pos
+        @active_label_text = lbl
+      end
+    end
+  end
+end

data/lib/parsanol/error_reporter/deepest.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module ErrorReporter
+    # Error reporter that tracks the deepest (furthest into input) parse failure.
+    # Unlike Tree reporter which returns the most recent error, this reporter
+    # keeps track of errors at the greatest input position, as these are typically
+    # more useful for diagnosing what went wrong.
+    #
+    # The rationale is that errors occurring later in the input are more likely
+    # to represent what the user intended - early failures often represent
+    # alternative branches that simply didn't match.
+    #
+    # @example
+    #   reporter = Parsanol::ErrorReporter::Deepest.new
+    #   parser.parse(input, reporter: reporter)
+    #   # The error cause will be the one at the furthest input position
+    #
+    # Inspired by "furthest failure" error reporting strategies in parser tools.
+    #
+    class Deepest < Base
+      # @return [Parsanol::Cause, nil] the deepest cause encountered so far
+      attr_reader :deepest_cause
+
+      # Creates a new deepest error reporter.
+      #
+      def initialize
+        @deepest_cause = nil
+      end
+
+      # Records an error at the current source position.
+      # Updates the tracked deepest cause if this error is further into input.
+      #
+      # @param atom [Parsanol::Atoms::Base] atom that failed
+      # @param source [Parsanol::Source] input source
+      # @param message [String, Array] error message
+      # @param children [Array, nil] child error causes
+      # @return [Parsanol::Cause] the deepest known error cause
+      #
+      def err(_atom, source, message, children = nil)
+        error_pos = source.pos
+        cause = Cause.format(source, error_pos, message, children)
+        deepest(cause)
+      end
+
+      # Records an error at a specific source position.
+      # Updates the tracked deepest cause if this error is further into input.
+      #
+      # @param atom [Parsanol::Atoms::Base] atom that failed
+      # @param source [Parsanol::Source] input source
+      # @param message [String, Array] error message
+      # @param pos [Integer] byte position of error
+      # @param children [Array, nil] child error causes
+      # @return [Parsanol::Cause] the deepest known error cause
+      #
+      def err_at(_atom, source, message, pos, children = nil)
+        cause = Cause.format(source, pos, message, children)
+        deepest(cause)
+      end
+
+      # Notification of successful parse (unused in this reporter).
+      #
+      # @param source [Parsanol::Source] input source
+      # @return [nil]
+      #
+      def succ(_source)
+        nil
+      end
+
+      # Evaluates a cause and returns the deepest known cause.
+      # If the given cause is deeper than the currently tracked deepest,
+      # updates tracking and returns the given cause. Otherwise returns
+      # the previously tracked deepest cause.
+      #
+      # @param cause [Parsanol::Cause] error cause to evaluate
+      # @return [Parsanol::Cause] the deepest known cause
+      #
+      def deepest(cause)
+        # Find the deepest leaf in the cause tree
+        _, leaf = find_deepest_leaf(cause)
+
+        # Update tracking if this goes deeper than what we've seen
+        if !@deepest_cause || leaf.pos >= @deepest_cause.pos
+          @deepest_cause = leaf
+          return cause
+        end
+
+        @deepest_cause
+      end
+
+      private
+
+      # Recursively finds the leaf node with the greatest depth (rank) in
+      # the error tree. The deepest leaf is the one furthest from root.
+      #
+      # @param node [Parsanol::Cause] current node in error tree
+      # @param rank [Integer] current depth from root
+      # @return [Array<Integer, Parsanol::Cause>] [depth, deepest_leaf]
+      #
+      def find_deepest_leaf(node, rank = 0)
+        best_node = node
+        best_rank = rank
+
+        kids = node.children
+        if kids && !kids.empty?
+          kids.each do |kid|
+            kid_rank, kid_node = find_deepest_leaf(kid, rank + 1)
+
+            if kid_rank > best_rank
+              best_rank = kid_rank
+              best_node = kid_node
+            end
+          end
+        end
+
+        [best_rank, best_node]
+      end
+    end
+  end
+end

data/lib/parsanol/error_reporter/tree.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module ErrorReporter
+    # Default error reporter that builds a hierarchical tree of failure causes.
+    # Each parse failure creates a Cause node that can contain child causes
+    # from nested parse attempts.
+    #
+    # The resulting error tree mirrors the grammar structure, making it easy
+    # to understand which parts of the grammar failed and why.
+    #
+    # @example
+    #   reporter = Parsanol::ErrorReporter::Tree.new
+    #   parser.parse(input, reporter: reporter)
+    #   # On failure, causes are available for inspection
+    #
+    # Inspired by error tree reporting patterns in parser generators.
+    #
+    class Tree < Base
+      # Records a parse failure at the current source position.
+      # Creates a Cause node that may contain child causes from deeper
+      # parsing levels.
+      #
+      # @param parser_atom [Parsanol::Atoms::Base] atom that failed to match
+      # @param src [Parsanol::Source] input source being parsed
+      # @param msg [String, Array<String>] error description
+      # @param nested_errors [Array<Cause>, nil] failures from inner parse attempts
+      # @return [Parsanol::Cause] error cause node for this failure
+      #
+      def err(_parser_atom, src, msg, nested_errors = nil)
+        error_pos = src.pos
+        Cause.format(src, error_pos, msg, nested_errors)
+      end
+
+      # Records a parse failure at a specific position (not current position).
+      # Used when the error occurred at a different location than where it's
+      # being reported.
+      #
+      # @param parser_atom [Parsanol::Atoms::Base] atom that failed to match
+      # @param src [Parsanol::Source] input source being parsed
+      # @param msg [String, Array<String>] error description
+      # @param error_pos [Integer] byte position where error actually occurred
+      # @param nested_errors [Array<Cause>, nil] failures from inner parse attempts
+      # @return [Parsanol::Cause] error cause node for this failure
+      #
+      def err_at(_parser_atom, src, msg, error_pos, nested_errors = nil)
+        Cause.format(src, error_pos, msg, nested_errors)
+      end
+
+      # Notification that a parse succeeded.
+      # Base implementation does nothing - see Contextual reporter for
+      # success tracking.
+      #
+      # @param src [Parsanol::Source] input source being parsed
+      # @return [nil]
+      #
+      def succ(_src)
+        # Tree reporter doesn't track successes
+        nil
+      end
+    end
+  end
+end

data/lib/parsanol/error_reporter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# A namespace for all error reporters.
+#
+# Error reporters collect and format parse errors. The parsing engine
+# calls reporter methods as it attempts to match atoms, building up
+# an error structure that can be presented to the user.
+#
+# @example Using a specific error reporter
+#   parser = MyParser.new
+#   parser.parse(input, reporter: Parsanol::ErrorReporter::Deepest.new)
+#
+# @example Creating a custom error reporter
+#   class MyReporter < Parsanol::ErrorReporter::Base
+#     def initialize
+#       @errors = []
+#     end
+#
+#     def err(atom, source, message, children = nil)
+#       @errors << { position: source.pos, message: message }
+#       @errors.last
+#     end
+#
+#     def err_at(atom, source, message, pos, children = nil)
+#       @errors << { position: pos, message: message }
+#       @errors.last
+#     end
+#   end
+#
+module Parsanol
+  module ErrorReporter
+    # Base class for error reporters.
+    #
+    # Error reporters collect and format parse errors. The parsing engine
+    # calls reporter methods as it attempts to match atoms, building up
+    # an error structure that can be presented to the user.
+    #
+    # Subclasses must implement {#err} and {#err_at} methods.
+    #
+    class Base
+      # Report an error at the current parse position.
+      #
+      # @param atom [Parsanol::Atoms::Base] The atom that failed to match
+      # @param source [Parsanol::Source] The input source
+      # @param message [String, Array<String>] Error message(s)
+      # @param children [Array<Cause>, nil] Child errors from deeper levels
+      # @return [Object] An error cause object (implementation-specific)
+      #
+      # @abstract Subclasses must implement this method
+      #
+      def err(atom, source, message, children = nil)
+        raise NotImplementedError,
+              'Error reporters must implement #err(atom, source, message, children)'
+      end
+
+      # Report an error at a specific position.
+      #
+      # @param atom [Parsanol::Atoms::Base] The atom that failed to match
+      # @param source [Parsanol::Source] The input source
+      # @param message [String, Array<String>] Error message(s)
+      # @param pos [Integer] The byte position of the error
+      # @param children [Array<Cause>, nil] Child errors from deeper levels
+      # @return [Object] An error cause object (implementation-specific)
+      #
+      # @abstract Subclasses must implement this method
+      #
+      def err_at(atom, source, message, pos, children = nil)
+        raise NotImplementedError,
+              'Error reporters must implement #err_at(atom, source, message, pos, children)'
+      end
+
+      # Called when an expression successfully parses.
+      #
+      # This method allows reporters to track successful parses for
+      # better error context. The default implementation does nothing.
+      #
+      # @param source [Parsanol::Source] The input source at success position
+      # @return [void]
+      #
+      def succ(source)
+        # Default: no-op
+      end
+
+      # Called after parse completes for finalization.
+      #
+      # Override this method to perform cleanup or generate final reports.
+      # The default implementation does nothing.
+      #
+      # @return [void]
+      #
+      def finalize
+        # Default: no-op
+      end
+    end
+  end
+end
+
+require 'parsanol/error_reporter/tree'
+require 'parsanol/error_reporter/deepest'
+require 'parsanol/error_reporter/contextual'

data/lib/parsanol/expression/treetop.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# Treetop-style expression parser for Parsanol.
+#
+# This module provides a parser and transform for converting treetop-style
+# expression strings into Parsanol atoms. The implementation is pure Ruby
+# and is not accelerated by the Rust native extension.
+#
+# == Why Pure Ruby?
+#
+# Expression parsing happens at grammar definition time (once per parser class),
+# not during input parsing. The overhead is negligible for typical use cases.
+# The resulting atoms can still be used with Rust-accelerated parsing.
+#
+# == Syntax Reference
+#
+#   Expression      ::= Alternative ('/' Alternative)*
+#   Alternative     ::= Sequence+
+#   Sequence        ::= Occurrence+
+#   Occurrence      ::= Atom ('?' | '*' | '+' | '{min,max}')?
+#   Atom            ::= '(' Expression ')' | '.' | String | CharClass
+#   String          ::= "'" (escape | [^'])* "'"
+#   CharClass       ::= '[' (escape | [^'])* ']'
+#
+# @note Whitespace is required before operators: 'a' ? not 'a'?
+#
+module Parsanol
+  class Expression
+    module Treetop
+      # Parser for treetop-style expression strings.
+      #
+      # Parses expressions like "'a' 'b' ?" and produces a parse tree
+      # that can be transformed into Parsanol atoms.
+      #
+      # @example
+      #   parser = Parser.new
+      #   tree = parser.parse("'a' / 'b'")
+      #   # => {:alt=>[{:seq=>[{:string=>"a"}]}, {:seq=>[{:string=>"b"}]}]}
+      #
+      class Parser < Parsanol::Parser
+        root(:expression)
+
+        rule(:expression) { alternatives }
+
+        # Alternative: 'a' / 'b'
+        rule(:alternatives) do
+          (simple >> (spaced('/') >> simple).repeat).as(:alt)
+        end
+
+        # Sequence by concatenation: 'a' 'b'
+        rule(:simple) { occurrence.repeat(1).as(:seq) }
+
+        # Occurrence modifiers: ?, *, +, {min,max}
+        rule(:occurrence) do
+          (atom.as(:repetition) >> spaced('*').as(:sign)) |
+            (atom.as(:repetition) >> spaced('+').as(:sign)) |
+            (atom.as(:repetition) >> repetition_spec) |
+            (atom.as(:maybe) >> spaced('?')) |
+            atom
+        end
+
+        rule(:atom) do
+          (spaced('(') >> expression.as(:unwrap) >> spaced(')')) |
+            dot |
+            string |
+            char_class
+        end
+
+        # Character class: [a-z], [0-9], etc.
+        rule(:char_class) do
+          (str('[') >>
+            ((str('\\') >> any) | (str(']').absent? >> any)).repeat(1) >>
+            str(']')).as(:match) >> space?
+        end
+
+        # Any character: .
+        rule(:dot) { spaced('.').as(:any) }
+
+        # String literal: 'hello'
+        rule(:string) do
+          str("'") >>
+            ((str('\\') >> any) | (str("'").absent? >> any)).repeat.as(:string) >>
+            str("'") >> space?
+        end
+
+        # Repetition specification: {1,3}, {2,}, {,5}
+        rule(:repetition_spec) do
+          spaced('{') >>
+            integer.maybe.as(:min) >> spaced(',') >>
+            integer.maybe.as(:max) >> spaced('}')
+        end
+
+        rule(:integer) do
+          match['0-9'].repeat(1)
+        end
+
+        # Whitespace handling
+        rule(:space) { match('\s').repeat(1) }
+        rule(:space?) { space.maybe }
+
+        # Helper: match string followed by optional whitespace
+        def spaced(str)
+          str(str) >> space?
+        end
+      end
+
+      # Transform for converting parse trees to Parsanol atoms.
+      #
+      # @example
+      #   tree = {:seq=>[{:string=>"a"}, {:string=>"b"}]}
+      #   transform = Transform.new
+      #   atom = transform.apply(tree)
+      #   # => Sequence.new([Str.new('a'), Str.new('b')])
+      #
+      class Transform < Parsanol::Transform
+        # Repetition with sign: * (zero+) or + (one+)
+        rule(repetition: simple(:rep), sign: simple(:sign)) do
+          min = sign == '+' ? 1 : 0
+          Parsanol::Atoms::Repetition.new(rep, min, nil)
+        end
+
+        # Repetition with bounds: {min,max}
+        rule(repetition: simple(:rep), min: simple(:min), max: simple(:max)) do
+          Parsanol::Atoms::Repetition.new(
+            rep,
+            Integer(min || 0),
+            (max && Integer(max)) || nil
+          )
+        end
+
+        # Alternative: a / b
+        rule(alt: subtree(:alt)) { Parsanol::Atoms::Alternative.new(*alt) }
+
+        # Sequence: a b
+        rule(seq: sequence(:s)) { Parsanol::Atoms::Sequence.new(*s) }
+
+        # Unwrap parentheses
+        rule(unwrap: simple(:u)) { u }
+
+        # Optional: a ?
+        rule(maybe: simple(:m)) { |d| d[:m].maybe }
+
+        # String literal
+        rule(string: simple(:s)) { Parsanol::Atoms::Str.new(s) }
+
+        # Character class
+        rule(match: simple(:m)) { Parsanol::Atoms::Re.new("[#{m}]") }
+
+        # Any character: .
+        rule(any: simple(:_a)) { Parsanol::Atoms::Re.new('.') }
+      end
+    end
+  end
+end