parsanol 1.3.64 → 1.3.66

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d3b9a74be500e1e1874c246d72614966e39ee7766731726a23d77e7b88b8f33
-  data.tar.gz: 79d0492db122146e4bfca2ce17de4017b02d94385f8b9f6db540e7ea69ee6d02
+  metadata.gz: da894739a391336f9b9f65a65abc87da1fe51b3f3268c0c2334638e53f5adb8f
+  data.tar.gz: 6777a602a63a37e599fdc1ed9c38f82eb8b01a30a12a23c24bbed7518f37e5cf
 SHA512:
-  metadata.gz: e7cf8b9f912837052ab62bcf35332de5b4715f0a9f43e8b9ffc8e5cb3cf5ce16a0d830c0841ad326855cad5eb8c8de8e3e9e28cdbf264f441fd40db71f78bef5
-  data.tar.gz: 00755e792eb152ced1b9d3e38f783d1f9637cc13add763b609e8e4edaaff1dd4dafa426bf162e11e956bad14d86ad75b6eb07bd42d0015f32f48e043e72e594c
+  metadata.gz: 0fad1aa5febfc712a767578c4ca4d9c9c6cf3def48ed7f6fe97a66a95e45d0e628a4285660eb14b40e6d0b72bbd6422868b85ea901d84318382f23aa5744378b
+  data.tar.gz: 6ab9b3b4461592a3a5e91accd57d0341c59c7f878985b01fd89b73fe91c8abd71eacedd6246d0c79a2fd57547607415c0932e73cfb2c2e61b3adb2af5165a9a6

data/lib/parsanol/atoms/state.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module Atoms
+    # PARG runtime-state atoms (parsanol-ruby#129): per-parse mutable
+    # slots living in the parse context's capture store, so capture
+    # rollback, scope discipline and the dispatch semantics are the
+    # proven dynamic-callback ones. All four are pure data — they
+    # serialize as structured tags and rebuild identically in any
+    # runtime that implements the state machine.
+    class StateBase < Base
+      def cached?
+        false
+      end
+
+      private
+
+      # Slots and captures may live in a parent scope frame (an earlier
+      # element's frame); Scope#[] only reads the active one.
+      def lookup(context, key)
+        context.captures.fetch(key)
+      rescue Parsanol::Scope::UndefinedVariable
+        nil
+      end
+
+      def mark_unsafe(context)
+        # The atom reads mutable parse state (captures), so no enclosing
+        # composite result may be memoized — replaying it would skip the
+        # re-evaluation (same contract as Atoms::Dynamic).
+        context.mark_cache_unsafe!
+      end
+    end
+
+    # Writes a state slot. Two forms: a literal value (always succeeds,
+    # consumes nothing) or an inline expression — the expression matches
+    # at the position and the slot stores its consumed text (the
+    # block_open pattern: match the delimiter, remember it).
+    class StateSet < StateBase
+      def initialize(slot, value: nil, atom: nil)
+        super()
+        @slot = slot
+        @value = value
+        @atom = atom
+      end
+
+      attr_reader :slot, :value, :atom
+
+      def try(source, context, _consume_all)
+        mark_unsafe(context)
+        if @atom.nil?
+          context.captures[@slot] = @value
+          return [true, ""]
+        end
+
+        start = source.bytepos
+        outcome = @atom.apply(source, context, false)
+        return outcome unless outcome.first
+
+        span = source.input.byteslice(start, source.bytepos - start)
+        context.captures[@slot] = span
+        outcome
+      end
+
+      def to_s_inner(_prec)
+        "set #{@slot}=#{@value || '…'}"
+      end
+    end
+
+    # Matches the state slot's current value verbatim at the position —
+    # the block-delimiter comparison ("exactly what was captured above").
+    class StateMatch < StateBase
+      def initialize(slot)
+        super()
+        @slot = slot
+      end
+
+      attr_reader :slot
+
+      def try(source, context, _consume_all)
+        mark_unsafe(context)
+        expected = lookup(context, @slot)
+        return [false, nil] if expected.nil?
+
+        actual = source.peek(expected.length)
+        return [false, nil] if actual != expected
+
+        source.bytepos += expected.length
+        [true, actual]
+      end
+
+      def to_s_inner(_prec)
+        "state(#{@slot})"
+      end
+    end
+
+    # Dispatches on the slot's current value to a rule reference. The
+    # resolver maps a rule name to its atom lazily (rules may still be
+    # under construction when this atom is built). A nil arm fails the
+    # atom — the native dynamic-callback parity.
+    class StateSwitch < StateBase
+      def initialize(slot, arms, default, resolver)
+        super()
+        @slot = slot
+        @arms = arms
+        @default = default
+        @resolver = resolver
+      end
+
+      attr_reader :slot, :arms, :default
+
+      def try(source, context, consume_all)
+        mark_unsafe(context)
+        current = lookup(context, @slot)
+        rule_name = @arms[current] || @default
+        return [false, nil] if rule_name.nil?
+
+        @resolver.call(rule_name).apply(source, context, consume_all)
+      end
+
+      def to_s_inner(_prec)
+        "switch(#{@slot})"
+      end
+    end
+
+    # A foreign atom: a class resolved from the artifact's customs
+    # binding at compile time. The instance runs as-is on the Ruby
+    # engine; the serialized tag carries the binding so any runtime can
+    # decide support loudly.
+    class CustomRef < Base
+      def initialize(name, klass)
+        super()
+        @name = name
+        @atom = klass.new
+      end
+
+      attr_reader :name
+
+      def cached?
+        false
+      end
+
+      def try(source, context, consume_all)
+        @atom.try(source, context, consume_all)
+      end
+
+      def to_s_inner(_prec)
+        "custom(#{@name})"
+      end
+    end
+  end
+end

data/lib/parsanol/atoms.rb

@@ -38,6 +38,7 @@ module Parsanol
     require "parsanol/atoms/entity"
     require "parsanol/atoms/capture"
     require "parsanol/atoms/dynamic"
+    require "parsanol/atoms/state"
     require "parsanol/atoms/scope"
     require "parsanol/atoms/infix"
     # Load visitor pattern (must be after all atom classes)

data/lib/parsanol/native/serializer.rb

@@ -68,6 +68,14 @@ module Parsanol
                      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::Ignored
@@ -219,6 +227,34 @@ module Parsanol
       }
     end
 
+    def serialize_state_set(atom)
+      payload = { "slot" => atom.slot.to_s }
+      if atom.atom
+        payload["expr"] = serialize_atom(atom.atom)
+      else
+        payload["value"] = atom.value
+      end
+      { "StateSet" => payload }
+    end
+
+    def serialize_state_match(atom)
+      { "StateMatch" => { "slot" => atom.slot.to_s } }
+    end
+
+    def serialize_state_switch(atom)
+      {
+        "StateSwitch" => {
+          "slot" => atom.slot.to_s,
+          "arms" => atom.arms.transform_keys(&:to_s),
+          "default" => atom.default,
+        },
+      }
+    end
+
+    def serialize_custom_ref(atom)
+      { "CustomRef" => { "name" => atom.name } }
+    end
+
     def serialize_dynamic(atom)
       # Dynamic evaluates a Ruby block at parse time.
       # Register the block and get a callback ID for FFI.

data/lib/parsanol/parg/artifact.rb

@@ -57,10 +57,15 @@ module Parsanol
       # path is a straight register-and-run — no Ruby recompilation. The
       # Ruby atom runtime (mode: :ruby) remains available explicitly, and
       # serves as the fallback on platforms without the extension.
+      #
+      # Dynamic artifacts (runtime state, custom atoms — #129) route to
+      # the Ruby engine: the envelope carries the PARG source precisely
+      # so a Ruby runtime can rebuild the live atom tree; the closures
+      # are not portable JSON.
       def parse(entry_name, input, mode: :native)
         case mode
         when :native
-          if Native.available?
+          if !envelope["dynamic"] && Native.available?
             return Native.parse(JSON.generate(entry(entry_name).fetch("grammar")), input)
           end
 

data/lib/parsanol/parg/compiler.rb

@@ -50,6 +50,7 @@ module Parsanol
         @atom_cache = {}
         @first_cache = {}.compare_by_identity
         @ref_stack = []
+        @dynamic = false
         @tables = {}
         @warnings = []
       end
@@ -67,6 +68,16 @@ module Parsanol
         Result.new(@atom_cache, @warnings, envelope)
       end
 
+      def resolve_custom(name)
+        class_name = @document.customs.fetch(name)
+        klass = Object.const_get(class_name)
+        Atoms::CustomRef.new(name, klass)
+      rescue NameError
+        raise CompileError,
+              "custom atom #{name.inspect} cannot resolve #{class_name.inspect} " \
+              "(bind the class before compiling, or fix the custom declaration)"
+      end
+
       def atom_for(name)
         @atom_cache[name] ||= build_atom(fetch_rule(name))
       end
@@ -157,6 +168,13 @@ module Parsanol
       end
 
       def fetch_rule(name)
+        # Customs are opaque terminals for the analysis passes (first
+        # sets, left-recursion): a literal stand-in keeps them
+        # non-nullable with a singleton first set.
+        if !@document.rules.key?(name) && @document.customs.key?(name)
+          return Node.new(:lit, "\u0001", false)
+        end
+
         @document.rules[name] || raise(CompileError, "unknown rule #{name.inspect}")
       end
 
@@ -194,7 +212,31 @@ module Parsanol
           end
 
           Atoms::Named.new(build_atom(node.b), node.a.to_sym)
-        when :ref then Atoms::Entity.new(node.a) { atom_for(node.a) }
+        when :set
+          @dynamic = true
+          slot = node.a.to_sym
+          value = node.b
+          if value.is_a?(String)
+            Atoms::StateSet.new(slot, value: value)
+          else
+            Atoms::StateSet.new(slot, atom: build_atom(value))
+          end
+        when :state_match
+          @dynamic = true
+          Atoms::StateMatch.new(node.a.to_sym)
+        when :switch
+          @dynamic = true
+          slot = node.a.to_sym
+          arms = node.b.to_h { |match, rule| [match, rule] }
+          default = arms.delete(:default)
+          Atoms::StateSwitch.new(slot, arms, default, method(:atom_for))
+        when :ref
+          if @document.customs.key?(node.a)
+            @dynamic = true
+            resolve_custom(node.a)
+          else
+            Atoms::Entity.new(node.a) { atom_for(node.a) }
+          end
         when :table
           values = table_column(node.a, node.b)
           Atoms::Alternative.new(*values.map { |value| Atoms::Str.new(value) })
@@ -430,6 +472,9 @@ module Parsanol
           "docs" => @document.docs,
           "source" => @document.source,
         }
+        envelope["customs"] = @document.customs unless @document.customs.empty?
+        envelope["states"] = @document.states unless @document.states.empty?
+        envelope["dynamic"] = true if @dynamic
         envelope["checksum"] = Compiler.checksum(envelope)
         envelope
       end

data/lib/parsanol/parg/document.rb

@@ -10,7 +10,8 @@ module Parsanol
       Test = Struct.new(:entry, :kind, :input, :expect)
 
       attr_accessor :grammar_name, :version, :source, :uses
-      attr_reader :rules, :bindings, :preprocess, :entries, :docs, :tests, :render, :derive
+      attr_reader :rules, :bindings, :preprocess, :entries, :docs, :tests, :render, :derive,
+                  :customs, :states
       # Entries authored in this file (pre-import); nil-entry tests resolve
       # against these first.
       attr_accessor :own_entries
@@ -29,6 +30,8 @@ module Parsanol
         @tests = []
         @uses = []
         @own_entries = nil
+        @customs = {}
+        @states = {}
       end
 
       def validate!

data/lib/parsanol/parg/lutaml.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Standalone requires of this file bypass the parg autoload registry —
+# declare the namespace dependency so Artifact resolves.
+require "parsanol/parg"
+
 module Parsanol
   module PARG
     # lutaml-model integration: register a PARG artifact as a lutaml-model

data/lib/parsanol/parg/parser.rb

@@ -18,8 +18,9 @@ module Parsanol
 
       IN_BLOCK_SECTIONS = %w[entry bindings preprocess test].freeze
 
+      STATE_KEYWORDS = %w[custom state].freeze
       KEYWORDS = %w[grammar as alt from_table column bindings render derive
-                    preprocess entry table_lookup].freeze
+                    preprocess entry table_lookup custom state set switch].freeze
 
       def initialize(text)
         @tokens = Lexer.new(text).tokens
@@ -160,6 +161,19 @@ module Parsanol
             skip_newlines
             next
           end
+          if peek&.type == :ident && STATE_KEYWORDS.include?(peek.value)
+            keyword = advance.value
+            slot = ident.value
+            if keyword == "custom"
+              punct("=")
+              document.customs[slot] = unquote(expect(:str).value)
+            else
+              punct(":")
+              document.states[slot] = ident.value
+            end
+            skip_newlines
+            next
+          end
           name = rule_name
           document.docs[name] = docs.join("\n") unless docs.empty?
           punct("=")
@@ -274,6 +288,43 @@ module Parsanol
 
       def parse_ident(token)
         case token.value
+        when "state"
+          Node.new(:state_match, ident.value)
+        when "set"
+          slot = ident.value
+          punct("=")
+          # A string writes the literal; a bare name copies the matched
+          # text of a capture (the block-delimiter pattern: set the slot
+          # from what the opening delimiter matched).
+          value = if peek&.type == :str
+                    unquote(expect(:str).value)
+                  else
+                    punct("(")
+                    inner = parse_choice
+                    punct(")")
+                    inner
+                  end
+          Node.new(:set, slot, value)
+        when "switch"
+          slot = ident.value
+          punct("{")
+          skip_newlines
+          arms = []
+          until peek&.type == :punct && peek.value == "}"
+            match = if peek&.type == :ident && peek.value == "_"
+                      advance
+                      :default
+                    else
+                      unquote(expect(:str).value)
+                    end
+            arrow = advance
+            raise ParseError, "expected \"->\", got #{arrow&.type}:#{arrow&.value}" unless arrow&.value == "->"
+
+            arms << [match, ident.value]
+            skip_newlines
+          end
+          punct("}")
+          Node.new(:switch, slot, arms)
         when "alt"
           ident("from_table")
           table = unquote(expect(:str).value)

data/lib/parsanol/parser.rb

@@ -238,6 +238,11 @@ module Parsanol
     # The degradation warning prints once per reason per process — not
     # per parser instance and not per parse.
     def native_expressible?
+      # The ext attaches its methods lazily (available? triggers the load);
+      # without this guard a first-touch call NoMethodErrors inside the
+      # serializer (Dynamic.register -> Native.register_callback).
+      return false unless Parsanol::Native.available?
+
       Parsanol::Native::Parser.grammar_handle(root)
       true
     rescue Parsanol::Native::UnsupportedGrammar => e

data/lib/parsanol/scope.rb

@@ -84,6 +84,14 @@ module Parsanol
       @active_frame.fetch(key)
     end
 
+    # Chain-aware read: the active frame, then its parents ([] is
+    # deliberately active-frame-only for capture-scope discipline; state
+    # atoms read across frames — a slot may have been written inside an
+    # earlier sibling element's frame).
+    def fetch(key)
+      @active_frame.fetch(key)
+    end
+
     # Chain-aware membership test, mirroring Parslet's captures.key?.
     # Checks the current frame and all parents without raising.
     #

data/lib/parsanol/version.rb

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

data/lib/parsanol/vm.rb

@@ -175,8 +175,10 @@ module Parsanol
         compiler.to_program
       end
 
+      # Returns violation descriptions for this atom's ordered-choice
+      # branches (empty-matchable non-last branches shadow later ones).
       def validate_choice_branches(atom)
-        atom.alternatives.each_with_index do |branch, idx|
+        atom.alternatives.each_with_index.filter_map do |branch, idx|
           walk_branch = branch
           next if idx == atom.alternatives.size - 1
 
@@ -194,14 +196,13 @@ module Parsanol
           next if walk_branch.nil?
           next unless Compiler.new.nullable?(walk_branch)
 
-          raise Parsanol::GrammarError,
-                "wrong grammar: alternative branch #{idx} " \
-                "(#{branch.inspect}) can match empty input and is not " \
-                "the last branch — ordered choice commits to its empty " \
-                "match, so #{atom.alternatives.size - idx - 1} later " \
-                "branch(es) can never match at positions where it " \
-                "matches empty. Reorder branches so empty-matchable " \
-                "ones come last, or make the branch non-empty."
+          "alternative branch #{idx} (#{branch.inspect}) can match " \
+            "empty input and is not the last branch — ordered choice " \
+            "commits to its empty match, so " \
+            "#{atom.alternatives.size - idx - 1} later branch(es) can " \
+            "never match at positions where it matches empty. Reorder " \
+            "branches so empty-matchable ones come last, or make the " \
+            "branch non-empty."
         end
       end
 
@@ -211,6 +212,7 @@ module Parsanol
       # the grammar is wrong, and inputs it would mis-parse fail with a
       # baffling cause. Raise before any input is seen.
       def validate_alternatives(root)
+        violations = []
         visited = {}.compare_by_identity
         walk = lambda do |atom, depth|
           next if atom.nil? || depth > 20
@@ -219,26 +221,26 @@ module Parsanol
           visited[atom] = true
           case atom
           when Parsanol::Atoms::Alternative
-            validate_choice_branches(atom)
+            violations.concat(validate_choice_branches(atom))
             atom.alternatives.each { |c| walk.call(c, depth + 1) }
           when Parsanol::Atoms::Sequence
             atom.parslets.each { |c| walk.call(c, depth + 1) }
           when Parsanol::Atoms::Repetition, Parsanol::Atoms::Named
             walk.call(atom.parslet, depth + 1)
-          when Parsanol::Atoms::Lookahead
-            walk.call(atom.bound_parslet, depth + 1)
-          when Parsanol::Atoms::Ignored
-            walk.call(atom.wrapped_atom, depth + 1)
           when Parsanol::Atoms::Entity
+            # Rule bodies hide behind the entity wrapper; without this
+            # descent the lint passes DSL grammars that fail the same
+            # grammar compiled from PARG (where bodies are inlined).
+            # Entities that cannot resolve outside a parse are skipped.
             begin
               walk.call(atom.parslet, depth + 1)
-            rescue Parsanol::GrammarError
-              raise
             rescue StandardError
-              # Lazily resolved / recursive entity that cannot resolve
-              # outside a parse: skip this branch of the walk.
               nil
             end
+          when Parsanol::Atoms::Lookahead
+            walk.call(atom.bound_parslet, depth + 1)
+          when Parsanol::Atoms::Ignored
+            walk.call(atom.wrapped_atom, depth + 1)
           when Parsanol::Atoms::Scope
             begin
               walk.call(atom.block.call, depth + 1)
@@ -248,6 +250,11 @@ module Parsanol
           end
         end
         walk.call(root, 0)
+        return if violations.empty?
+
+        raise Parsanol::GrammarError,
+              "wrong grammar: #{violations.size} shadowed-alternative " \
+              "violation(s):\n  - #{violations.join('\n  - ')}"
       end
 
       # Executes a compiled program. Returns [true, value] on success;

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parsanol
 version: !ruby/object:Gem::Version
-  version: 1.3.64
+  version: 1.3.66
 platform: ruby
 authors:
 - Ribose Inc.
@@ -70,6 +70,7 @@ files:
 - lib/parsanol/atoms/repetition.rb
 - lib/parsanol/atoms/scope.rb
 - lib/parsanol/atoms/sequence.rb
+- lib/parsanol/atoms/state.rb
 - lib/parsanol/atoms/str.rb
 - lib/parsanol/atoms/visitor.rb
 - lib/parsanol/buffer.rb