parsanol 1.3.13-arm-linux

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

data/lib/parsanol/expression.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Parses treetop-style expression strings and converts them to Parsanol atoms.
+#
+# This allows specifying parser rules as strings using treetop syntax instead
+# of building atoms explicitly with the DSL.
+#
+# == Performance Note
+#
+# The expression parser is implemented in pure Ruby and is NOT accelerated by
+# the Rust native extension. This is intentional and acceptable because:
+#
+# 1. Expression parsing happens at grammar definition time (once)
+# 2. Expression strings are typically short (< 100 characters)
+# 3. The resulting atoms can still be used with Rust-accelerated parsing
+#
+# If you need maximum performance for dynamically generated parsers, consider
+# building atoms directly with the DSL (str, match, any, etc.) instead.
+#
+# == Syntax
+#
+# The treetop syntax supports:
+#
+# - Strings: 'hello' (single quotes)
+# - Character classes: [a-z], [0-9]
+# - Any character: .
+# - Sequence: 'a' 'b' (concatenation)
+# - Alternative: 'a' / 'b'
+# - Optional: 'a' ? (space before ? required)
+# - Zero or more: 'a' * (space before * required)
+# - One or more: 'a' + (space before + required)
+# - Repetition: 'a'{1,3}
+# - Grouping: ('a' / 'b')+
+#
+# == Example
+#
+#   # Using exp()
+#   rule(:word) { exp("'a' 'b' ?") }
+#
+#   # Equivalent DSL:
+#   rule(:word) { str('a') >> str('b').maybe }
+#
+# == Result Usage
+#
+# The atoms produced by exp() can be used with Rust-accelerated parsing:
+#
+#   atom = Parsanol.exp("'a' +")
+#
+#   # Ruby parsing
+#   atom.parse('aaa')
+#
+#   # Rust-accelerated parsing (if native extension available)
+#   Parsanol::Native.parse_with_grammar(atom, 'aaa')
+#
+module Parsanol
+  class Expression
+    include Parsanol
+
+    autoload :Treetop, "parsanol/expression/treetop"
+
+    # Creates a parser atom from a treetop-style expression string.
+    #
+    # @param str [String] a treetop expression
+    # @param opts [Hash] options (:type => :treetop, default)
+    # @return [Parsanol::Expression] expression object (call #to_parslet for atom)
+    #
+    # @example
+    #   expr = Parsanol::Expression.new("'a' 'b' ?")
+    #   atom = expr.to_parslet
+    #   atom.parse('a')  # => "a"@0
+    #
+    def initialize(str, opts = {}, _context = self)
+      @type = opts[:type] || :treetop
+      @exp = str
+      @parslet = transform(parse(str))
+    end
+
+    # Transforms the parse tree into a parser atom.
+    #
+    # @param tree [Hash] parse tree from Treetop::Parser
+    # @return [Parsanol::Atoms::Base] parser atom
+    def transform(tree)
+      transform = Treetop::Transform.new
+      transform.apply(tree)
+    rescue StandardError
+      warn "Could not transform: #{tree.inspect}"
+      raise
+    end
+
+    # Parses the expression string and returns a parse tree.
+    #
+    # @param str [String] treetop expression
+    # @return [Hash] parse tree
+    def parse(str)
+      parser = Treetop::Parser.new
+      parser.parse(str)
+    end
+
+    # Returns the parser atom for this expression.
+    #
+    # @return [Parsanol::Atoms::Base] parser atom
+    def to_parslet
+      @parslet
+    end
+  end
+end