ctx_parser 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d926ccda7788e5126e7dbd90230a48073eb13d275badfdb13c4f502f06407b8f
-  data.tar.gz: 1fa99e3f02360e1eb9b77446e17156ca250214473a377c7d3e514bb71a32c1d9
+  metadata.gz: dfdec0a6366bcb4f65cca5025dacb968ec838de632dbed9b02424b1eadfe7ba9
+  data.tar.gz: c7b1eadc4fc4f6baa24b0e9c2c94e40080097e60da3ba25a6b4693c5d4735a42
 SHA512:
-  metadata.gz: 93a927e92dfdb97cab57643787c7f5380fb11bf6a0bb5fd134fb89b03da0ab4c31c1b3d3b3c29f395b4b9d5884578800c3af0e94181df509441751a2f7c43dba
-  data.tar.gz: 2b614f708cefbd0f9da209f9d2a9ea3bdb908ff87998e63dd35ecd7de32e0ea3d8f7259d0bef0538b478cbb0d998fe48f7a80ceaaf2546a8b0c306ede1e63747
+  metadata.gz: aa1e066001a118d610be8fd777844ddd53dab4627ab976eefaf076218d7ec77d62d15011ae203804cb8c3117f03cee079aa83315cd909bb2eaae192817201d4f
+  data.tar.gz: 0e1f197af6d134e9fa86989b62b4e82e6b4cecc103336a213128b211f1c35060e337903c04b91cd8f365729ce602a8f18acdba5cb1d7409efef01eb2ef07ca33

data/CHANGELOG.md

@@ -4,6 +4,12 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 0.5.1 (2026-10-30)
+
+- Add `Document#build_blocks` for native syntax trees and `Document::Flat` for independent command lines, sharing initialization, finalization and root validation.
+- Validate Block children by source ownership, containment and order; indentation remains the responsibility of the default tree builder.
+- Add cached `Cursor#block(index)` source ranges whose state stays live across rewind and reset.
+
 ## 0.5.0 (2026-10-30)
 
 - Add Cursor#resolved? with a lazy, invalidated prefix index; Block/Capture completeness remains live after state changes and reset.

data/README-zh.md

@@ -94,6 +94,8 @@ result.records.each { |row| puts "#{row[:name]}: #{row[:state]}" }
 
 `Records` 持有自己的筛选数组，行对象仍属于调用方；使用期间应保持行不变，需要快照时传入 `Immutable.copy(rows)`。`Immutable.copy` 即使遇到冻结容器也重建普通容器，单次复制中保留共享引用并拒绝循环；不扫描方法表，也不引入应用级全局缓存。字符串经 `String.new` 和 Ruby 去重后冻结，保留编码与字节。不同次复制不保证容器对象身份相同；`Immutable.copy_string` 提供相同的文本边界并省去容器遍历表。整数转换仅在 `min` 允许负数或为 `nil` 时接受负号，默认仍只接受非负数。
 
+`Document` 默认按缩进建树；原生语法可以覆盖受保护的 `build_blocks`，返回同一游标内按来源排序、互不重叠的根 Block，随后仍执行 `finish`。子块必须处于父范围内并保持顺序，不要求更深缩进。`Document::Flat` 将命令行作为独立来源块；`cursor.block(index)` 复用单行范围，rewind/reset 保留其身份，完整性始终读取当前游标状态。这些 API 由配套 0.5.1 候选提供，厂商语法由消费模块拥有。
+
 ## 开发与测试
 
 共享类按实际职责命名，平台信息放在命名空间中。直接对应设备命令的解析器保留文件名和类名。

data/README.md

@@ -94,6 +94,8 @@ Address conversion uses `Values.ip_address`, `Values.ip_address?`, and `Values.m
 
 `Records` owns selection arrays, while row objects remain caller-owned: treat those rows as stable during use, or pass `Immutable.copy(rows)` when a snapshot is needed. `Immutable.copy` rebuilds containers even when frozen, preserves shared references within each copy, and rejects cycles. This removes attached state, Hash defaults and singleton behavior without scanning method tables or maintaining a global cache. String snapshots use `String.new` followed by Ruby string deduplication; encoding and bytes are preserved. Container identity is not preserved across separate copies. `Immutable.copy_string` provides the same text boundary without allocating a container traversal map. Integer conversion accepts a minus sign only when `min` permits negative values (or is `nil`); the default remains nonnegative.
 
+`Document` builds indentation-based trees by default. Native grammars may override protected `build_blocks` and return ordered, non-overlapping root Blocks from the same cursor; `finish` still runs afterward. Block children must be contained and ordered, but need not have greater indentation. `Document::Flat` treats each command as an independent source block. `cursor.block(index)` reuses a one-line range; rewind/reset preserve its identity while completeness follows current cursor state. These APIs are provided by the paired 0.5.1 candidate; vendor grammar remains in consumers.
+
 ## Development and tests
 
 Name shared classes by their responsibility and use the namespace for platform context. Preserve filenames and class names that directly match device commands.

data/lib/ctx_parser/block.rb

@@ -21,7 +21,7 @@ module CtxParser
       previous_index = header.index
       unless children.is_a?(Array) && children.all? do |child|
           next false unless child.is_a?(Block) && child.cursor.equal?(cursor) &&
-            child.index > previous_index && child.last_index <= last_index && child.header.indent > header.indent
+            child.index > previous_index && child.last_index <= last_index
 
           previous_index = child.last_index
           true

data/lib/ctx_parser/cursor.rb

@@ -25,12 +25,20 @@ module CtxParser
         @lines << Line.new(index: @lines.size, raw: raw.freeze)
       end
       @lines.freeze
+      @line_blocks = {}
       @checksum = Digest::SHA256.hexdigest(@content).freeze
       reset!
     end
 
     # 返回原始来源行数。
     def size = lines.size
+
+    # 单行范围按需复用；回退和重置只改变状态，不改变不可变来源块。
+    def block(index)
+      validate_index!(index)
+      require_relative "block" unless defined?(Block)
+      @line_blocks[index] ||= Block.new(cursor: self, header: lines[index], children: [], last_index: index)
+    end
     # 判断游标是否到达来源末尾。
     def eof? = position >= size
     # 查看下一来源行，不推进游标也不修改状态。

data/lib/ctx_parser/document.rb

@@ -4,7 +4,7 @@ require_relative "cursor"
 require_relative "block"
 
 module CtxParser
-  # 持有配置树及诊断；分类器负责语法，Block 负责缩进范围。
+  # 持有配置树及诊断；构建器解释语法，Block 只约束来源范围。
   class Document
     attr_reader :cursor, :roots, :issues
 
@@ -18,7 +18,8 @@ module CtxParser
       end
       @cursor = source.is_a?(Cursor) ? source : Cursor.new(source, max_bytes: max_bytes)
       @comments, @boundaries, @issues = comments, boundaries, []
-      @roots = Block.read(cursor) { |line| classify(line) }
+      cursor.rewind
+      @roots = validate_roots(build_blocks)
       finish
       @issues = Immutable.copy(@issues)
     end
@@ -33,6 +34,9 @@ module CtxParser
 
     protected
 
+    # 默认按缩进构建；原生语法可覆盖此步骤，继续共享来源初始化和校验。
+    def build_blocks = Block.read(cursor) { |line| classify(line) }
+
     # 允许有状态词法分析器将行分类为配置条目、忽略行或边界。
     def classify(line)
       return :boundary if @boundaries&.match?(line.text)
@@ -43,5 +47,39 @@ module CtxParser
 
     # 允许词法分析器在文档结束时报告未闭合上下文，不向公共配置块添加词法状态。
     def finish; end
+
+    private
+
+    # 根块可以留出注释或边界行，但不能重叠、倒序或引用别的来源。
+    def validate_roots(entries)
+      entries = Array.new(entries) if entries.is_a?(Array)
+      previous = -1
+      unless entries.is_a?(Array) && entries.all? do |entry|
+          next false unless entry.is_a?(Block) && entry.cursor.equal?(cursor) && entry.index > previous
+
+          previous = entry.last_index
+          true
+        end
+        raise ArgumentError, "Root blocks must be ordered within this document"
+      end
+      entries.freeze
+    end
+
+    # set 等逐行配置没有缩进父子关系，每行独立保留来源状态。
+    class Flat < Document
+      protected
+
+      def build_blocks
+        entries = []
+        while (line = cursor.read)
+          case classify(line)
+          when :entry then entries << cursor.block(line.index)
+          when :ignored, :boundary then cursor.mark(line.index, state: :ignored)
+          else raise ArgumentError, "Invalid source line disposition"
+          end
+        end
+        entries
+      end
+    end
   end
 end

data/lib/ctx_parser/version.rb

@@ -2,5 +2,5 @@
 
 module CtxParser
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_parser
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Gatework contributors