parsanol 1.0.1-aarch64-linux

data/lib/parsanol/parser.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# Base class for constructing PEG parsers. Provides a declarative DSL for
+# defining grammar rules and designating the root (entry point) rule.
+#
+# @example Define a simple parser
+#   class NumberParser < Parsanol::Parser
+#     rule(:digit) { match('[0-9]') }
+#     rule(:number) { digit.repeat(1) }
+#     root(:number)
+#   end
+#
+#   NumberParser.new.parse("123")  # => "123"
+#
+# Parser classes can be embedded within other parsers, enabling grammar
+# composition and reuse.
+#
+# @example Composing parsers
+#   class InnerParser < Parsanol::Parser
+#     root :inner
+#     rule(:inner) { str('x').repeat(3) }
+#   end
+#
+#   class OuterParser < Parsanol::Parser
+#     root :outer
+#     rule(:outer) { str('a') >> InnerParser.new >> str('a') }
+#   end
+#
+#   OuterParser.new.parse("axxxa")  # => "axxxa"
+#
+# Inspired by parser combinator and parsing expression grammar patterns.
+#
+module Parsanol
+  class Parser < Parsanol::Atoms::Base
+    include Parsanol
+
+    class << self
+      # Declares the root (entry point) rule for this parser.
+      # The root is where parsing begins when #parse is called.
+      #
+      # @param rule_name [Symbol] name of the rule to use as root
+      #
+      # @example
+      #   class MyParser < Parsanol::Parser
+      #     rule(:document) { ... }
+      #     root(:document)  # parsing starts here
+      #   end
+      #
+      def root(rule_name)
+        # Remove any existing root method before redefining
+        undef_method :root if method_defined?(:root)
+        define_method(:root) { __send__(rule_name) }
+      end
+    end
+
+    # Delegates matching to the root rule.
+    #
+    # @param src [Parsanol::Source] input source
+    # @param ctx [Parsanol::Atoms::Context] parsing context
+    # @param should_consume_all [Boolean] require complete consumption
+    # @return [Array(Boolean, Object)] parse result
+    #
+    def try(src, ctx, should_consume_all)
+      root.try(src, ctx, should_consume_all)
+    end
+
+    # Formats this parser for display (delegates to root rule).
+    #
+    # @param prec [Integer] precedence level
+    # @return [String] formatted representation
+    #
+    def to_s_inner(prec)
+      root.to_s(prec)
+    end
+
+    # Entry point for visitor traversal from parser root.
+    #
+    # @param visitor [Object] visitor object
+    def accept(visitor)
+      visitor.visit_parser(root)
+    end
+
+    # Unified parsing interface with mode selection support.
+    #
+    # @param input [String] the string to parse
+    # @param mode_or_opts [Symbol, Hash] parsing mode or options hash
+    # @param kwargs [Hash] additional keyword options
+    #
+    # Modes:
+    # - :ruby - Pure Ruby parsing (default, always available)
+    # - :native - Use Rust extension if available, fallback to Ruby
+    # - :json - Return JSON string representation of parse tree
+    #
+    # Options:
+    # - :reporter - Custom error reporter instance
+    # - :prefix - Allow partial matching (default: false)
+    #
+    # @return [Hash, Array, String, Parsanol::Slice] parsed result
+    # @raise [Parsanol::ParseFailed] when parsing fails
+    #
+    def parse(input, mode_or_opts = {}, **kwargs)
+      if mode_or_opts.is_a?(Hash)
+        # Legacy API: parse(input, options={})
+        merged = mode_or_opts.merge(kwargs)
+        super(input, merged)
+      else
+        # New API: parse(input, mode:, **options)
+        dispatch_parse(mode_or_opts, input, kwargs)
+      end
+    end
+
+    # Parses multiple inputs in batch mode.
+    #
+    # @param inputs [Array<String>] strings to parse
+    # @param mode [Symbol] parsing mode (:ruby, :native, or :json)
+    # @param opts [Hash] additional options
+    # @return [Array] array of parse results
+    #
+    def parse_batch(inputs, mode: :ruby, **opts)
+      inputs.map { |str| parse(str, mode: mode, **opts) }
+    end
+
+    private
+
+    # Dispatches to the appropriate parsing backend based on mode.
+    #
+    # @param mode [Symbol] the parsing mode
+    # @param input [String] input to parse
+    # @param opts [Hash] parsing options
+    # @return [Object] parse result
+    #
+    def dispatch_parse(mode, input, opts)
+      case mode
+      when :ruby
+        parse_ruby(input, opts)
+      when :native
+        parse_native(input, opts)
+      when :json
+        parse_json(input, opts)
+      else
+        raise ArgumentError, "Unknown mode: #{mode}. Valid modes: :ruby, :native, :json"
+      end
+    end
+
+    # Pure Ruby parsing (delegates to Base implementation).
+    #
+    # @param input [String] input to parse
+    # @param opts [Hash] parsing options
+    # @return [Object] parse result
+    #
+
+    # Native extension parsing with Ruby fallback.
+    #
+    # @param input [String] input to parse
+    # @param opts [Hash] parsing options
+    # @return [Object] parse result
+    #
+    def parse_native(input, opts)
+      if Parsanol::Native.available?
+        Parsanol::Native.parse_parslet_compatible(root, input)
+      else
+        parse_ruby(input, opts)
+      end
+    end
+
+    # JSON output mode - returns JSON string representation.
+    #
+    # @param input [String] input to parse
+    # @param opts [Hash] parsing options
+    # @return [String] JSON representation of parse tree
+    #
+    def parse_json(input, opts)
+      if Parsanol::Native.available?
+        grammar_def = Parsanol::Native.serialize_grammar(root)
+        outcome = Parsanol::Native.parse(grammar_def, input)
+        outcome.to_json
+      else
+        parse_ruby(input, opts).to_json
+      end
+    end
+  end
+end

data/lib/parsanol/parslet.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+# Parsanol::Parslet - Nested compatibility layer for original Parslet API
+#
+# This provides backwards compatibility for code that uses the original Parslet API.
+# Instead of root-level Parslet constant, we use Parsanol::Parslet as a nested module.
+#
+# == Supported Features
+#
+# - All parser atoms (str, match, any, sequence, alternative, repetition, etc.)
+# - Parser class with rule definitions
+# - Transform for AST construction
+# - Error reporting with Cause
+# - Treetop-style expression parsing via exp()
+#
+# == Limitations
+#
+# - Some advanced features may require direct Parsanol usage
+#
+# Usage:
+#   require 'parsanol/parslet'
+#
+#   class MyParser < Parsanol::Parslet::Parser
+#     include Parsanol::Parslet
+#     rule(:foo) { str('foo') }
+#     root(:foo)
+#   end
+#
+# Migration from original Parslet:
+#   Before: require 'parslet'
+#           class MyParser < Parslet::Parser
+#           include Parslet
+#
+#   After:  require 'parsanol/parslet'
+#           class MyParser < Parsanol::Parslet::Parser
+#           include Parsanol::Parslet
+
+require 'parsanol'
+
+module Parsanol
+  module Parslet
+    # Include Parsanol to get all DSL methods (str, match, any, etc.)
+    include Parsanol
+
+    # Error class alias for compatibility
+    ParseFailed = Parsanol::ParseFailed
+
+    # Atoms namespace - aliases to Parsanol atoms
+    # These are the atoms explicitly loaded by lib/parsanol/atoms.rb
+    module Atoms
+      Base = ::Parsanol::Atoms::Base
+      Str = ::Parsanol::Atoms::Str
+      Re = ::Parsanol::Atoms::Re
+      Sequence = ::Parsanol::Atoms::Sequence
+      Alternative = ::Parsanol::Atoms::Alternative
+      Repetition = ::Parsanol::Atoms::Repetition
+      Named = ::Parsanol::Atoms::Named
+      Entity = ::Parsanol::Atoms::Entity
+      Lookahead = ::Parsanol::Atoms::Lookahead
+      Cut = ::Parsanol::Atoms::Cut
+      Capture = ::Parsanol::Atoms::Capture
+      Scope = ::Parsanol::Atoms::Scope
+      Dynamic = ::Parsanol::Atoms::Dynamic
+      Infix = ::Parsanol::Atoms::Infix
+      Ignored = ::Parsanol::Atoms::Ignored
+      ParseFailed = ::Parsanol::ParseFailed
+    end
+
+    # Class aliases
+    Parser = ::Parsanol::Parser
+    Transform = ::Parsanol::Transform
+    Cause = ::Parsanol::Cause
+    Slice = ::Parsanol::Slice
+    Source = ::Parsanol::Source
+    Pattern = ::Parsanol::Pattern
+    Context = ::Parsanol::Context
+
+    # Module functions for DSL (delegate to Parsanol)
+    module_function
+
+    def match(str = nil)
+      Parsanol.match(str)
+    end
+
+    def str(str)
+      Parsanol.str(str)
+    end
+
+    def any
+      Parsanol.any
+    end
+
+    def scope(&block)
+      Parsanol.scope(&block)
+    end
+
+    def dynamic(&block)
+      Parsanol.dynamic(&block)
+    end
+
+    def infix_expression(element, *operations, &reducer)
+      Parsanol.infix_expression(element, *operations, &reducer)
+    end
+
+    # Parses a treetop-style expression string and returns the corresponding atom.
+    # Delegates to Parsanol.exp.
+    #
+    # @example
+    #   # the same as str('a') >> str('b').maybe
+    #   exp(%q("a" "b"?))
+    #
+    # @param str [String] a treetop expression
+    # @return [Parsanol::Atoms::Base] the corresponding parser atom
+    def exp(str)
+      Parsanol.exp(str)
+    end
+
+    def sequence(symbol)
+      Parsanol.sequence(symbol)
+    end
+
+    def simple(symbol)
+      Parsanol.simple(symbol)
+    end
+
+    def subtree(symbol)
+      Parsanol.subtree(symbol)
+    end
+
+    # Class method extensions for Parser
+    module ClassMethods
+      # Enable automatic rule optimization for all rules in this parser.
+      # @param enable [Boolean] whether to enable optimization
+      def optimize_rules!(enable = true)
+        @optimize_rules = enable
+      end
+
+      # Check if rule optimization is enabled.
+      # @return [Boolean]
+      def optimize_rules?
+        @optimize_rules = false if @optimize_rules.nil?
+        @optimize_rules
+      end
+    end
+
+    # Extend with class methods when included
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/parsanol/pattern/binding.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Pattern binding classes for transform pattern matching.
+# These classes represent placeholders in transform patterns that capture
+# values during pattern matching.
+#
+# Inspired by Parslet (MIT License).
+
+# Base class for all pattern bindings. Matches any subtree regardless of type.
+# Used internally by Parsanol::Transform for pattern-based tree transformation.
+module Parsanol
+  class Pattern
+    SubtreeBind = Struct.new(:symbol) do
+      # Returns the symbol that will be bound during matching.
+      #
+      # @return [Symbol] the binding variable name
+      def variable_name
+        symbol
+      end
+
+      # Human-readable representation of this binding.
+      #
+      # @return [String] description of the binding
+      def inspect
+        "#{binding_category}(#{symbol.inspect})"
+      end
+
+      # Determines if this binding can match the given subtree.
+      # SubtreeBind is the most permissive - matches anything.
+      #
+      # @param subtree [Object] the value to test
+      # @return [true] always returns true
+      def can_bind?(_subtree)
+        true
+      end
+
+      private
+
+      # Extracts the binding category name from the class name.
+      #
+      # @return [String] lowercase category name
+      def binding_category
+        class_match = self.class.name.match(/::(\w+)Bind\z/)
+        return class_match[1].downcase if class_match
+
+        # Fallback for unexpected class names
+        'subtree'
+      end
+    end
+  end
+end
+
+# Binding that matches only simple (leaf) values.
+# Simple values are those that are neither Hash nor Array.
+#
+# @example
+#   simple(:x)  # matches strings, numbers, slices - but not hashes or arrays
+module Parsanol
+  class Pattern
+    class SimpleBind < Parsanol::Pattern::SubtreeBind
+      # Tests if the subtree is a simple leaf value.
+      #
+      # @param subtree [Object] the value to test
+      # @return [Boolean] true if subtree is not a Hash or Array
+      def can_bind?(subtree)
+        !subtree.is_a?(Hash) && !subtree.is_a?(Array)
+      end
+    end
+  end
+end
+
+# Binding that matches sequences of simple leaf values.
+# A sequence is an Array where no element is a Hash or Array.
+#
+# @example
+#   sequence(:items)  # matches ['a', 'b', 'c'] but not ['a', {x: 1}]
+module Parsanol
+  class Pattern
+    class SequenceBind < Parsanol::Pattern::SubtreeBind
+      # Tests if the subtree is a flat sequence of simple values.
+      #
+      # @param subtree [Object] the value to test
+      # @return [Boolean] true if subtree is an Array of simple values
+      def can_bind?(subtree)
+        return false unless subtree.is_a?(Array)
+
+        subtree.none? { |element| element.is_a?(Hash) || element.is_a?(Array) }
+      end
+    end
+  end
+end

data/lib/parsanol/pattern.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Pattern matching for parse tree structures.
+#
+# This class provides tree pattern matching functionality where patterns
+# are expressed using hashes for key-value structures and arrays for
+# sequences. Leaf nodes can be matched using binding expressions.
+#
+# @example Matching a function call tree
+#   tree = {
+#     function_call: {
+#       name: 'foobar',
+#       args: [1, 2, 3]
+#     }
+#   }
+#
+#   pattern = Parsanol::Pattern.new(
+#     function_call: { name: simple(:name), args: sequence(:args) }
+#   )
+#   bindings = pattern.match(tree)
+#   # => { name: 'foobar', args: [1, 2, 3] }
+#
+# Note: Pattern matching is performed at a single subtree level only.
+# For recursive matching throughout a tree, use Parsanol::Transform.
+#
+# Inspired by pattern matching concepts in functional programming.
+#
+module Parsanol
+  class Pattern
+    # Creates a new pattern matcher with the given pattern structure.
+    #
+    # @param pattern [Hash, Array, Object] the pattern to match against
+    def initialize(pattern)
+      @pattern_def = pattern
+    end
+
+    # Attempts to match the given subtree against this pattern.
+    #
+    # Returns a hash of variable bindings if matching succeeds, or nil if
+    # the pattern does not match. Existing bindings can be provided to
+    # verify consistency with previous matches.
+    #
+    # @param subtree [Object] the tree or value to match
+    # @param bindings [Hash, nil] existing variable bindings to verify
+    # @return [Hash, nil] bindings hash on success, nil on failure
+    #
+    # @example Matching with existing bindings
+    #   pattern = Parsanol::Pattern.new('a')
+    #   pattern.match('a', { foo: 'bar' })
+    #   # => { foo: 'bar' }
+    #
+    def match(subtree, bindings = nil)
+      current_bindings = bindings ? bindings.dup : {}
+      check_match(subtree, @pattern_def, current_bindings) ? current_bindings : nil
+    end
+
+    private
+
+    # Core matching dispatcher based on types.
+    # Routes to appropriate matching strategy based on tree and pattern types.
+    #
+    # @param target [Object] the value being matched
+    # @param pattern_val [Object] the pattern to match against
+    # @param captured [Hash] accumulated bindings (modified in place)
+    # @return [Boolean] true if match succeeds
+    #
+    def check_match(target, pattern_val, captured)
+      if target.is_a?(Hash) && pattern_val.is_a?(Hash)
+        match_hash_structure(target, pattern_val, captured)
+      elsif target.is_a?(Array) && pattern_val.is_a?(Array)
+        match_array_elements(target, pattern_val, captured)
+      else
+        match_leaf_value(target, pattern_val, captured)
+      end
+    end
+
+    # Matches leaf values (non-containers).
+    # Handles direct equality, case equality, and binding capture.
+    #
+    # @param target [Object] the value being matched
+    # @param pattern_val [Object] the pattern element
+    # @param captured [Hash] bindings hash
+    # @return [Boolean] true if match succeeds
+    #
+    def match_leaf_value(target, pattern_val, captured)
+      # Case equality covers exact matches and class matches
+      return true if pattern_val === target
+
+      # Check if pattern is a binding expression (like simple(:x))
+      if pattern_val.respond_to?(:can_bind?) && pattern_val.can_bind?(target)
+        return capture_binding(target, pattern_val, captured)
+      end
+
+      # No match possible
+      false
+    end
+
+    # Handles binding capture for expressions like simple(:name).
+    # If the variable is already bound, verifies consistency.
+    # Otherwise, creates a new binding.
+    #
+    # @param value [Object] the value to bind
+    # @param binder [Object] the binding expression object
+    # @param captured [Hash] bindings hash (modified in place)
+    # @return [Boolean] true if binding succeeds
+    #
+    def capture_binding(value, binder, captured)
+      var_key = binder.variable_name
+
+      # Verify existing binding consistency if present
+      return captured[var_key] == value if var_key && captured.key?(var_key)
+
+      # Store new binding
+      captured[var_key] = value if var_key
+      true
+    end
+
+    # Matches array structures element-by-element.
+    # Arrays must have identical length and each element must match.
+    #
+    # @param target_ary [Array] the array being matched
+    # @param pattern_ary [Array] the pattern array
+    # @param captured [Hash] bindings hash
+    # @return [Boolean] true if all elements match
+    #
+    def match_array_elements(target_ary, pattern_ary, captured)
+      # Length mismatch means no match
+      return false unless target_ary.length == pattern_ary.length
+
+      # Each position must match
+      target_ary.zip(pattern_ary).all? do |elem, pat|
+        check_match(elem, pat, captured)
+      end
+    end
+
+    # Matches hash structures key-by-key.
+    # All keys in pattern must exist in target with matching values.
+    #
+    # @param target_hash [Hash] the hash being matched
+    # @param pattern_hash [Hash] the pattern hash
+    # @param captured [Hash] bindings hash
+    # @return [Boolean] true if all key-value pairs match
+    #
+    def match_hash_structure(target_hash, pattern_hash, captured)
+      # Size mismatch means no match
+      return false unless target_hash.size == pattern_hash.size
+
+      # Verify each expected key exists with matching value
+      pattern_hash.each do |key, expected|
+        return false unless target_hash.key?(key)
+
+        actual = target_hash[key]
+        return false unless check_match(actual, expected, captured)
+      end
+
+      true
+    end
+  end
+end