parsanol 1.3.132-aarch64-linux → 1.3.134-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 858f8defa63f9c570ba144672710e3d152dcf8c9e4e2433ca63085f2c6573b1e
-  data.tar.gz: 2c45e86e29e2a55f4ef6c312bfcb42d5766b7e7f343ee74ee903f080f47fa839
+  metadata.gz: a705fd766cfedfe219e944de94e684d5706a0f71f0a2322a74c235949efe89d0
+  data.tar.gz: 5be20b0bbf1a79c3302ca33f2df3489adbfce902463c9c3eb27417add5c34531
 SHA512:
-  metadata.gz: 837d88e5055370b3929b7626f4045a95112f8745fed10a90cfe79b8fe6df6acfc5337bbaf9d80fe6f2431912f83e26cc5665b7f1dd6a8295661c1d13e8c1317c
-  data.tar.gz: 12d330e16733a67a038b2cb2750f3a514375b1bbf5dcd778f20fb8128f33dd7fcfc5d07cb4d38dfca8842d7d1ade199f688facf3d5089fef47e53cdfe4e4a7d5
+  metadata.gz: 8012b30cbbb2abe03ed46b7a2acb0e7b25fbbc6a2201242f2ff95eebc5a315d100e14859008661316e56c15f0900cdff22bb6ee992164f99a4a1a5b3dc1dcab7
+  data.tar.gz: e76a33d0062a73072b77b4eb187d21fa06dc29c71f6a1929f0878cc1e087759382247237475990b74d19d0074c9328aaa36ccf9c6bff2a742cdebe33bc88a79e

data/lib/parsanol/native/parser.rb

@@ -99,7 +99,7 @@ module Parsanol
             return handle
           end
 
-          json = legacy ? GrammarSerializer.serialize(root_atom) : grammar_json(root_atom)
+          json = legacy ? GrammarSerializer.serialize(root_atom, preserve_identity: true) : grammar_json(root_atom)
           handle = Native._register_grammar(json)
           HANDLE_CACHE[cache_key] = handle
           trim_caches

data/lib/parsanol/native/serializer.rb

@@ -8,14 +8,22 @@ module Parsanol
     # Serialize a Parslet grammar (root atom) to JSON string
     #
     # @param root [Parsanol::Atoms::Base] The root atom of the grammar
+    # @param preserve_identity [Boolean] emit exactly one wire atom per
+    #   Ruby atom, even when an atom is reached again through a recursive
+    #   rule while its own children are still being serialized. Parslet
+    #   compatibility needs this: its memo is keyed by atom identity, so a
+    #   duplicated wire atom splits one memo entry in two and the native
+    #   engine can pick a different alternative than the Ruby engine. The
+    #   default keeps the established wire layout of strict grammars.
     # @return [String] JSON representation of the grammar
-    def self.serialize(root)
+    def self.serialize(root, preserve_identity: false)
       # Create fresh instance for each serialization
       # (state is specific to each grammar)
-      new.serialize(root)
+      new(preserve_identity: preserve_identity).serialize(root)
     end
 
-    def initialize
+    def initialize(preserve_identity: false)
+      @preserve_identity = preserve_identity
       @atoms = []
       @atom_cache = {} # object_id => atom_id for deduplication
       # Strong retention: cache keys are object_ids; without holding the
@@ -52,74 +60,19 @@ module Parsanol
       # Don't create a new atom, just resolve and return the referenced atom_id
       return serialize_entity(atom) if atom.is_a?(Parsanol::Atoms::Entity)
 
-      # Serialize based on atom type first (recursively)
-      serialized = case atom
-                   when Parsanol::Atoms::Str
-                     serialize_str(atom)
-                   when Parsanol::Atoms::Re
-                     serialize_re(atom)
-                   when Parsanol::Atoms::Sequence
-                     serialize_sequence(atom)
-                   when Parsanol::Atoms::Alternative
-                     serialize_alternative(atom)
-                   when Parsanol::Atoms::Repetition
-                     serialize_repetition(atom)
-                   when Parsanol::Atoms::Named
-                     serialize_named(atom)
-                   when Parsanol::Atoms::Lookahead
-                     serialize_lookahead(atom)
-                   when Parsanol::Atoms::Capture
-                     serialize_capture(atom)
-                   when Parsanol::Atoms::Scope
-                     serialize_scope(atom)
-                   when Parsanol::Atoms::StateSet
-                     serialize_state_set(atom)
-                   when Parsanol::Atoms::StateMatch
-                     serialize_state_match(atom)
-                   when Parsanol::Atoms::StateSwitch
-                     serialize_state_switch(atom)
-                   when Parsanol::Atoms::CustomRef
-                     serialize_custom_ref(atom)
-                   when Parsanol::Atoms::Dynamic
-                     serialize_dynamic(atom)
-                   when Parsanol::Atoms::TriviaCapture
-                     # parsanol-ruby#152: the capture wrapper carries
-                     # its marker table so the native engine records
-                     # comment-shaped units into the pending channel
-                     # and attaches them to the next Named capture
-                     # under `comments:`. A distinct variant keeps the
-                     # declared gate: engines predating it reject
-                     # capture-carrying artifacts loudly.
-                     serialize_trivia_capture(atom)
-                   when Parsanol::Atoms::Trivia
-                     # Wire-distinct from Ignore (rs#172): the Rust
-                     # engine suppresses trivia-position diagnostics by
-                     # atom kind. Engines predating the Trivia tag
-                     # reject skip-carrying artifacts loudly (unknown
-                     # variant), which is the declared gate.
-                     serialize_trivia(atom)
-                   when Parsanol::Atoms::Constant
-                     # rs#137 follow-up: coradoc-markdown's Output
-                     # atoms — empty match yielding a wire constant.
-                     { "Constant" => { "value" => serialize_constant_value(atom.value) } }
-                   when Parsanol::Atoms::Lookbehind
-                     # rs#137/#163: the behind-window test — a fixed
-                     # literal window or an end-anchored regex (the
-                     # CommonMark flanking form).
-                     look = if atom.regex?
-                              { "Regex" => { "source" => atom.regex_source } }
-                            else
-                              { "Literal" => { "count" => atom.count,
-                                               "pattern" => atom.pattern } }
-                            end
-                     { "Lookbehind" => { "look" => look,
-                                         "positive" => atom.positive } }
-                   when Parsanol::Atoms::Ignored
-                     serialize_ignored(atom)
-                   else
-                     # Fallback for unknown atom types
-                     serialize_unknown(atom)
-                   end
+      # Reserve the id before the children, as serialize_entity does, so a
+      # recursive path back to this atom reuses it instead of emitting a
+      # second copy.
+      if @preserve_identity
+        atom_id = @atoms.size
+        @atom_cache[cache_key] = atom_id
+        @retained_atoms << atom
+        @atoms << nil
+        @atoms[atom_id] = serialize_body(atom)
+        return atom_id
+      end
+
+      serialized = serialize_body(atom)
 
       # Now reserve an atom_id and cache
       atom_id = @atoms.size
@@ -130,6 +83,77 @@ module Parsanol
       atom_id
     end
 
+    def serialize_body(atom)
+      # Serialize based on atom type first (recursively)
+      case atom
+      when Parsanol::Atoms::Str
+        serialize_str(atom)
+      when Parsanol::Atoms::Re
+        serialize_re(atom)
+      when Parsanol::Atoms::Sequence
+        serialize_sequence(atom)
+      when Parsanol::Atoms::Alternative
+        serialize_alternative(atom)
+      when Parsanol::Atoms::Repetition
+        serialize_repetition(atom)
+      when Parsanol::Atoms::Named
+        serialize_named(atom)
+      when Parsanol::Atoms::Lookahead
+        serialize_lookahead(atom)
+      when Parsanol::Atoms::Capture
+        serialize_capture(atom)
+      when Parsanol::Atoms::Scope
+        serialize_scope(atom)
+      when Parsanol::Atoms::StateSet
+        serialize_state_set(atom)
+      when Parsanol::Atoms::StateMatch
+        serialize_state_match(atom)
+      when Parsanol::Atoms::StateSwitch
+        serialize_state_switch(atom)
+      when Parsanol::Atoms::CustomRef
+        serialize_custom_ref(atom)
+      when Parsanol::Atoms::Dynamic
+        serialize_dynamic(atom)
+      when Parsanol::Atoms::TriviaCapture
+        # parsanol-ruby#152: the capture wrapper carries
+        # its marker table so the native engine records
+        # comment-shaped units into the pending channel
+        # and attaches them to the next Named capture
+        # under `comments:`. A distinct variant keeps the
+        # declared gate: engines predating it reject
+        # capture-carrying artifacts loudly.
+        serialize_trivia_capture(atom)
+      when Parsanol::Atoms::Trivia
+        # Wire-distinct from Ignore (rs#172): the Rust
+        # engine suppresses trivia-position diagnostics by
+        # atom kind. Engines predating the Trivia tag
+        # reject skip-carrying artifacts loudly (unknown
+        # variant), which is the declared gate.
+        serialize_trivia(atom)
+      when Parsanol::Atoms::Constant
+        # rs#137 follow-up: coradoc-markdown's Output
+        # atoms — empty match yielding a wire constant.
+        { "Constant" => { "value" => serialize_constant_value(atom.value) } }
+      when Parsanol::Atoms::Lookbehind
+        # rs#137/#163: the behind-window test — a fixed
+        # literal window or an end-anchored regex (the
+        # CommonMark flanking form).
+        look = if atom.regex?
+                 { "Regex" => { "source" => atom.regex_source } }
+               else
+                 { "Literal" => { "count" => atom.count,
+                                  "pattern" => atom.pattern } }
+               end
+        { "Lookbehind" => { "look" => look,
+                            "positive" => atom.positive } }
+      when Parsanol::Atoms::Ignored
+        serialize_ignored(atom)
+      else
+        # Fallback for unknown atom types
+        serialize_unknown(atom)
+      end
+    end
+
     def serialize_str(atom)
       {
         "Str" => {

data/lib/parsanol/native.rb

@@ -402,12 +402,22 @@ module Parsanol
         BatchDecoder.decode_and_flatten(raw, input, Parsanol::Slice)
       end
 
+      # The native engine's recursion-limit abort (ParseError::
+      # RecursionLimitExceeded in parsanol-rs). It carries no position
+      # marker: it is a resource limit, not a refusal of the input.
+      NATIVE_RECURSION_LIMIT = /\A(?:Recursion limit exceeded\b|Maximum recursion depth \(\d+\) exceeded)/
+
       def raise_compatible_parse_error(error, input)
         message = error.message
         position = message[NATIVE_POS_MARKER, 1].to_i
         cause = Parsanol::Cause.new(message.sub(NATIVE_POS_MARKER, ""),
                                     Parsanol::Source.new(input), position)
-        raise Parsanol::ParseFailed.new(cause.to_s, cause), cause: nil
+        failure = if !message.match?(NATIVE_POS_MARKER) && message.match?(NATIVE_RECURSION_LIMIT)
+                    Parsanol::RecursionLimitExceeded
+                  else
+                    Parsanol::ParseFailed
+                  end
+        raise failure.new(cause.to_s, cause), cause: nil
       end
 
       # Reference-walker path (TODO.sota/8 B1): the plain recursive

data/lib/parsanol/parg/cli.rb

@@ -22,7 +22,12 @@ module Parsanol
                                             compile to an artifact envelope;
                                             --bindings also writes one
                                             checksummed per-target binding
-                                            artifact beside it (#432)
+                                            artifact beside it (#432);
+                                            --model-bindings FILE embeds a
+                                            rule -> model sidecar (JSON/YAML)
+                                            in the artifact
+          bindings <artifact.json>          dump the embedded rule -> model
+                                            binding table as JSON (coradoc#307)
           test    <file.parg|artifact.json>   run the grammar's test section
           parse   <file> [--entry E] INPUT  parse one input; prints the tree
                                             and the bound captures
@@ -75,6 +80,7 @@ module Parsanol
         when "lint" then lint
         when "export" then export_grammar
         when "diff" then diff_artifacts
+        when "bindings" then dump_bindings
         when "lsp" then Lsp.new.run && 0
         else
           warn USAGE
@@ -145,6 +151,9 @@ module Parsanol
         source = @argv.shift
         out = flag_value("-o") || default_artifact_name(source)
         envelope = compile_source(source).envelope
+        if (sidecar = flag_value("--model-bindings"))
+          envelope = ModelBindings.embed(envelope, ModelBindings.load(sidecar))
+        end
         # Seal: the exact text written is the exact text the byte-level
         # checksum covers (Compiler.seal_json includes the trailing
         # newline).
@@ -162,6 +171,18 @@ module Parsanol
         0
       end
 
+      # `parg bindings ARTIFACT`: the embedded rule -> model table as JSON.
+      def dump_bindings
+        path = @argv.shift
+        unless path
+          warn "usage: parsanol parg bindings ARTIFACT.json"
+          return 2
+        end
+        envelope = ModelBindings.read_envelope(path)
+        puts ModelBindings.dump(envelope)
+        0
+      end
+
       # Every --bindings flag value, `all` expanded to the target set.
       # Empty when the flag is absent (compile emits no binding artifacts).
       def bindings_targets

data/lib/parsanol/parg/compiler.rb

@@ -61,7 +61,8 @@ module Parsanol
       # unicode_tables — is byte-stable when the grammar's behavior is
       # unchanged. Mirrors the cross-engine parity view.
       SEMANTICS_EXCLUDED = %w[checksum byte_checksum compiler_version
-                              unicode_tables semantics_hash validated].freeze
+                              unicode_tables semantics_hash validated
+                              model_bindings].freeze
 
       def self.semantics_hash(envelope)
         payload = envelope.except(*SEMANTICS_EXCLUDED)

data/lib/parsanol/parg/model_bindings.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Parsanol
+  module PARG
+    # The rule -> model binding table embedded in an artifact (coradoc#307).
+    #
+    # A sidecar (JSON or YAML) declares, per rule, which model a raw-tree
+    # node inflates to:
+    #
+    #   version: 1
+    #   rules:
+    #     thematic_break:
+    #       keys: [hr]                  # exact capture-key set of the node
+    #       model: HorizontalRule
+    #       captures: {}                # attribute => scalar capture key
+    #       children: {}                # attribute => nested-node capture key
+    #       defaults: { style: "---" }  # attributes fixed by the rule
+    #
+    # `parg compile --model-bindings FILE` embeds it under the envelope's
+    # additive "model_bindings" key; artifacts compiled without a sidecar
+    # carry no such key and are byte-identical to before. The table is not
+    # parse semantics, so semantics_hash ignores it; the checksum covers it.
+    module ModelBindings
+      KEY = "model_bindings"
+      VERSION = 1
+      RULE_FIELDS = %w[keys model captures children defaults].freeze
+
+      module_function
+
+      # @param path [String] a .json / .yml / .yaml sidecar
+      # @return [Hash] the validated, string-keyed table
+      def load(path)
+        text = File.read(path, encoding: Encoding::UTF_8)
+        raw = File.extname(path).match?(/\.ya?ml\z/i) ? YAML.safe_load(text) : JSON.parse(text)
+        normalize(raw)
+      rescue JSON::ParserError, Psych::SyntaxError => e
+        raise ArtifactError, "model bindings #{path}: #{e.message}"
+      end
+
+      # @return [Hash] the table with every rule filled to the full shape
+      def normalize(raw)
+        raise ArtifactError, "model bindings: expected a mapping" unless raw.is_a?(Hash)
+
+        table = stringify(raw)
+        unless table["version"] == VERSION
+          raise ArtifactError, "model bindings: unsupported version #{table['version'].inspect} (want #{VERSION})"
+        end
+
+        rules = table["rules"]
+        raise ArtifactError, "model bindings: `rules` must be a mapping" unless rules.is_a?(Hash)
+
+        { "version" => VERSION, "rules" => rules.to_h { |name, rule| [name, normalize_rule(name, rule)] } }
+      end
+
+      def normalize_rule(name, rule)
+        raise ArtifactError, "model bindings: rule #{name.inspect} must be a mapping" unless rule.is_a?(Hash)
+
+        unknown = rule.keys - RULE_FIELDS
+        raise ArtifactError, "model bindings: rule #{name.inspect} has unknown field #{unknown.first.inspect}" unless unknown.empty?
+        unless rule["model"].is_a?(String) && !rule["model"].empty?
+          raise ArtifactError, "model bindings: rule #{name.inspect} needs a `model`"
+        end
+        unless rule["keys"].is_a?(Array) && !rule["keys"].empty?
+          raise ArtifactError, "model bindings: rule #{name.inspect} needs non-empty `keys`"
+        end
+
+        {
+          "keys" => rule["keys"].map(&:to_s),
+          "model" => rule["model"],
+          "captures" => hash_field(name, rule, "captures"),
+          "children" => hash_field(name, rule, "children"),
+          "defaults" => hash_field(name, rule, "defaults"),
+        }
+      end
+
+      def hash_field(name, rule, field)
+        value = rule.fetch(field, {})
+        raise ArtifactError, "model bindings: rule #{name.inspect} `#{field}` must be a mapping" unless value.is_a?(Hash)
+
+        value
+      end
+
+      def stringify(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.to_s, stringify(item)] }
+        when Array then value.map { |item| stringify(item) }
+        else value
+        end
+      end
+
+      # Embed a table in an envelope and re-seal the canonical checksum.
+      def embed(envelope, table)
+        sealed = envelope.merge(KEY => table)
+        sealed["checksum"] = Compiler.checksum(sealed)
+        sealed
+      end
+
+      # Read an artifact file for the dump: JSON plus checksum verification
+      # only, so no grammar source and no custom-atom class is needed.
+      def read_envelope(path)
+        envelope = JSON.parse(File.read(path, encoding: Encoding::UTF_8))
+        unless envelope.is_a?(Hash) && envelope["checksum"] == Compiler.checksum(envelope)
+          raise ArtifactError, "#{path}: artifact checksum mismatch"
+        end
+
+        envelope
+      rescue JSON::ParserError => e
+        raise ArtifactError, "#{path}: #{e.message}"
+      end
+
+      # @return [Hash, nil] the embedded table, nil for an artifact without one
+      def from(envelope)
+        envelope[KEY]
+      end
+
+      # The machine-readable dump: rule -> model/keys/captures/children/defaults.
+      def dump(envelope)
+        table = from(envelope) || { "version" => VERSION, "rules" => {} }
+        JSON.pretty_generate(table)
+      end
+    end
+  end
+end

data/lib/parsanol/parg.rb

@@ -26,6 +26,7 @@ module Parsanol
     autoload :Compiler, "parsanol/parg/compiler"
     autoload :Artifact, "parsanol/parg/artifact"
     autoload :Bindings, "parsanol/parg/bindings"
+    autoload :ModelBindings, "parsanol/parg/model_bindings"
     autoload :Render, "parsanol/parg/render"
     autoload :Derive, "parsanol/parg/derive"
     autoload :SelfHost, "parsanol/parg/selfhost"

data/lib/parsanol/version.rb

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

data/lib/parsanol.rb

@@ -66,6 +66,13 @@ module Parsanol
     attr_reader :parse_failure_cause
   end
 
+  # Raised when the native engine stops because the input nests deeper
+  # than its recursion limit. A subclass of ParseFailed with the same
+  # message and cause, so existing rescues behave as before; callers that
+  # want to retry on another engine can rescue this class instead of
+  # matching the message.
+  class RecursionLimitExceeded < ParseFailed; end
+
   # Class methods added to classes that include Parsanol.
   module ClassMethods
     # Enable automatic rule optimization for all rules in this parser.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parsanol
 version: !ruby/object:Gem::Version
-  version: 1.3.132
+  version: 1.3.134
 platform: aarch64-linux
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-11-03 00:00:00.000000000 Z
+date: 2026-11-05 00:00:00.000000000 Z
 dependencies: []
 description: A small Ruby library for constructing parsers in the PEG (Parsing Expression
   Grammar) fashion. Parsanol provides Parslet-compatible API with additional features
@@ -120,6 +120,7 @@ files:
 - lib/parsanol/parg/lints.rb
 - lib/parsanol/parg/lsp.rb
 - lib/parsanol/parg/lutaml.rb
+- lib/parsanol/parg/model_bindings.rb
 - lib/parsanol/parg/node.rb
 - lib/parsanol/parg/parser.rb
 - lib/parsanol/parg/preprocess.rb