parsanol 1.3.13-arm-linux

data/lib/parsanol/optimizers/sequence_optimizer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "../ast_visitor"
+
+module Parsanol
+  module Optimizers
+    # Optimizes sequence patterns in the AST
+    # Follows visitor pattern for clean separation of concerns
+    #
+    # Transformations:
+    # - str('a') >> str('b') => str('ab') (merge adjacent strings)
+    # - (A >> B) >> C => A >> B >> C (flatten nested sequences)
+    # - Sequence(A) => A (unwrap single-element sequences)
+    class SequenceOptimizer < ASTVisitor
+      # Visit a sequence node and apply sequence optimizations
+      # @param parslet [Parsanol::Atoms::Sequence] sequence to optimize
+      # @return [Parsanol::Atoms::Base] optimized parslet
+      def visit_sequence(parslet)
+        # First optimize children recursively
+        new_parslets = parslet.parslets.map { |p| visit(p) }
+
+        # Optimization 1: Flatten nested sequences
+        flattened = flatten_sequences(new_parslets)
+
+        # Optimization 2: Merge adjacent string literals
+        merged = merge_adjacent_strings(flattened)
+
+        # Optimization 3: Unwrap single-element sequences
+        return merged[0] if merged.size == 1
+
+        # Return optimized sequence if changed
+        if merged == parslet.parslets
+          parslet
+        else
+          Parsanol::Atoms::Sequence.new(*merged)
+        end
+      end
+
+      private
+
+      # Flatten nested sequences into a single level
+      # @param parslets [Array<Parsanol::Atoms::Base>] array of parslets
+      # @return [Array<Parsanol::Atoms::Base>] flattened array
+      def flatten_sequences(parslets)
+        result = []
+        parslets.each do |p|
+          if p.is_a?(Parsanol::Atoms::Sequence)
+            result.concat(p.parslets)
+          else
+            result << p
+          end
+        end
+        result
+      end
+
+      # Merge adjacent Str atoms into single Str atoms
+      # @param parslets [Array<Parsanol::Atoms::Base>] array of parslets
+      # @return [Array<Parsanol::Atoms::Base>] array with merged strings
+      def merge_adjacent_strings(parslets)
+        return parslets if parslets.size < 2
+
+        result = []
+        i = 0
+
+        while i < parslets.size
+          current = parslets[i]
+
+          if current.is_a?(Parsanol::Atoms::Str)
+            # Look ahead for consecutive Str atoms using Rope for O(1) append
+            rope = Parsanol::Rope.new.append(current.str)
+            j = i + 1
+
+            while j < parslets.size && parslets[j].is_a?(Parsanol::Atoms::Str)
+              rope.append(parslets[j].str)
+              j += 1
+            end
+
+            # Create merged Str if we found consecutive strings
+            # O(n) join happens once at the end instead of O(n²) repeated concatenation
+            if j > i + 1
+              result << Parsanol::Atoms::Str.new(rope.to_s)
+              i = j
+            else
+              result << current
+              i += 1
+            end
+          else
+            result << current
+            i += 1
+          end
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/parsanol/options/zero_copy.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Parsanol::ZeroCopy - Zero-Copy Transform Mode (Direct FFI Object Construction)
+#
+# This mode provides MAXIMUM PERFORMANCE through zero-copy FFI.
+# - Rust directly constructs Ruby objects via rb_class_new, rb_ivar_set
+# - No serialization overhead whatsoever
+# - REQUIRES native extension AND type mapping definitions
+#
+# Usage:
+#   # Define Ruby classes that mirror Rust types
+#   module Calculator
+#     class Number < Expr
+#       attr_reader :value
+#       def initialize(value); @value = value; end
+#       def eval = @value
+#     end
+#
+#     class BinOp < Expr
+#       attr_reader :left, :op, :right
+#       def eval; ...; end
+#     end
+#   end
+#
+#   class CalculatorParser < Parsanol::Parser
+#     include Parsanol::ZeroCopy
+#
+#     rule(:number) { ... }
+#     root(:expression)
+#
+#     # Type mapping (tells Rust which Ruby classes to construct)
+#     output_types(
+#       number: Calculator::Number,
+#       binop: Calculator::BinOp
+#     )
+#   end
+#
+#   parser = CalculatorParser.new
+#   expr = parser.parse("42+8")  # Returns Calculator::Number or BinOp DIRECTLY
+#   puts expr.eval  # No transform needed!
+#
+# Performance: FASTEST mode (18-44x faster than pure Ruby)
+# Memory: Lowest overhead (zero-copy, no serialization)
+
+module Parsanol
+  module ZeroCopy
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Define output type mapping for zero-copy construction
+      #
+      # This tells the Rust parser which Ruby classes to instantiate
+      # for each named capture in the grammar.
+      #
+      # @param types [Hash] Mapping of rule names to Ruby classes
+      # @example
+      #   output_types(
+      #     number: Calculator::Number,
+      #     binop: Calculator::BinOp,
+      #     expr: Calculator::Expr
+      #   )
+      def output_types(types = nil)
+        @output_types = types if types
+        @output_types ||= {}
+      end
+
+      # Define a single output type mapping
+      #
+      # @param rule_name [Symbol, String] Name of the rule
+      # @param ruby_class [Class] Ruby class to instantiate
+      # @example
+      #   output_type :number, Calculator::Number
+      def output_type(rule_name, ruby_class)
+        output_types[rule_name.to_sym] = ruby_class
+      end
+
+      # Get output types as a hash suitable for FFI
+      #
+      # @return [Hash] String keys, class names as values
+      def output_types_for_ffi
+        output_types.transform_keys(&:to_s).transform_values do |klass|
+          klass.is_a?(Class) ? klass.name : klass.to_s
+        end
+      end
+    end
+
+    # Parse input and return direct Ruby objects (no serialization)
+    #
+    # @param input [String] The input string to parse
+    # @return [Object] Direct Ruby object (type depends on grammar)
+    # @raise [LoadError] If native extension not available
+    # @raise [Parsanol::ParseFailed] If parsing fails
+    def parse(input)
+      unless Parsanol::Native.available?
+        raise LoadError,
+              "ZeroCopy mode requires native extension for direct FFI object construction. " \
+              "Run `rake compile` to build the extension, or use " \
+              "parser.parse(input, mode: :ruby) for pure Ruby parsing."
+      end
+
+      grammar_json = Parsanol::Native.serialize_grammar(root)
+      type_map = self.class.output_types_for_ffi
+
+      if type_map.empty?
+        raise ArgumentError,
+              "ZeroCopy mode requires output_types to be defined. " \
+              "Add `output_types(number: MyNumberClass)` to your parser class."
+      end
+
+      Parsanol::Native.parse_to_objects(grammar_json, input, type_map)
+    end
+
+    # Parse with explicit type map override
+    #
+    # @param input [String] The input string to parse
+    # @param type_map [Hash] Override type mapping for this parse
+    # @return [Object] Direct Ruby object
+    def parse_with_types(input, type_map)
+      raise LoadError, "ZeroCopy mode requires native extension." unless Parsanol::Native.available?
+
+      grammar_json = Parsanol::Native.serialize_grammar(root)
+      Parsanol::Native.parse_to_objects(grammar_json, input, type_map)
+    end
+  end
+end

data/lib/parsanol/options.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Parsanol Transform Mode Options
+#
+# This module provides the ZeroCopy transformation mode for maximum performance:
+#
+# ZeroCopy - Direct FFI object construction (requires native extension, fastest)
+#
+# Usage:
+#   class MyParser < Parsanol::Parser
+#     include Parsanol::ZeroCopy
+#     rule(:number) { match('[0-9]').repeat(1).as(:int) }
+#     root(:number)
+#
+#     output_types(number: MyNumberClass)
+#   end
+#
+# For standard parsing, use the Parse Modes API instead:
+#   parser.parse(input, mode: :native)  # or :ruby, :json
+
+require "parsanol/options/zero_copy"

data/lib/parsanol/parallel.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Parallel parsing support for batch processing multiple inputs.
+  # Uses rayon for linear speedup on multi-core systems.
+  #
+  # @example Parse multiple files in parallel
+  #   grammar = MyParser.new.serialize_grammar
+  #   inputs = Dir.glob("*.json").map { |f| File.read(f) }
+  #
+  #   results = Parsanol::Parallel.parse_batch(grammar, inputs)
+  #   results.each_with_index do |result, i|
+  #     case result
+  #     when Hash then puts "File #{i} parsed: #{result}"
+  #     when Parsanol::ParseFailed then puts "File #{i} failed: #{result.message}"
+  #     end
+  #   end
+  #
+  module Parallel
+    # Configuration for parallel parsing.
+    #
+    # @example Configure with 8 threads
+    #   config = Parsanol::Parallel::Config.new
+    #     .with_num_threads(8)
+    #     .with_min_chunk_size(50)
+    #
+    #   results = Parsanol::Parallel.parse_batch(grammar, inputs, config: config)
+    #
+    class Config
+      # @return [Integer, nil] Number of threads (nil = auto-detect based on CPU cores)
+      attr_accessor :num_threads
+
+      # @return [Integer] Minimum inputs per thread (default: 10)
+      attr_accessor :min_chunk_size
+
+      def initialize
+        @num_threads = nil # Auto-detect
+        @min_chunk_size = 10
+      end
+
+      # Set the number of threads to use.
+      #
+      # @param n [Integer] Number of threads
+      # @return [Config] self for chaining
+      def with_num_threads(n)
+        @num_threads = n
+        self
+      end
+
+      # Set the minimum chunk size per thread.
+      #
+      # @param size [Integer] Minimum inputs per thread
+      # @return [Config] self for chaining
+      def with_min_chunk_size(size)
+        @min_chunk_size = size
+        self
+      end
+    end
+
+    class << self
+      # Parse multiple inputs in parallel.
+      #
+      # When the native extension with parallel feature is available,
+      # this uses rayon for parallel execution. Otherwise, falls back
+      # to sequential parsing.
+      #
+      # @param grammar_json [String] JSON-serialized grammar
+      # @param inputs [Array<String>] Array of input strings to parse
+      # @param config [Config] Parallel configuration (optional)
+      # @return [Array<Object>] Array of parse results in same order as inputs
+      #
+      # @example Basic usage
+      #   results = Parsanol::Parallel.parse_batch(grammar, inputs)
+      #
+      # @example With configuration
+      #   config = Parsanol::Parallel::Config.new.with_num_threads(4)
+      #   results = Parsanol::Parallel.parse_batch(grammar, inputs, config: config)
+      #
+      def parse_batch(grammar_json, inputs, config: Config.new)
+        unless Parsanol::Native.available?
+          raise LoadError,
+                "Parallel parsing requires native extension. " \
+                "Run `rake compile` to build the extension."
+        end
+
+        Parsanol::Native.parse_batch_parallel(
+          grammar_json,
+          inputs,
+          num_threads: config.num_threads,
+        )
+      end
+
+      # Parse multiple inputs in parallel with transformation.
+      #
+      # @param grammar_json [String] JSON-serialized grammar
+      # @param inputs [Array<String>] Array of input strings to parse
+      # @param transform [Parsanol::Transform] Transform to apply to each result
+      # @param config [Config] Parallel configuration (optional)
+      # @return [Array<Object>] Array of transformed results
+      #
+      def parse_batch_with_transform(grammar_json, inputs, transform,
+config: Config.new)
+        results = parse_batch(grammar_json, inputs, config: config)
+        results.map { |result| transform.apply(result) }
+      end
+
+      # Get the number of available CPU cores for parallel processing.
+      #
+      # @return [Integer] Number of available cores
+      def available_cores
+        require "etc"
+        Etc.nprocessors
+      rescue StandardError
+        1
+      end
+
+      # Estimate optimal number of threads for a given input size.
+      #
+      # @param input_count [Integer] Number of inputs to process
+      # @return [Integer] Recommended number of threads
+      def optimal_threads(input_count)
+        cores = available_cores
+        # Don't use more threads than inputs
+        [cores, input_count].min
+      end
+    end
+  end
+end

data/lib/parsanol/parser.rb

@@ -0,0 +1,242 @@
+# 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.
+    #
+    # All parse modes return results with Slice objects that contain
+    # position information (offset, length, line, column). This enables
+    # source code extraction, error reporting, and remark attachment.
+    #
+    # @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 (always available, returns Slices with position)
+    # - :native - Use Rust extension if available, fallback to Ruby
+    # - :json - Return JSON string with position info for each value
+    #
+    # Options:
+    # - :reporter - Custom error reporter instance
+    # - :prefix - Allow partial matching (default: false)
+    #
+    # @return [Hash, Array, Parsanol::Slice] parsed result with position info
+    # @raise [Parsanol::ParseFailed] when parsing fails
+    #
+    # @example Parse and access position info
+    #   result = parser.parse("hello")
+    #   result[:name].offset         # => 0
+    #   result[:name].line_and_column # => [1, 1]
+    #   result[:name].to_s           # => "hello"
+    #
+    def parse(input, mode_or_opts = {}, **kwargs)
+      if mode_or_opts.is_a?(Hash) && !kwargs.key?(:mode)
+        # Legacy API: parse(input, options={})
+        merged = mode_or_opts.merge(kwargs)
+        if Parsanol::Native.available? && !merged.key?(:prefix) &&
+            !merged.key?(:reporter)
+          # Native backend by default; falls back to pure Ruby inside
+          # parse_native when the extension is missing.
+          parse_native(input, merged)
+        else
+          super(input, merged)
+        end
+      else
+        # New API: parse(input, mode:, **options)
+        mode = kwargs.delete(:mode) ||
+          (Parsanol::Native.available? ? :native : :ruby)
+        case mode
+        when :ruby
+          super(input, kwargs)
+        when :native
+          parse_native(input, kwargs)
+        when :json
+          parse_json(input, kwargs)
+        else
+          raise ArgumentError,
+                "Unknown mode: #{mode}. Valid modes: :ruby, :native, :json"
+        end
+      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
+
+    # Clear the Rust grammar cache to free memory.
+    #
+    # @return [nil]
+    # @raise [LoadError] if native parser is not available
+    def clear_grammar_cache
+      Parsanol::Native.clear_grammar_cache
+    end
+
+    # Get the current number of cached grammars in Rust.
+    #
+    # @return [Integer] number of cached grammars
+    # @raise [LoadError] if native parser is not available
+    def grammar_cache_size
+      Parsanol::Native.grammar_cache_size
+    end
+
+    # Get the grammar cache capacity.
+    #
+    # @return [Integer] maximum cache capacity
+    # @raise [LoadError] if native parser is not available
+    def grammar_cache_capacity
+      Parsanol::Native.grammar_cache_capacity
+    end
+
+    # Get cache statistics for both Ruby and Rust caches.
+    #
+    # @return [Hash] cache statistics including Ruby GRAMMAR_CACHE and Rust grammar cache
+    # @raise [LoadError] if native parser is not available for Rust stats
+    def cache_stats
+      Parsanol::Native.cache_stats
+    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
+        # Call base class parse directly (send needed since parse is defined in parent)
+        Parsanol::Atoms::Base.instance_method(:parse).bind_call(self, 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
+
+    # Native extension parsing with Ruby fallback.
+    # Returns results with Slice objects containing position info.
+    #
+    # @param input [String] input to parse
+    # @param opts [Hash] parsing options
+    # @return [Object] parse result with Slice objects for position info
+    #
+    def parse_native(input, opts)
+      if Parsanol::Native.available?
+        Parsanol::Native.parse(root, input)
+      else
+        Parsanol::Atoms::Base.instance_method(:parse).bind_call(self, input,
+                                                                opts)
+      end
+    end
+
+    # JSON output mode - returns JSON with position info.
+    # All Slice values are serialized with their position information.
+    #
+    # @param input [String] input to parse
+    # @param opts [Hash] parsing options
+    # @return [String] JSON representation with position info
+    #
+    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