parsanol 1.3.14-arm-linux → 1.3.15-arm-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee82309e5f5550d8b7e874fb457082c29e441044c21f0149108947c1908fc312
-  data.tar.gz: a58b979b3cca49c5fcc3ad04bbc592f2dc1995883500e13e1bdcab73fa3e41a9
+  metadata.gz: e98e448bc4374451a62e175387759b4db66c90160e5df3204e652c17a751ddd7
+  data.tar.gz: 7f081c2cd9e6fac46cd4e43d15c91a6755af3aad8b01c35b5cb542d190cf2786
 SHA512:
-  metadata.gz: d2cd46409841355d16f45d29cbe1d87fc57107bef76de6ef85c7f6cf9b154e25a0f6cb5b05f62235319b8ece92f283f6da772f834fbc629a11e867d23fd90435
-  data.tar.gz: b44083dd31df4bde64bb04d319ef9ef605f5aca0c1f03302c284918e6779bc8c809b774d59ec92ec9acb44728a2b3acf00945dc5b9488c9f2f8627c4ff11b7c9
+  metadata.gz: 682268466119952e99a678a79270d6fe69a449630665a8e082e7f01f709903f6190552053e6328ec74f47fd452d1b946bedd5b89687a20594debbe33a6e9a2d2
+  data.tar.gz: 386e99e3a11788991e7b1fc5fb0ae55a6c95caa0b60508c62c3f997492c213887135d9d7b4bcb04a72b7d9d8c8bd20a9b20b105b6a2e31cc78b814db32380306

data/lib/parsanol/atoms/base.rb

@@ -30,9 +30,34 @@ module Parsanol
       # @return [Object] the parsed result
       # @raise [Parsanol::ParseFailed] on parse failure
       def parse(source, options = {})
-        input = normalize_input(source)
         must_consume_all = !options[:prefix]
 
+        # Compiled-VM fast path: String input, full-consumption semantics.
+        # On failure (or unsupported grammar / budget exhaustion) fall
+        # through to the interpreter, which also produces the exact
+        # cause-tree diagnostics.
+        if must_consume_all && source.is_a?(String) &&
+            (program = VM.program_for(self))
+          result = VM.run(program, source, true)
+          if result == VM::BAIL
+            # Internal bail: fall back to the interpreter and skip the VM
+            # for this grammar from now on.
+            VM.disable_for!(self)
+          elsif result.first == :heavy
+            # Succeeded but burned >1/8 of the step budget —
+            # heavy-backtracking grammar; the memoizing interpreter is
+            # the better engine from now on.
+            VM.disable_for!(self)
+            return finalize_result(result[1])
+          elsif result.first
+            return finalize_result(result[1])
+          end
+          # Clean [false, nil]: the input does not parse — the interpreter
+          # reparse below produces the detailed cause tree.
+        end
+
+        input = normalize_input(source)
+
         # Initial parse attempt (no error collection)
         success, value = run_with_context(input, nil, must_consume_all)
         return finalize_result(value) if success

data/lib/parsanol/native/transformer.rb

@@ -132,9 +132,11 @@ module Parsanol
         # Transform the value
         transformed = transform(value, named: true)
 
-        # Check if value is a tagged repetition from native parser
+        # Check if value is a tagged repetition from native parser.
+        # The Rust handle path tags with Symbols, the batch decoder with
+        # ":repetition" Strings — accept both.
         is_tagged_repetition = value.is_a?(Array) && !value.empty? &&
-          value.first.is_a?(String) && value.first == REPETITION_TAG
+          [REPETITION_SYM, REPETITION_TAG].include?(value.first)
 
         # Check RAW value for repetition pattern BEFORE transformation
         # Array with items that all have the parent key
@@ -203,13 +205,12 @@ module Parsanol
           # Empty array from repetition stays as empty array
           if transformed.empty?
             { sym_key => EMPTY_ARRAY }
-          # Check if items already have the same key (avoid double-wrapping)
-          elsif transformed.all? do |item|
-            item.is_a?(Hash) && item.key?(sym_key)
-          end
+          # Hash items already carry their own capture names — a
+          # repetition of named captures keeps them as-is (parslet
+          # semantics); only unnamed items get the parent name per item.
+          elsif transformed.all?(Hash)
             { sym_key => transformed }
           else
-            # Wrap each item with the name
             { sym_key => transformed.map { |item| { sym_key => item } } }
           end
         elsif transformed.is_a?(::Parsanol::Slice) && transformed.empty?

data/lib/parsanol/native.rb

@@ -38,14 +38,14 @@ module Parsanol
       def parse(grammar, input)
         raise LoadError, "Native parser not available" unless available?
 
-        raw_ast =
-          if grammar.is_a?(String)
-            parse_json_grammar(grammar, input)
-          else
-            parse_atom_grammar(grammar, input)
-          end
-
-        BatchDecoder.decode_and_flatten(raw_ast, input, Parsanol::Slice)
+        # Both sub-methods return the final decoded tree; on native failure
+        # they fall back to the pure-Ruby parser, whose result is already
+        # final and must not be transformed again.
+        if grammar.is_a?(String)
+          parse_json_grammar(grammar, input)
+        else
+          parse_atom_grammar(grammar, input)
+        end
       end
 
       # Memory-bounded parsing without packrat cache.
@@ -65,12 +65,14 @@ module Parsanol
                          Parser.serialize_grammar(grammar)
                        end
 
+        # Decode here, not around the fallback: raise_native_parse_error
+        # returns the Ruby parser's already-final tree on success.
         begin
-          raw_ast = _parse_fresh_raw(grammar_json, input)
+          BatchDecoder.decode_and_flatten(_parse_fresh_raw(grammar_json, input),
+                                          input, Parsanol::Slice)
         rescue RuntimeError => e
           raise_native_parse_error(e, grammar, input)
         end
-        BatchDecoder.decode_and_flatten(raw_ast, input, Parsanol::Slice)
       end
 
       # Parse and return RAW AST without transformation.
@@ -201,7 +203,8 @@ module Parsanol
 
       # Pre-serialized JSON grammar path (library authors with cached JSON).
       def parse_json_grammar(grammar_json, input)
-        _parse_raw(grammar_json, input)
+        BatchDecoder.decode_and_flatten(_parse_raw(grammar_json, input),
+                                        input, Parsanol::Slice)
       rescue RuntimeError => e
         raise_native_parse_error(e, grammar_json, input)
       end
@@ -212,12 +215,16 @@ module Parsanol
         handle = Parser.grammar_handle(grammar)
 
         begin
-          _parse_handle(handle, input)
+          BatchDecoder.decode_and_flatten(_parse_handle(handle, input),
+                                          input, Parsanol::Slice)
         rescue ArgumentError
           # Handle dropped Rust-side (e.g. cache cleared): re-register once.
           Parser.invalidate_handle(handle)
           begin
-            _parse_handle(Parser.grammar_handle(grammar), input)
+            BatchDecoder.decode_and_flatten(
+              _parse_handle(Parser.grammar_handle(grammar), input),
+              input, Parsanol::Slice
+            )
           rescue RuntimeError => e
             raise_native_parse_error(e, grammar, input)
           end

data/lib/parsanol/parser.rb

@@ -109,32 +109,36 @@ module Parsanol
     #   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)
+      opts =
+        if mode_or_opts.is_a?(Hash)
+          mode_or_opts.merge(kwargs)
+        elsif mode_or_opts.nil?
+          kwargs
         else
-          super(input, merged)
+          # New API: parse(input, :mode, **options)
+          kwargs[:mode] = mode_or_opts
+          kwargs
         end
+      # parse(input, {mode: :ruby, ...}) is the same call shape a subclass
+      # forwarding options via super produces; :mode must be honored
+      # wherever it appears, or those callers silently get the native path.
+      mode = opts.delete(:mode) ||
+        (if Parsanol::Native.available? && !opts.key?(:prefix) &&
+              !opts.key?(:reporter)
+           :native
+         else
+           :ruby
+         end)
+      case mode
+      when :ruby
+        super(input, opts)
+      when :native
+        parse_native(input, opts)
+      when :json
+        parse_json(input, opts)
       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
+        raise ArgumentError,
+              "Unknown mode: #{mode}. Valid modes: :ruby, :native, :json"
       end
     end
 

data/lib/parsanol/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Parsanol
-  VERSION = "1.3.14"
+  VERSION = "1.3.15"
 end

data/lib/parsanol/vm.rb

@@ -0,0 +1,962 @@
+# frozen_string_literal: true
+
+require "strscan"
+require "parsanol/atoms/can_flatten"
+
+module Parsanol
+  # Bytecode VM for the pure-Ruby parse path.
+  #
+  # Compiles an atom tree once into a flat integer program and executes it
+  # with a single dispatch loop. Terminals record packed span Integers
+  # ((pos << 20) | len) instead of allocating Slices; composite values
+  # mirror the interpreter's tagged arrays exactly. A bottom-up
+  # materialization pass turns spans into Slices and Named markers into
+  # their eagerly-flattened hashes, so output is byte-identical to the
+  # tree interpreter (mode: :ruby).
+  #
+  # Design notes: TODO.perf/6-ruby-vm.md
+  module VM
+    HALT = 0
+    STR = 1
+    RE = 2
+    ANY = 3
+    SEQ_BEGIN = 4
+    SEQ_END = 5
+    CHOICE = 6
+    POPBT = 7
+    JMP = 8
+    NAME_END = 9
+    CALL = 10
+    RET = 11
+    LOOK_POS = 12
+    LOOK_POS_END = 13
+    LOOK_NEG = 14
+    LOOK_NEG_END = 15
+    DROP = 16
+    FAIL = 17
+    REP_INIT = 18
+    REP_TEST = 19
+    REP_STEP = 20
+    REP_EXIT = 21
+    MAYBE_RE = 22
+    MAYBE_STR = 23
+    RUN_RE = 24
+    RUN_STR = 25
+    SEQ_SIMPLE = 26
+
+    K_ALT = 0
+    K_REP = 1
+    K_LOOK_FAIL = 2
+    K_NEG = 3
+
+    SEQ_MARK = Object.new.freeze
+
+    # Deferred Named wrapper; materialization produces
+    # { name => flatten(inner, named: true) } like Named#apply.
+    NamedValue = Struct.new(:name, :value)
+
+    SINGLE_CLASS_RE = /\A(?:\^)?(?:\[[^\[\]]*\]|\\[dDwWsShH]|\\x[0-9a-fA-F]{2}|\\[0-7]{1,3}|[^\[\\\]|()?*+{}\^])\z/
+
+    CHAR_WIDTH = Array.new(256, 0)
+    (0...128).each { |b| CHAR_WIDTH[b] = 1 }
+    (0xC2..0xDF).each { |b| CHAR_WIDTH[b] = 2 }
+    (0xE0..0xEF).each { |b| CHAR_WIDTH[b] = 3 }
+    (0xF0..0xF4).each { |b| CHAR_WIDTH[b] = 4 }
+
+    MAX_PACK_LEN = (1 << 20) - 1
+    FRAME_STRIDE = 4 # count, end_pos, rbase, min
+    BT_STRIDE = 6    # pc, pos, rlen, cbase, clen, kind
+    # Returned (as the sole value) when the VM cannot complete a parse
+    # for internal reasons — callers should fall back to the interpreter
+    # and may skip the VM for this grammar afterwards. A clean
+    # [false, nil] means the input genuinely does not parse.
+    BAIL = Object.new.freeze
+
+    STEP_BUDGET_FACTOR = 200
+    STEP_BUDGET_FIXED = 10_000
+
+    class << self
+      @programs = {}
+
+      # Cached compile keyed by root-atom object identity. Atoms are
+      # effectively immutable once constructed; false caches grammars the
+      # VM cannot handle so we do not re-walk them on every parse.
+      #
+      # A grammar whose VM run failed once (unsupported backtracking shape
+      # or step budget) is marked :fallback so later parses skip the VM
+      # attempt entirely — the interpreter result is identical.
+      def program_for(atom)
+        root = atom.is_a?(Parsanol::Parser) ? atom.root : atom
+        key = root.object_id
+        cache = (@programs ||= {})
+        cached = cache[key]
+        return nil if cached == :fallback
+        return cached if key?(cache, key)
+
+        cache[key] = compile(atom)
+      end
+
+      # Marks a grammar as VM-incompatible after a runtime failure.
+      def disable_for!(atom)
+        root = atom.is_a?(Parsanol::Parser) ? atom.root : atom
+        (@programs ||= {})[root.object_id] = :fallback # rubocop:disable Lint/HashCompareByIdentity -- object_id keys avoid holding strong references to grammar atoms
+      end
+
+      def key?(cache, key) # rubocop:disable Naming/PredicateMethod -- mirrors Hash#key?
+        cache.key?(key)
+      end
+
+      def clear_program_cache
+        @programs&.clear
+      end
+
+      # Compiles the grammar rooted at +atom+. Returns the flat program
+      # Array, or nil when the grammar uses unsupported atoms.
+      def compile(atom)
+        root = atom.is_a?(Parsanol::Parser) ? atom.root : atom
+        compiler = Compiler.new
+        return nil unless compiler.compile_atom(root, true)
+
+        # HALT terminates the MAIN program; subroutines follow it so the
+        # root CALL's return address can never collide with a subroutine.
+        compiler.ops << [HALT, nil, nil, nil]
+        return nil unless compiler.append_subroutines
+
+        compiler.to_program
+      end
+
+      # Executes a compiled program. Returns [true, value] on success;
+      # [false, nil] on failure or budget exhaustion — callers fall back
+      # to the interpreter, which reproduces exact diagnostics.
+      def run(program, input, consume_all)
+        Executor.new(program, input, consume_all).execute
+      end
+
+      # Converts the VM value tree into the interpreter's value tree.
+      def materialize(value, input)
+        case value
+        when Integer
+          pos = value >> 20
+          Slice.new(pos, input.byteslice(pos, value & MAX_PACK_LEN), input)
+        when NamedValue
+          { value.name => Mat.flatten(materialize(value.value, input), true) }
+        when Array
+          value.map { |v| materialize(v, input) }
+        when Hash
+          value.transform_values { |v| materialize(v, input) }
+        else
+          value
+        end
+      end
+    end
+
+    module Mat
+      extend Parsanol::Atoms::CanFlatten
+    end
+    private_constant :Mat
+
+    # Compiles atoms into a flat stride-4 program. Entity bodies compile
+    # as subroutines, keyed by [body object_id, consume_all] so spine
+    # sites (consume_all=true) and inner sites stay semantically distinct.
+    class Compiler
+      def initialize
+        @ops = []
+        @subs = {}      # [obj_id, flag] => pc or :pending
+        @pending = {}   # [obj_id, flag] => [[call_idx, body], ...]
+      end
+
+      attr_reader :ops
+
+      def to_program
+        return nil if @ops.size > MAX_PROGRAM
+
+        @ops.flatten!(1)
+      end
+
+      def compile_atom(atom, consume_all)
+        case atom
+        when Parsanol::Atoms::Str
+          bytes = atom.str.unpack("C*")
+          emit(STR, bytes, bytes.size, atom.str.bytesize)
+          self
+        when Parsanol::Atoms::Re
+          emit(RE, atom.re, byte_table(atom.re), nil)
+          self
+        when Parsanol::Atoms::Sequence
+          parslets = atom.parslets
+          n = parslets.size
+          return nil if n.zero?
+
+          simple = simple_children(parslets, consume_all)
+          if simple
+            emit(SEQ_SIMPLE, simple, nil, nil)
+            return self
+          end
+
+          emit(SEQ_BEGIN)
+          last = n - 1
+          idx = 0
+          while idx < n
+            return nil unless compile_atom(parslets[idx], consume_all && idx == last)
+
+            idx += 1
+          end
+          emit(SEQ_END)
+          self
+        when Parsanol::Atoms::Alternative
+          alts = atom.alternatives
+          count = alts.size
+          return nil if count.zero?
+
+          jumps = []
+          idx = 0
+          while idx < count
+            last_alt = idx == count - 1
+            choice = (emit(CHOICE, nil, nil, nil) unless last_alt)
+            return nil unless compile_atom(alts[idx], consume_all)
+
+            unless last_alt
+              # The branch matched: drop this CHOICE's backtrack entry
+              # (ordered choice commits) before skipping the rest.
+              emit(POPBT)
+              jumps << emit(JMP, nil, nil, nil)
+            end
+            patch(choice, 1, flat(@ops.size)) if choice
+            idx += 1
+          end
+          jumps.each { |j| patch(j, 1, flat(@ops.size)) }
+          self
+        when Parsanol::Atoms::Repetition
+          compile_repetition(atom, consume_all)
+        when Parsanol::Atoms::Named
+          return nil unless compile_atom(atom.parslet, consume_all)
+
+          emit(NAME_END, atom.name, nil, nil)
+          self
+        when Parsanol::Atoms::Entity
+          compile_entity(atom, consume_all)
+        when Parsanol::Atoms::Lookahead
+          compile_lookahead(atom, consume_all)
+        when Parsanol::Atoms::Ignored
+          inner = atom.wrapped_atom
+          return nil if inner.nil?
+          return nil unless compile_atom(inner, consume_all)
+
+          emit(DROP)
+          self
+          # Dynamic, Capture, Scope, Cut, Custom, Infix, unknown
+        end
+      end
+
+      def append_subroutines # rubocop:disable Naming/PredicateMethod -- mutating; returns compile success, not a predicate
+        until @pending.empty?
+          key, list = @pending.shift
+          body = list.first[1]
+          flag = key[1]
+          sub = @ops.size
+          # Register before compiling so recursive references resolve.
+          @subs[key] = sub
+          return false unless compile_atom(body, flag)
+
+          emit(RET)
+          list.each { |entry| patch(entry[0], 1, flat(sub)) } # rubocop:disable Style/HashEachMethods -- Array of [call_idx, body] pairs, not a Hash
+        end
+        true
+      end
+
+      MAX_PROGRAM = 40_000 # instructions; larger grammars fall back
+
+      private
+
+      def emit(op, a = nil, b = nil, c = nil) # rubocop:disable Naming/MethodParameterName -- opcode operand slots
+        @ops << [op, a, b, c]
+        @ops.size - 1
+      end
+
+      def patch(idx, slot, value)
+        @ops[idx][slot] = value
+      end
+
+      # Compiler works in instruction indexes; the executor's pc indexes
+      # the flattened array (4 slots per instruction).
+      def flat(instr_index)
+        instr_index * 4
+      end
+
+      # Returns a flat [op, a, b, c, ...] descriptor array when every
+      # child compiles to a single-value fused op, else nil.
+      def simple_children(parslets, consume_all)
+        kids = []
+        last = parslets.size - 1
+        parslets.each_with_index do |child, idx|
+          spine = consume_all && idx == last
+          op = simple_child(child, spine)
+          return nil if op.nil?
+
+          kids.concat(op)
+        end
+        kids
+      end
+
+      def simple_child(atom, spine)
+        case atom
+        when Parsanol::Atoms::Str
+          bytes = atom.str.unpack("C*")
+          [STR, bytes, bytes.size, atom.str.bytesize]
+        when Parsanol::Atoms::Re
+          [RE, atom.re, byte_table(atom.re), nil]
+        when Parsanol::Atoms::Repetition
+          min = atom.min
+          max = atom.max
+          return nil if max&.zero? || spine
+
+          body = atom.parslet
+          if min.zero? && max == 1
+            case body
+            when Parsanol::Atoms::Re
+              [MAYBE_RE, body.re, byte_table(body.re), nil]
+            when Parsanol::Atoms::Str
+              bytes = body.str.unpack("C*")
+              [MAYBE_STR, bytes, bytes.size, body.str.bytesize]
+            end
+          elsif min >= 1 && max.nil?
+            case body
+            when Parsanol::Atoms::Re
+              [RUN_RE, body.re, byte_table(body.re), min]
+            when Parsanol::Atoms::Str
+              bytes = body.str.unpack("C*")
+              [RUN_STR, bytes, bytes.size, min]
+            end
+          end
+        end
+      end
+
+      # Repetition compilation with terminal fusions:
+      # * maybe(0,1) of a single terminal -> one MAYBE_* op (no backtrack
+      #   entry, no unwind cycle on the empty path)
+      # * unbounded-plus of a single terminal (non-spine sites) -> greedy
+      #   RUN_* op
+      def compile_repetition(atom, consume_all)
+        min = atom.min
+        max = atom.max
+        return nil if max&.zero?
+
+        body = atom.parslet
+        if min.zero? && max == 1 && !consume_all
+          case body
+          when Parsanol::Atoms::Re
+            emit(MAYBE_RE, body.re, byte_table(body.re), nil)
+            return self
+          when Parsanol::Atoms::Str
+            bytes = body.str.unpack("C*")
+            emit(MAYBE_STR, bytes, bytes.size, body.str.bytesize)
+            return self
+          end
+        end
+        if min >= 1 && max.nil? && !consume_all
+          case body
+          when Parsanol::Atoms::Re
+            emit(RUN_RE, body.re, byte_table(body.re), min)
+            return self
+          when Parsanol::Atoms::Str
+            bytes = body.str.unpack("C*")
+            emit(RUN_STR, bytes, bytes.size, min)
+            return self
+          end
+        end
+
+        emit(REP_INIT, min, nil, nil)
+        test = emit(REP_TEST, nil, max, nil)
+        return nil unless compile_atom(body, false)
+
+        step = emit(REP_STEP, nil, nil, max)
+        exit_ = emit(REP_EXIT, atom.result_tag, consume_all ? 1 : 0, nil)
+        patch(test, 1, flat(exit_))
+        patch(step, 1, flat(test))
+        patch(step, 2, flat(exit_))
+        self
+      end
+
+      def compile_entity(atom, consume_all)
+        body = begin
+          atom.parslet
+        rescue StandardError
+          nil
+        end
+        return nil if body.nil?
+
+        # Leaf entities are transparent: a rule whose body is a single
+        # terminal compiles inline, skipping the CALL/RET round trip.
+        case body
+        when Parsanol::Atoms::Str
+          bytes = body.str.unpack("C*")
+          emit(STR, bytes, bytes.size, body.str.bytesize)
+          return self
+        when Parsanol::Atoms::Re
+          emit(RE, body.re, byte_table(body.re), nil)
+          return self
+        end
+
+        # Non-recursive rules inline: the body's ops replace the CALL/RET
+        # round trip entirely. A body currently being compiled (directly
+        # or indirectly) is recursive and must stay a subroutine.
+        # rubocop:disable Lint/HashCompareByIdentity -- object_id keys; would otherwise pin every atom alive
+        unless (@compiling ||= {})[body.object_id]
+          @compiling[body.object_id] = true
+          # rubocop:enable Lint/HashCompareByIdentity
+          result = compile_atom(body, consume_all)
+          @compiling.delete(body.object_id)
+          return result if result
+
+          return nil
+        end
+
+        key = [body.object_id, consume_all]
+        sub = @subs[key]
+        if sub.is_a?(Integer)
+          emit(CALL, flat(sub), nil, nil)
+        else
+          call_idx = emit(CALL, nil, nil, nil)
+          (@pending[key] ||= []) << [call_idx, body]
+          @subs[key] = :pending if sub.nil?
+        end
+        self
+      end
+
+      def compile_lookahead(atom, consume_all)
+        positive = atom.positive
+        bound = atom.bound_parslet
+        return nil if bound.nil?
+
+        entry = emit(positive ? LOOK_POS : LOOK_NEG, nil, nil, nil)
+        return nil unless compile_atom(bound, consume_all)
+
+        emit(positive ? LOOK_POS_END : LOOK_NEG_END)
+        patch(entry, 1, flat(@ops.size)) # continuation for K_NEG entries
+        self
+      end
+
+      # 256-entry table: "regex matches a prefix consisting of exactly this
+      # ASCII byte" — only when the regex is provably a single-char class.
+      def byte_table(re) # rubocop:disable Naming/MethodParameterName
+        return nil unless SINGLE_CLASS_RE.match?(re.source)
+        return nil if re.match?("") # can match empty -> not byte-local
+
+        table = Array.new(256, false)
+        (1..127).each do |b|
+          table[b] = true if re.match?(b.chr)
+        end
+        table
+      end
+    end
+
+    # One execution of a compiled program over one input string.
+    # When a parse succeeds but consumed a large fraction of the step
+    # budget, the grammar backtracks heavily and the tree interpreter
+    # (with its adaptive memoization) is the better engine; #run reports
+    # this via :heavy so Base#parse can skip the VM for the grammar.
+    class Executor
+      def initialize(program, input, consume_all)
+        @ops = program
+        @input = input
+        @consume_all = consume_all
+      end
+
+      def execute # rubocop:disable Metrics/MethodLength, Metrics/BlockLength, Metrics/BlockNesting -- single dispatch loop; hot path
+        ops = @ops
+        input = @input
+        bytes = input.unpack("C*")
+        # Regexp#match?(str, pos) searches FORWARD from pos (unanchored);
+        # StringScanner#match? is position-anchored, matching the
+        # interpreter's Source#matches? semantics exactly.
+        scanner = StringScanner.new(input)
+        n = bytes.size
+        budget = (STEP_BUDGET_FACTOR * n) + STEP_BUDGET_FIXED
+        steps = 0
+
+        pc = 0
+        pos = 0
+        rstack = []
+        bt = []
+        frames = []
+        calls = []
+
+        # rubocop:disable-next Metrics/BlockLength -- the dispatch loop IS execute
+        loop do
+          steps += 1
+          return BAIL if steps > budget
+
+          if pc == FAIL
+            pc, pos = unwind(bt, rstack, frames, calls)
+            return [false, nil] if pc == :fail
+            return BAIL if pc == :bail
+
+            next
+          end
+
+          case ops[pc]
+          when STR
+            lit = ops[pc + 1]
+            ln = ops[pc + 2]
+            i = 0
+            matched = true
+            while i < ln
+              if bytes[pos + i] != lit[i]
+                matched = false
+                break
+              end
+              i += 1
+            end
+            if matched
+              rstack << ((pos << 20) | ln)
+              pos += ops[pc + 3]
+              pc += 4
+            else
+              pc = FAIL
+            end
+          when RE
+            b = bytes[pos]
+            matched =
+              if (table = ops[pc + 2]) && b && b < 128
+                table[b]
+              elsif pos < n
+                (scanner.pos = pos) && scanner.match?(ops[pc + 1])
+              else
+                false
+              end
+            if matched
+              w = CHAR_WIDTH[b]
+              w = char_width_slow(input, pos) if w.zero?
+              rstack << ((pos << 20) | w)
+              pos += w
+              pc += 4
+            else
+              pc = FAIL
+            end
+          when ANY
+            if pos < n
+              w = CHAR_WIDTH[bytes[pos]]
+              w = char_width_slow(input, pos) if w.zero?
+              rstack << ((pos << 20) | w)
+              pos += w
+              pc += 4
+            else
+              pc = FAIL
+            end
+          when SEQ_BEGIN
+            rstack << SEQ_MARK
+            pc += 4
+          when SEQ_END
+            # Pop pushes in reverse; append and single reverse (O(n), no
+            # per-element unshift).
+            values = []
+            guard = rstack.size
+            ok_seq = false
+            while guard.positive?
+              v = rstack.pop
+              guard -= 1
+              if v == SEQ_MARK
+                ok_seq = true
+                break
+              end
+              values << v
+            end
+            return [false, nil] unless ok_seq
+
+            values << :sequence
+            values.reverse!
+            rstack << values
+            pc += 4
+          when CHOICE
+            bt << ops[pc + 1] << pos << rstack.size << frames.size << calls.size << K_ALT
+            pc += 4
+          when POPBT
+            bt.pop(BT_STRIDE)
+            pc += 4
+          when JMP
+            pc = ops[pc + 1]
+          when NAME_END
+            rstack << VM::NamedValue.new(ops[pc + 1], rstack.pop)
+            pc += 4
+          when CALL
+            calls << (pc + 4)
+            pc = ops[pc + 1]
+          when RET
+            pc = calls.pop
+            return BAIL if pc.nil?
+          when LOOK_POS
+            bt << ops[pc + 1] << pos << rstack.size << frames.size << calls.size << K_LOOK_FAIL
+            pc += 4
+          when LOOK_POS_END
+            # Body matched: restore entry's saved pos, drop entry and the
+            # body's value, push nil like Lookahead#try.
+            pos = bt[-BT_STRIDE + 1]
+            bt.pop(BT_STRIDE)
+            rstack.pop
+            rstack << nil
+            pc += 4
+          when LOOK_NEG
+            bt << ops[pc + 1] << pos << rstack.size << frames.size << calls.size << K_NEG
+            pc += 4
+          when LOOK_NEG_END
+            # Body matched: negative lookahead fails. Drop entry + body
+            # values, then propagate failure outward.
+            rlen = bt[-BT_STRIDE + 2]
+            rstack.slice!(rlen..) if rstack.size > rlen
+            bt.pop(BT_STRIDE)
+            pc = FAIL
+          when DROP
+            rstack.pop
+            rstack << nil
+            pc += 4
+          when REP_INIT
+            frames << 0 << pos << rstack.size << ops[pc + 1] # count,end,rbase,min
+            pc += 4
+          when REP_TEST
+            cbase = frames.size - FRAME_STRIDE
+            count = frames[cbase]
+            return BAIL if count.nil?
+
+            max = ops[pc + 2]
+            if max && count >= max
+              pc = ops[pc + 1] # exit
+            else
+              bt << ops[pc + 1] << frames[cbase + 1] << rstack.size << cbase << calls.size << K_REP
+              pc += 4 # body
+            end
+          when REP_STEP
+            bt.pop(BT_STRIDE)
+            cbase = frames.size - FRAME_STRIDE
+            count = frames[cbase]
+            return BAIL if count.nil?
+
+            count += 1
+            frames[cbase] = count
+            frames[cbase + 1] = pos
+            max = ops[pc + 3]
+            pc = if max && count >= max
+                   ops[pc + 2] # exit
+                 else
+                   ops[pc + 1] # test
+                 end
+          when REP_EXIT
+            cbase = frames.size - FRAME_STRIDE
+            return BAIL if frames[cbase].nil?
+
+            if ops[pc + 2] == 1 && pos != n
+              frames.slice!(cbase..)
+              pc = FAIL
+            else
+              rbase = frames[cbase + 2]
+              values = rstack.pop(rstack.size - rbase)
+              values.unshift(ops[pc + 1])
+              rstack << values
+              frames.slice!(cbase..)
+              pc += 4
+            end
+          when SEQ_SIMPLE
+            kids = ops[pc + 1]
+            kn = kids.size
+            values = [:sequence]
+            ki = 0
+            failed = false
+            while ki < kn
+              kop = kids[ki]
+              ka = kids[ki + 1]
+              kb = kids[ki + 2]
+              kc = kids[ki + 3]
+              case kop
+              when RE
+                b = bytes[pos]
+                m = if kb && b && b < 128
+                      kb[b]
+                    elsif pos < n
+                      (scanner.pos = pos) && scanner.match?(ka)
+                    else
+                      false
+                    end
+                if m
+                  w = CHAR_WIDTH[b]
+                  w = char_width_slow(input, pos) if w.zero?
+                  values << ((pos << 20) | w)
+                  pos += w
+                else
+                  failed = true
+                end
+              when STR
+                i = 0
+                ln = kb
+                m = true
+                while i < ln
+                  if bytes[pos + i] != ka[i] # rubocop:disable Metrics/BlockNesting -- fused byte-compare loop
+                    m = false
+                    break
+                  end
+                  i += 1
+                end
+                if m
+                  values << ((pos << 20) | ln)
+                  pos += kc
+                else
+                  failed = true
+                end
+              when MAYBE_RE
+                b = bytes[pos]
+                m = if kb && b && b < 128
+                      kb[b]
+                    elsif pos < n
+                      (scanner.pos = pos) && scanner.match?(ka)
+                    else
+                      false
+                    end
+                if m
+                  w = CHAR_WIDTH[b]
+                  w = char_width_slow(input, pos) if w.zero?
+                  values << [:maybe, (pos << 20) | w]
+                  pos += w
+                else
+                  values << [:maybe]
+                end
+              when MAYBE_STR
+                i = 0
+                ln = kb
+                m = true
+                while i < ln
+                  if bytes[pos + i] != ka[i] # rubocop:disable Metrics/BlockNesting -- fused byte-compare loop
+                    m = false
+                    break
+                  end
+                  i += 1
+                end
+                if m
+                  values << [:maybe, (pos << 20) | ln]
+                  pos += kc
+                else
+                  values << [:maybe]
+                end
+              when RUN_RE
+                loop do
+                  b = bytes[pos]
+                  m = if kb && b && b < 128
+                        kb[b]
+                      elsif pos < n
+                        (scanner.pos = pos) && scanner.match?(ka)
+                      else
+                        false
+                      end
+                  break unless m
+
+                  w = CHAR_WIDTH[b]
+                  w = char_width_slow(input, pos) if w.zero?
+                  values << ((pos << 20) | w)
+                  pos += w
+                end
+              when RUN_STR
+                loop do
+                  i = 0
+                  ln = kb
+                  m = true
+                  while i < ln
+                    if bytes[pos + i] != ka[i] # rubocop:disable Metrics/BlockNesting -- fused byte-compare loop
+                      m = false
+                      break
+                    end
+                    i += 1
+                  end
+                  break unless m
+
+                  values << ((pos << 20) | ln)
+                  pos += ln
+                end
+              end
+              break if failed
+
+              ki += 4
+            end
+            if failed
+              pc = FAIL
+            else
+              rstack << values
+              pc += 4
+            end
+          when MAYBE_RE
+            b = bytes[pos]
+            matched =
+              if (table = ops[pc + 2]) && b && b < 128
+                table[b]
+              elsif pos < n
+                (scanner.pos = pos) && scanner.match?(ops[pc + 1])
+              else
+                false
+              end
+            if matched
+              w = CHAR_WIDTH[b]
+              w = char_width_slow(input, pos) if w.zero?
+              rstack << [:maybe, (pos << 20) | w]
+              pos += w
+            else
+              rstack << [:maybe]
+            end
+            pc += 4
+          when MAYBE_STR
+            lit = ops[pc + 1]
+            ln = ops[pc + 2]
+            i = 0
+            matched = true
+            while i < ln
+              if bytes[pos + i] != lit[i]
+                matched = false
+                break
+              end
+              i += 1
+            end
+            if matched
+              rstack << [:maybe, (pos << 20) | ln]
+              pos += ops[pc + 3]
+            else
+              rstack << [:maybe]
+            end
+            pc += 4
+          when RUN_RE
+            re = ops[pc + 1]
+            table = ops[pc + 2]
+            min = ops[pc + 3]
+            values = [:repetition]
+            loop do
+              b = bytes[pos]
+              m = if table && b && b < 128
+                    table[b]
+                  elsif pos < n
+                    (scanner.pos = pos) && scanner.match?(re)
+                  else
+                    false
+                  end
+              break unless m
+
+              w = CHAR_WIDTH[b]
+              w = char_width_slow(input, pos) if w.zero?
+              values << ((pos << 20) | w)
+              pos += w
+            end
+            if min && values.size - 1 < min
+              pc = FAIL
+            else
+              rstack << values
+              pc += 4
+            end
+          when RUN_STR
+            lit = ops[pc + 1]
+            ln = ops[pc + 2]
+            min = ops[pc + 3]
+            values = [:repetition]
+            loop do
+              i = 0
+              matched = true
+              while i < ln
+                if bytes[pos + i] != lit[i]
+                  matched = false
+                  break
+                end
+                i += 1
+              end
+              break unless matched
+
+              values << ((pos << 20) | ln)
+              pos += ln
+            end
+            if min && values.size - 1 < min
+              pc = FAIL
+            else
+              rstack << values
+              pc += 4
+            end
+          when HALT
+            if @consume_all && pos != n
+              pc = FAIL
+              next
+            end
+            value = VM.materialize(rstack[0], input)
+            # More than ~100 steps per input byte means heavy
+            # backtracking; the memoizing interpreter wins there.
+            return steps > (n << 9) + 1000 ? [:heavy, value] : [true, value]
+          else
+            return BAIL
+          end
+        end
+      end
+
+      private
+
+      # Unwind one backtrack entry. Returns [pc, pos] or :fail. Repetition
+      # entries with count >= min complete their tagged array and jump to
+      # the exit continuation with the last iteration end position.
+      def unwind(bt, rstack, frames, calls) # rubocop:disable Naming/MethodParameterName -- stack register names
+        return :fail if bt.empty?
+
+        # Everything above this entry belongs to constructs being
+        # abandoned by the jump (inner alternatives, repetitions, or
+        # subroutine state); discard it along with the entry itself.
+        blen = bt.size - BT_STRIDE
+        if ENV["VM_TRACE"]
+          warn "  UNWIND bt=#{bt.each_slice(6).map { |e| "[#{e[0]},#{e[1]},#{e[2]},#{e[3]},#{e[4]},#{e[5]}" }.join(' ')}"
+        end
+        kind = bt.pop
+        clen = bt.pop
+        cbase = bt.pop
+        rlen = bt.pop
+        epos = bt.pop
+        epc = bt.pop
+        bt.slice!(blen..) if bt.size > blen
+
+        rstack.slice!(rlen..) if rstack.size > rlen
+        calls.slice!(clen..) if calls.size > clen
+
+        case kind
+        when K_ALT
+          frames.slice!(cbase..) if frames.size > cbase
+          [epc, epos]
+        when K_REP
+          count = frames[cbase]
+          min = frames[cbase + 3]
+          if count.nil? || min.nil?
+            return :bail
+          end
+
+          if count >= min
+            # Repetition succeeds with the completed prefix.
+            rbase = frames[cbase + 2]
+            end_pos = frames[cbase + 1]
+            tag = @ops[epc + 1]
+            check_full = @ops[epc + 2]
+            if check_full == 1 && end_pos != @input.bytesize
+              frames.slice!(cbase..)
+              unwind(bt, rstack, frames, calls)
+            else
+              values = rstack.pop(rstack.size - rbase)
+              values.unshift(tag)
+              rstack << values
+              frames.slice!(cbase..)
+              [epc + 4, end_pos]
+            end
+          else
+            frames.slice!(cbase..)
+            unwind(bt, rstack, frames, calls)
+          end
+        when K_LOOK_FAIL
+          frames.slice!(cbase..) if frames.size > cbase
+          unwind(bt, rstack, frames, calls)
+        when K_NEG
+          # Negative lookahead body failed -> lookahead succeeds.
+          frames.slice!(cbase..) if frames.size > cbase
+          rstack << nil
+          [epc, epos]
+        end
+      end
+
+      def char_width_slow(input, pos)
+        w = CHAR_WIDTH[input.getbyte(pos)]
+        w.zero? ? 1 : w
+      end
+    end
+  end
+end

data/lib/parsanol.rb

@@ -259,6 +259,7 @@ require "parsanol/atoms"
 require "parsanol/pattern"
 require "parsanol/pattern/binding"
 require "parsanol/transform"
+require "parsanol/vm"
 require "parsanol/parser"
 require "parsanol/error_reporter"
 require "parsanol/scope"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parsanol
 version: !ruby/object:Gem::Version
-  version: 1.3.14
+  version: 1.3.15
 platform: arm-linux
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -238,6 +238,7 @@ files:
 - lib/parsanol/string_view.rb
 - lib/parsanol/transform.rb
 - lib/parsanol/version.rb
+- lib/parsanol/vm.rb
 - lib/parsanol/wasm/README.md
 - lib/parsanol/wasm/package.json
 - lib/parsanol/wasm/parsanol.js