parsanol 1.3.13-arm-linux

data/lib/parsanol/atoms/custom.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module Atoms
+    # Base class for creating custom parser atoms.
+    #
+    # Custom atoms allow extending Parsanol with domain-specific matching logic
+    # that cannot be expressed with the built-in combinators.
+    #
+    # @example Custom atom for matching indentation-sensitive content
+    #   class IndentAtom < Parsanol::Atoms::Custom
+    #     def initialize(expected_indent)
+    #       @expected_indent = expected_indent
+    #       super()
+    #     end
+    #
+    #     # Required: Implement try_match
+    #     def try_match(source, context, consume_all)
+    #       pos = source.pos
+    #       indent = count_indent(source)
+    #
+    #       if indent == @expected_indent
+    #         content = read_until_newline(source)
+    #         [true, content]
+    #       else
+    #         source.pos = pos  # Restore position on failure
+    #         [false, nil]
+    #       end
+    #     end
+    #
+    #     private
+    #
+    #     def count_indent(source)
+    #       # ... implementation ...
+    #     end
+    #   end
+    #
+    #   # Usage in parser
+    #   class MyParser < Parsanol::Parser
+    #     rule(:indented_line) { IndentAtom.new(2) }
+    #   end
+    #
+    class Custom < Base
+      # Required: Implement this method to define matching behavior
+      #
+      # @param source [Parsanol::Source] The input source with position tracking
+      # @param context [Parsanol::Atoms::Context] Parse context for memoization
+      # @param consume_all [Boolean] If true, must consume entire input
+      # @return [Array<Boolean, Object>] Tuple of [success, result]
+      #   - success: true if match succeeded, false otherwise
+      #   - result: matched value on success, nil on failure
+      #
+      # @note You MUST restore source.bytepos on failure for proper backtracking
+      #
+      def try_match(source, context, consume_all)
+        raise NotImplementedError,
+              "Custom atoms must implement #try_match(source, context, consume_all)"
+      end
+
+      # Override of Base#try that delegates to try_match
+      # Handles error reporting and result wrapping
+      #
+      # @api private
+      def try(source, context, consume_all)
+        success, result = try_match(source, context, consume_all)
+
+        if success
+          [true, result]
+        else
+          # Generate error cause for reporting
+          context.err(
+            self,
+            source,
+            "Failed to match custom atom: #{self.class.name}",
+          )
+        end
+      end
+
+      # Optional: Override to provide first set for optimization
+      # Returns the set of characters/strings this atom can match at start
+      #
+      # @return [Set<String>, nil] First set, or nil if not determinable
+      def first_set
+        nil # Unknown by default
+      end
+
+      # Optional: Override to enable caching for this atom
+      # Return false for context-dependent matching (e.g., indentation)
+      #
+      # @return [Boolean] true if atom can be cached
+      def cacheable?
+        true
+      end
+
+      # Optional: Override to provide custom serialization for native parser
+      # Return nil if atom cannot be serialized (must use pure Ruby mode)
+      #
+      # @return [Hash, nil] JSON-serializable representation
+      def to_native_format
+        nil # Not serializable by default
+      end
+
+      # Override to_s_inner for debug printing
+      # @api private
+      def to_s_inner(_prec = nil)
+        "custom(#{self.class.name})"
+      end
+    end
+  end
+end

data/lib/parsanol/atoms/cut.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Cut operator for PEG grammars
+#
+# A cut operator (↑) instructs the parser to discard backtrack information
+# at a specific point. This enables more aggressive cache eviction and can
+# reduce space complexity from O(n) to O(1).
+#
+# Reference: Mizushima et al. (2010) "Packrat Parsers Can Handle Practical
+# Grammars in Mostly Constant Space"
+#
+# Example:
+#
+#   rule(:statement) {
+#     str('if').cut >> condition >> then_clause |
+#     str('while').cut >> condition >> body |
+#     str('print').cut >> expression
+#   }
+#
+# After 'if' succeeds, the cut discards backtrack info for 'while' and 'print'.
+# This means if the parse fails later in the 'if' branch, we won't try the
+# other alternatives.
+#
+module Parsanol
+  module Atoms
+    class Cut < Parsanol::Atoms::Base
+      attr_reader :parslet
+
+      def initialize(parslet)
+        super()
+        @parslet = parslet
+      end
+
+      def try(source, context, consume_all)
+        # First, try to match the parslet
+        success, value = parslet.apply(source, context, consume_all)
+
+        return [success, value] unless success
+
+        # On success, signal to context that a cut has occurred
+        # This allows the context to:
+        # 1. Mark the current position as a cut point
+        # 2. Empty the backtrack stack (we won't backtrack past here)
+        # 3. Aggressively evict cache entries before this position
+        context.cut!(source.bytepos) if context.respond_to?(:cut!)
+
+        [success, value]
+      end
+
+      # Cut doesn't need caching - it's a thin wrapper
+      def cached?
+        false
+      end
+
+      def to_s_inner(prec)
+        "#{parslet.to_s(prec)}↑"
+      end
+
+      # FIRST set of cut is same as wrapped parslet
+      # Cut doesn't change matching behavior, only affects backtracking
+      def compute_first_set
+        parslet.first_set
+      end
+    end
+  end
+end

data/lib/parsanol/atoms/dsl.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# Parser composition DSL - chainable methods for building parser atoms.
+# All atoms can use these methods to combine into larger parsers.
+#
+# Inspired by Parslet (MIT License).
+
+module Parsanol
+  module Atoms
+    module DSL
+      # Repeats the current atom between min and max times.
+      # If max is nil, there is no upper limit.
+      #
+      # @example
+      #   str('a').repeat           # match zero or more 'a's
+      #   str('a').repeat(1, 3)   # match 1-3 `a`s
+      def repeat(min = 0, max = nil)
+        Parsanol::Atoms::Repetition.new(self, min, max)
+      end
+
+      # Matches atom optionally (0 or 1 times).
+      # Result is nil if not present, otherwise the matched value.
+      #
+      # @example
+      #   str('foo').maybe   # => nil or 'foo'
+      def maybe
+        Parsanol::Atoms::Repetition.new(self, 0, 1, :maybe)
+      end
+
+      # Ignores the result of a match - returns nil always.
+      #
+      # @example
+      #   str('foo').ignore   # => nil (not 'foo')
+      def ignore
+        Parsanol::Atoms::Ignored.new(self)
+      end
+
+      # Chains two atoms in sequence.
+      #
+      # @example
+      #   str('a') >> str('b')
+      def >>(other)
+        Parsanol::Atoms::Sequence.new(self, other)
+      end
+
+      # Chains two atoms as alternatives (ordered choice).
+      #
+      # @example
+      #   str('a') | str('b')   # matches 'a' or `b`
+      def |(other)
+        Parsanol::Atoms::Alternative.new(self, other)
+      end
+
+      # Negative lookahead - succeeds only if atom is absent.
+      #
+      # @example
+      #   str('a').absent?
+      def absent?
+        Parsanol::Atoms::Lookahead.new(self, false)
+      end
+
+      # Positive lookahead - succeeds only if atom is present.
+      #
+      # @example
+      #   str('a').present?
+      def present?
+        Parsanol::Atoms::Lookahead.new(self, true)
+      end
+
+      # Labels a match for tree output.
+      #
+      # @example
+      #   str('a').as(:b)   # => {:b => 'a'}
+      def as(name)
+        Parsanol::Atoms::Named.new(self, name)
+      end
+
+      # Captures match result for later reference.
+      #
+      # @example
+      #   str('a').capture(:first) >> dynamic { str(ctx.captures[:first]) }
+      def capture(name)
+        Parsanol::Atoms::Capture.new(self, name)
+      end
+
+      # Commit point - prevents backtracking after successful match.
+      # Use with caution: cuts prevent backtracking to alternatives.
+      #
+      # @example
+      #   str('if').cut >> condition >> body |
+      def cut
+        Parsanol::Atoms::Cut.new(self)
+      end
+    end
+  end
+end

data/lib/parsanol/atoms/dynamic.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Evaluates a block at parse time. The result from the block must be a parser
+# (something which implements #apply). In the first case, the parser will then
+# be applied to the input, creating the result.
+#
+# Dynamic parses are never cached.
+#
+# Example:
+#   dynamic { rand < 0.5 ? str('a') : str('b') }
+#
+module Parsanol
+  module Atoms
+    class Dynamic < Parsanol::Atoms::Base
+      attr_reader :block
+
+      def initialize(block)
+        @block = block
+      end
+
+      def cached?
+        false
+      end
+
+      def try(source, context, consume_all)
+        # Phase 55: Cache @block ivar to reduce lookup overhead
+        block = @block
+        result = block.call(source, context)
+
+        # Result is a parslet atom.
+        result.apply(source, context, consume_all)
+      end
+
+      def to_s_inner(_prec)
+        "dynamic { ... }"
+      end
+    end
+  end
+end

data/lib/parsanol/atoms/entity.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Named rule wrapper that provides lazy evaluation and caching for grammar
+# rules. Rules are defined as Entity atoms and named, and they can be
+# referenced by other rules with automatic cycle detection.
+#
+# @example
+#   class MyParser < Parsanol::Parser
+#     rule(:expression) { str('a') >> str('b') }
+#     root(:expression)
+#   end
+#
+#   MyParser.new.parse('ab')  # => ["a", "b"]
+#
+module Parsanol
+  module Atoms
+    class Entity < Parsanol::Atoms::Base
+      attr_reader :rule_name, :block_definition
+
+      # Alias for backward compatibility
+      alias name rule_name
+
+      def initialize(name, label_or_opts = {}, &body)
+        super()
+        @rule_name = name
+        # Support both old API (label string) and new API (options hash)
+        @options = if label_or_opts.is_a?(Hash)
+                     label_or_opts
+                   else
+                     { label: label_or_opts }
+                   end
+        @body = body
+        @cached_atom = nil
+        # Set label on self for display purposes
+        self.label = @options[:label] if @options[:label]
+      end
+
+      # Evaluates the rule body, returns cached result.
+      def parslet
+        return @cached_atom unless @cached_atom.nil?
+
+        @cached_atom = @body.call
+
+        raise_not_implemented if @cached_atom.nil?
+
+        @cached_atom.label = @options[:label] if @options[:label]
+        @cached_atom
+      end
+
+      def try(source, context, consume_all)
+        atom = parslet
+        atom.apply(source, context, consume_all)
+      end
+
+      # Entities don't need caching since the underlying atom is already cached.
+      def cached?
+        false
+      end
+
+      def to_s_inner(_prec)
+        rule_name.to_s.upcase
+      end
+
+      private
+
+      def raise_not_implemented
+        trace_lines = caller.grep_v(/#{Regexp.escape(__FILE__)}/)
+        error_message = "rule '#{@rule_name}' has not been implemented, but already used?"
+        exception = NotImplementedError.new(error_message)
+        exception.set_backtrace(trace_lines)
+        raise exception
+      end
+    end
+  end
+end

data/lib/parsanol/atoms/ignored.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Ignores the result of a match, Useful for cases where you want to match
+# prefix or suffix without returning any.
+
+#
+# @example
+#   str('foo')            # will return 'foo',
+#   str('foo').ignore     # will return nil
+#
+# Inspired by Parslet (MIT License).
+
+module Parsanol
+  module Atoms
+    class Ignored < Parsanol::Atoms::Base
+      attr_reader :wrapped_atom
+
+      def initialize(atom)
+        super()
+        @wrapped_atom = atom
+      end
+
+      def apply(source, context, consume_all)
+        ok, result = @wrapped_atom.apply(source, context, consume_all)
+
+        return [false, result] unless ok
+
+        # Success - return nil instead of the matched value
+        [true, nil]
+      end
+
+      def to_s_inner(prec)
+        "ignored(#{@wrapped_atom.to_s(prec)})"
+      end
+    end
+  end
+end

data/lib/parsanol/atoms/infix.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# Infix expression parser using precedence climbing algorithm.
+# Parses mathematical-style expressions with configurable operators.
+#
+# @example Basic usage
+#   element = match('[0-9]').repeat(1)
+#   operations = [
+#     [str('+'), 1, :left],
+#     [str('*'), 2, :left]
+#   ]
+#   infix = Parsanol::Atoms::Infix.new(element, *operations)
+#
+# Inspired by Parslet (MIT License).
+# Algorithm reference: http://eli.thegreenplace.net/2012/08/02/parsing-expressions-by-precedence-climbing/
+
+module Parsanol
+  module Atoms
+    class Infix < Parsanol::Atoms::Base
+      attr_reader :base_element, :operator_table, :result_combiner
+
+      # Creates a new infix expression parser.
+      #
+      # @param base_element [Parsanol::Atoms::Base] parser for atomic operands
+      # @param operations [Array<Array>] operator definitions [atom, precedence, associativity]
+      # @yield block to combine left, operator, right into result
+      def initialize(base_element, operations, &combiner)
+        super()
+        @base_element = base_element
+        @operator_table = operations
+        @result_combiner = combiner || default_combiner
+      end
+
+      # Attempts to parse an infix expression from the source.
+      #
+      # @param source [Parsanol::Source] input source
+      # @param context [Parsanol::Atoms::Context] parsing context
+      # @param consume_all [Boolean] whether to consume all input
+      # @return [Array] success/error tuple
+      def try(source, context, consume_all)
+        catch(:parse_error) do
+          raw_result = climb_precedence(source, context, consume_all)
+          structured_result = build_result_tree(raw_result)
+          return succ(structured_result)
+        end
+      end
+
+      private
+
+      # Default combiner creates nested hash structure
+      def default_combiner
+        lambda do |left_side, operator, right_side|
+          { left: left_side, op: operator, right: right_side }
+        end
+      end
+
+      # Converts flat array representation to nested structure.
+      # Input: ['1', '+', ['2', '*', '3']]
+      # Output: { left: '1', op: '+', right: { left: '2', op: '*', right: '3' } }
+      #
+      # @param expression [Object] array or leaf value
+      # @return [Object] structured result
+      def build_result_tree(expression)
+        return expression unless expression.is_a?(Array)
+
+        combiner = @result_combiner
+        accumulator = expression.shift
+
+        until expression.empty?
+          operator_token, right_operand = expression.shift(2)
+
+          if right_operand.is_a?(Array)
+            # Recursively process nested expressions
+            right_operand = build_result_tree(right_operand)
+          end
+
+          accumulator = combiner.call(accumulator, operator_token,
+                                      right_operand)
+        end
+
+        accumulator
+      end
+
+      # Main precedence climbing loop.
+      # Parses operands and operators, respecting precedence and associativity.
+      #
+      # @param source [Parsanol::Source] input source
+      # @param context [Parsanol::Atoms::Context] parsing context
+      # @param consume_all [Boolean] consume all flag
+      # @param min_precedence [Integer] minimum precedence to continue (default: 1)
+      # @return [Object] parsed expression
+      def climb_precedence(source, context, consume_all, min_precedence = 1)
+        element_parser = @base_element
+        expression_parts = []
+
+        # Must match at least one element to start
+        ok, first_value = element_parser.apply(source, context, false)
+        unless ok
+          throw :parse_error,
+                context.err(self, source, "Expected #{element_parser.inspect}",
+                            [first_value])
+        end
+
+        expression_parts << flatten(first_value, true)
+
+        # Continue while operators match
+        loop do
+          saved_position = source.bytepos
+          operator_match, precedence, associativity = try_match_operator(
+            source, context, false
+          )
+
+          # No operator found - done with this level
+          break unless operator_match
+
+          if precedence >= min_precedence
+            # Calculate next minimum precedence based on associativity
+            next_min = associativity == :left ? precedence + 1 : precedence
+
+            expression_parts << operator_match
+            expression_parts << climb_precedence(source, context, consume_all,
+                                                 next_min)
+          else
+            # Operator has lower precedence - backtrack and return
+            source.bytepos = saved_position
+            return simplify_result(expression_parts)
+          end
+        end
+
+        simplify_result(expression_parts)
+      end
+
+      # Attempts to match any operator from the operator table.
+      #
+      # @param source [Parsanol::Source] input source
+      # @param context [Parsanol::Atoms::Context] parsing context
+      # @param consume_all [Boolean] consume all flag
+      # @return [Array, nil] [matched_value, precedence, associativity] or nil
+      def try_match_operator(source, context, consume_all)
+        operators = @operator_table
+
+        operators.each do |op_parser, prec, assoc|
+          ok, value = op_parser.apply(source, context, consume_all)
+          return [flatten(value, true), prec, assoc] if ok
+        end
+
+        nil
+      end
+
+      # Simplifies single-element results to avoid unnecessary nesting.
+      #
+      # @param result [Array] expression parts
+      # @return [Object] simplified result
+      def simplify_result(result)
+        result.length == 1 ? result.first : result
+      end
+
+      public
+
+      # Returns string representation for debugging
+      def to_s_inner(_precedence)
+        op_list = @operator_table.map { |op, _, _| op.inspect }.join(", ")
+        "infix_expression(#{@base_element.inspect}, [#{op_list}])"
+      end
+    end
+  end
+end

data/lib/parsanol/atoms/lookahead.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Lookahead assertion - checks for pattern presence/absence without consuming.
+# Position is always restored after the check.
+#
+# @example Positive lookahead (must be present)
+#   str('foo').present?  # succeeds if 'foo' ahead
+#
+# @example Negative lookahead (must not be present)
+#   str('foo').absent?   # succeeds if 'foo' not ahead
+#
+module Parsanol
+  module Atoms
+    class Lookahead < Parsanol::Atoms::Base
+      # @return [Boolean] true for positive, false for negative
+      attr_reader :positive
+
+      # @return [Parsanol::Atoms::Base] parser to check
+      attr_reader :bound_parslet
+
+      # Creates a new lookahead.
+      #
+      # @param parser [Parsanol::Atoms::Base] parser to check
+      # @param is_positive [Boolean] positive vs negative
+      def initialize(parser, is_positive = true)
+        super()
+        @positive = is_positive
+        @bound_parslet = parser
+
+        # Pre-built error components
+        @should_start = ["Input should start with ", parser].freeze
+        @should_not_start = ["Input should not start with ", parser].freeze
+      end
+
+      # Tests lookahead without consuming input.
+      #
+      # @param source [Parsanol::Source] input
+      # @param context [Parsanol::Atoms::Context] context
+      # @param consume_all [Boolean] ignored
+      # @return [Array(Boolean, Object)] result
+      def try(source, context, consume_all)
+        # Save position - never consume
+        saved = source.bytepos
+
+        matched, = @bound_parslet.apply(source, context, consume_all)
+
+        # Always restore
+        source.bytepos = saved
+
+        if @positive
+          # Positive: succeed if matched
+          return ok(nil) if matched
+
+          context.err_at(self, source, @should_start, source.bytepos)
+        else
+          # Negative: succeed if not matched
+          if matched
+            return context.err_at(self, source, @should_not_start,
+                                  source.bytepos)
+          end
+
+          ok(nil)
+        end
+      end
+
+      precedence LOOKAHEAD
+
+      # String representation.
+      #
+      # @param prec [Integer] precedence
+      # @return [String]
+      def to_s_inner(prec)
+        symbol = @positive ? "&" : "!"
+        "#{symbol}#{@bound_parslet.to_s(prec)}"
+      end
+
+      # FIRST set is always EPSILON (zero-width).
+      #
+      # @return [Set]
+      def compute_first_set
+        Set.new([Parsanol::FirstSet::EPSILON])
+      end
+    end
+  end
+end