ctx_parser 0.1.1

data/lib/ctx_parser/block.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module CtxParser
+  # 配置节点覆盖整个子树，保留未知命令、空白及原始换行。
+  class Block
+    Draft = Struct.new(:header, :children, :last_index)
+    private_constant :Draft
+
+    attr_reader :cursor, :header, :children, :last_index
+
+    # 冻结已校验的来源范围及其子配置块。
+    def initialize(cursor:, header:, children:, last_index:)
+      unless cursor.lines[header.index].equal?(header) && last_index.is_a?(Integer) &&
+          (header.index...cursor.size).cover?(last_index)
+        raise ArgumentError, "Invalid source block range"
+      end
+
+      @cursor, @header, @last_index = cursor, header, last_index
+      @children = children.dup.freeze
+      freeze
+    end
+
+    # 构建缩进结构，同时由调用方根据当前词法状态分类来源行。
+    def self.read(cursor, comments: nil, boundaries: nil)
+      roots, stack = [], []
+      while (line = cursor.read)
+        disposition = if block_given?
+          yield line
+        elsif boundaries&.match?(line.text)
+          :boundary
+        elsif line.text.empty? || comments&.match?(line.text)
+          :ignored
+        else
+          :entry
+        end
+        case disposition
+        when :boundary
+          stack.pop.last_index = line.index - 1 until stack.empty?
+          cursor.mark(line.index, state: :ignored)
+        when :ignored
+          cursor.mark(line.index, state: :ignored)
+        when :entry
+          while stack.any? && line.indent <= stack.last.header.indent
+            stack.pop.last_index = line.index - 1
+          end
+          draft = Draft.new(line, [], nil)
+          (stack.last&.children || roots) << draft
+          stack << draft
+        else
+          raise ArgumentError, "Invalid source line disposition"
+        end
+      end
+      stack.pop.last_index = cursor.position - 1 until stack.empty?
+      roots.map { |draft| build(cursor, draft) }.freeze
+    end
+
+    # 迭代冻结配置块树，不依赖 Ruby 递归深度。
+    def self.build(cursor, draft)
+      # 使用显式栈先构建子节点再构建父节点，保留顺序并避免递归栈增长。
+      stack = [ [ draft, 0, [] ] ]
+      until stack.empty?
+        entry, next_child, children = stack.last
+        if (child = entry.children[next_child])
+          stack.last[1] += 1
+          stack << [ child, 0, [] ]
+        else
+          block = new(cursor: cursor, header: entry.header, last_index: entry.last_index, children: children)
+          stack.pop
+          return block if stack.empty?
+
+          stack.last[2] << block
+        end
+      end
+    end
+    private_class_method :build
+
+    # 返回配置块标题的零起始索引。
+    def index = header.index
+    # 返回配置块标题的一起始来源行号。
+    def line = header.number
+    # 返回已去除外围缩进和行结束符的来源内容。
+    def text = header.text
+    # 返回配置块或捕获事实覆盖的闭合来源区间。
+    def line_range = line..(last_index + 1)
+    # 返回属于当前配置块的原始来源行。
+    def lines = cursor.lines[index..last_index].freeze
+    # 返回配置块或捕获事实对应的精确来源文本。
+    def content = lines.map(&:raw).join.freeze
+    # 返回当前配置块各来源行的处理状态。
+    def states = lines.map { |source| cursor.state(source.index) }.freeze
+    # 要求块内所有来源行均已解析或明确忽略。
+    def complete? = states.all? { |state| Cursor::RESOLVED_STATES.include?(state) }
+    # 序列化诊断元数据，不包含原始来源文本。
+    def as_json(*) = { first_line: line, last_line: last_index + 1, children: children.size }
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} lines=#{line_range} children=#{children.size}>"
+    alias to_s inspect
+  end
+end

data/lib/ctx_parser/capture.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "block"
+require_relative "immutable"
+
+module CtxParser
+  # 保存不可变事实及其来源；路径相对于首条配置结果记录。
+  class Capture
+    Snapshot = Data.define(:data, :path) do
+      # 此边界仅接收调用方原始数据，各快照自行持有深度冻结的副本。
+      def initialize(data:, path:)
+        unless path.is_a?(Array) && path.all? { |key| key.nil? || key.is_a?(Symbol) || key.is_a?(String) || key.is_a?(Integer) }
+          raise ArgumentError, "Capture path must contain record keys or indexes"
+        end
+
+        super(data: Immutable.copy(data), path: Immutable.copy(path))
+      end
+    end
+    private_constant :Snapshot
+
+    attr_reader :block, :data, :path
+
+    # 冻结解析事实及其来源块和结果路径。
+    def initialize(block:, data:, path:)
+      raise ArgumentError, "Capture source must be a block" unless block.is_a?(Block)
+
+      initialize_snapshot(block, Snapshot.new(data: data, path: path))
+    end
+
+    # 同一事实的多个来源共享已复制的值，不共享未经校验的调用方容器。
+    def self.for_blocks(blocks, data:, path:)
+      unless blocks.is_a?(Array) && blocks.all? { |block| block.is_a?(Block) }
+        raise ArgumentError, "Capture sources must be blocks"
+      end
+      return [].freeze if blocks.empty?
+
+      snapshot = Snapshot.new(data: data, path: path)
+      blocks.map { |block| allocate.tap { |capture| capture.send(:initialize_snapshot, block, snapshot) } }.freeze
+    end
+
+    # 返回配置块或捕获事实对应的精确来源文本。
+    def content = block.content
+    # 返回配置块或捕获事实覆盖的闭合来源区间。
+    def line_range = block.line_range
+    # 判断捕获事实依赖的所有来源行是否均已解决。
+    def complete? = block.complete?
+    # 序列化诊断元数据，不包含原始来源文本。
+    def as_json(*) = { first_line: line_range.begin, last_line: line_range.end, complete: complete? }
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} lines=#{line_range}>"
+    alias to_s inspect
+
+    private
+
+    # 私有工厂仅接收由本类完成复制及校验的快照。
+    def initialize_snapshot(block, snapshot)
+      @block, @data, @path = block, snapshot.data, snapshot.path
+      freeze
+    end
+  end
+end

data/lib/ctx_parser/command_catalog.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+
+module CtxParser
+  # 每条命令仅声明一次，并派生不可变维度及解析器索引。
+  class CommandCatalog
+    attr_reader :entries, :commands, :parsers
+
+    # 校验并冻结受支持的维度到命令声明。
+    def initialize(entries, multi_command: false)
+      unless entries.is_a?(Array) && entries.any?
+        raise ArgumentError, "Command catalog must contain declarations"
+      end
+      raise ArgumentError, "Multi-command selection must be boolean" unless multi_command == true || multi_command == false
+
+      @multi_command = multi_command
+      @commands, @parsers = {}, {}
+      @entries = entries.map { |entry| register(entry) }.freeze
+      @commands.each_value { |value| value.freeze }
+      @commands.freeze
+      @parsers.freeze
+      freeze
+    end
+
+    private
+
+    # 仅复制声明数据；解析器类保留正常 Ruby 生命周期。
+    def register(entry)
+      unless entry.is_a?(Hash) && entry.size == 3 && %i[dimensions command parser].all? { |key| entry.key?(key) }
+        raise ArgumentError, "Command declaration requires dimensions, command and parser"
+      end
+
+      dimensions, command, parser = entry.values_at(:dimensions, :command, :parser)
+      unless dimensions.is_a?(Array) && dimensions.any? && dimensions.all? { |name| name.is_a?(Symbol) && !name.empty? } &&
+          dimensions.uniq == dimensions && (@multi_command || dimensions.none? { |name| @commands.key?(name) })
+        raise ArgumentError, "Command dimensions must be unique nonempty symbols"
+      end
+      unless command.is_a?(String) && !command.strip.empty? && !/[\x00-\x1f\x7f]/.match?(command)
+        raise ArgumentError, "Command must be nonempty text without control characters"
+      end
+      raise ArgumentError, "Command is already declared" if @parsers.key?(command)
+      raise ArgumentError, "Command parser must inherit from Parser" unless parser.is_a?(Class) && parser < Parser
+
+      command = command.dup.freeze
+      dimensions = dimensions.dup.freeze
+      dimensions.each do |name|
+        @commands[name] = @commands.key?(name) ? Array(@commands[name]) + [ command ] : command
+      end
+      @parsers[command] = parser
+      { dimensions: dimensions, command: command, parser: parser }.freeze
+    end
+  end
+end

data/lib/ctx_parser/configuration_parser.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+
+module CtxParser
+  # 共享来源状态与作用域管理；具体解析器负责识别规则及诊断。
+  class ConfigurationParser < Parser
+    private
+
+    # 为新的配置解析建立来源跟踪状态。
+    def read_configuration(...)
+      @source_path = []
+      @invalid_source = @source_error = nil
+      super
+    end
+
+    # 仅在解释成功后标记来源行；嵌套转换失败归因到最内层来源。
+    def analyze(block)
+      value = yield
+      cursor.mark(block.index, state: :parsed) if cursor.state(block.index) == :pending
+      if cursor.state(block.index) == :parsed
+        block.children.each { |child| unparsed_child(child) if cursor.state(child.index) == :pending }
+      end
+      value
+    rescue ArgumentError => error
+      # 同一异常向外传播时仅保留最内层出错块，避免把整个父配置误标为无效。
+      unless @source_error.equal?(error)
+        @source_error, @invalid_source = error, block
+      end
+      if block.equal?(@invalid_source)
+        cursor.mark(block.index, state: :invalid)
+      elsif cursor.state(block.index) == :pending
+        cursor.mark(block.index, state: :parsed)
+      end
+      raise
+    end
+
+    # 各子节点独立保留来源状态及错误位置。
+    def analyze_children(block, &operation)
+      block.children.each { |child| analyze(child) { operation.call(child) } }
+    end
+
+    # 进入临时结果路径，成功或失败后均恢复父作用域。
+    def scope(block, path)
+      previous_path = @source_path
+      @source_path = path
+      value = yield
+      capture(block, value, path)
+      value
+    ensure
+      @source_path = previous_path
+    end
+
+    # 将归一化事实关联到来源块及结果路径。
+    def capture(block, value, path)
+      cursor.capture(block, data: value, path: path)
+    end
+
+    # 迭代忽略领域外子树，不宣称其产生已解析事实。
+    def ignore(block)
+      pending = [ block ]
+      until pending.empty?
+        entry = pending.pop
+        cursor.mark(entry.index, state: :ignored)
+        pending.concat(entry.children)
+      end
+      nil
+    end
+
+    # 未处理的子节点保持待解析；具体解析器可诊断位置错误的相关命令。
+    def unparsed_child(_block); end
+  end
+end

data/lib/ctx_parser/cursor.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "line"
+require_relative "capture"
+require_relative "input"
+
+module CtxParser
+  # 每次解析独立持有游标，区分读取位置、访问状态与语义状态。
+  class Cursor
+    STATES = %i[pending parsed ignored unsupported invalid].freeze
+    RESOLVED_STATES = %i[parsed ignored].freeze
+
+    attr_reader :content, :lines, :checksum, :position
+
+    # 为单次解析创建独立的来源行、语义状态及事实索引。
+    def initialize(content)
+      raise ArgumentError, "Configuration content must be text" unless content.is_a?(String)
+
+      @content = Input.text(content, encoding: :transcode).freeze
+
+      @lines = @content.scan(/[^\r\n]*(?:\r\n|\r|\n)|[^\r\n]+\z/).each_with_index.map do |raw, index|
+        Line.new(index: index, raw: raw)
+      end.freeze
+      @checksum = Digest::SHA256.hexdigest(@content).freeze
+      reset!
+    end
+
+    # 返回原始来源行数。
+    def size = lines.size
+    # 判断游标是否到达来源末尾。
+    def eof? = position >= size
+    # 查看下一来源行，不推进游标也不修改状态。
+    def peek = lines[position]
+    # 返回来源行处理状态的不可变快照。
+    def states = @states.dup.freeze
+    # 提供已成功解释的来源行信息。
+    def parsed_flags = @states.map { |state| state == :parsed }.freeze
+    # 即使采用后序分析，也按文档顺序返回来源，并保留同一行的捕获顺序。
+    def captures = @ordered_captures ||= ordered_captures(@captures)
+
+    # 推进游标并记录访问，不代表该行已成功解析。
+    def read
+      return nil if eof?
+
+      line = peek
+      @visited[position] = true
+      @position += 1
+      line
+    end
+
+    # 查找下一待处理行；语义成功或失败仍须由调用方显式记录。
+    def read_pending
+      while (line = read)
+        return line if state(line.index) == :pending
+      end
+      nil
+    end
+
+    # 校验来源行索引后，返回对应语义处理状态。
+    def state(index)
+      validate_index!(index)
+      @states[index]
+    end
+
+    # 检查是否解释成功；无效行索引保留 nil。
+    def parsed?(index) = valid_index?(index) ? @states[index] == :parsed : nil
+    # 独立检查游标是否访问过该行，不与解释成功混淆。
+    def visited?(index) = valid_index?(index) ? @visited[index] : nil
+
+    # 为有效来源行记录明确的语义状态。
+    def mark(index, state: :parsed)
+      validate_index!(index)
+      raise ArgumentError, "Invalid line state" unless STATES.include?(state)
+
+      @states[index] = state
+      self
+    end
+
+    # 返回起点开始下一轮处理，同时保留语义状态与来源证据。
+    def rewind
+      @position = 0
+      self
+    end
+
+    # 清空访问、语义状态及捕获事实，重新开始分析。
+    def reset!
+      @states = Array.new(size, :pending)
+      @visited = Array.new(size, false)
+      @captures = []
+      @captures_by_path, @ordered_by_path = {}, {}
+      @ordered_captures = nil
+      rewind
+    end
+
+    # 回退一行，不改变语义状态。
+    def step_back
+      return false if position.zero?
+
+      @position -= 1
+      true
+    end
+
+    # 重新访问前一行，并将其恢复为待解析状态。
+    def unread
+      return false unless step_back
+
+      mark(position, state: :pending)
+      true
+    end
+
+    # 将最后消费的行恢复为待解析，不移动游标。
+    def defer
+      return false if position.zero?
+
+      mark(position - 1, state: :pending)
+      true
+    end
+
+    # 返回未解决或无效行，排除已明确忽略的注释及领域外配置。
+    def unparsed_lines
+      lines.reject { |line| RESOLVED_STATES.include?(state(line.index)) }.freeze
+    end
+
+    # 拼接未解决来源行，并保留原有格式。
+    def unparsed_content = unparsed_lines.map(&:raw).join.freeze
+
+    # 将事实快照关联到来源块，不将整个块标记为解析成功。
+    def capture(block, data:, path:)
+      capture_many([ block ], data: data, path: path).first
+    end
+
+    # 注册归纳事实的不可变快照前，先校验全部来源。
+    def capture_many(blocks, data:, path:)
+      unless blocks.is_a?(Array) && blocks.all? { |block| block.is_a?(Block) && block.cursor.equal?(self) }
+        raise ArgumentError, "Blocks must belong to this cursor"
+      end
+
+      captured = Capture.for_blocks(blocks, data: data, path: path)
+      captured.each do |capture|
+        @captures << capture
+        (@captures_by_path[capture.path] ||= []) << capture
+        @ordered_by_path.delete(capture.path)
+      end
+      @ordered_captures = nil unless captured.empty?
+      captured
+    end
+
+    # 使用捕获时的不可变路径作为缓存键，不使用调用方可变查询数组。
+    def captures_for(path)
+      return @ordered_by_path[path] if @ordered_by_path.key?(path)
+
+      entries = @captures_by_path[path]
+      entries ? @ordered_by_path[entries.first.path] = ordered_captures(entries) : [].freeze
+    end
+    # 序列化诊断元数据，不包含原始来源文本。
+    def as_json(*) = { position: position, lines: size, states: @states.tally, captures: @captures.size }
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} position=#{position} lines=#{size} captures=#{@captures.size}>"
+    alias to_s inspect
+
+    private
+
+    # 同一来源行保持稳定插入顺序，以维持既有来源追溯契约。
+    def ordered_captures(entries)
+      entries.each_with_index.sort_by { |capture, order| [ capture.block.index, order ] }.map(&:first).freeze
+    end
+
+    # 检查整数索引是否属于当前来源文档。
+    def valid_index?(index) = index.is_a?(Integer) && index >= 0 && index < size
+
+    # 拒绝指向当前文档之外的行引用。
+    def validate_index!(index)
+      raise IndexError, "Line index is outside the document" unless valid_index?(index)
+    end
+  end
+end

data/lib/ctx_parser/document.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "cursor"
+require_relative "block"
+
+module CtxParser
+  # 持有配置树及诊断；分类器负责语法，Block 负责缩进范围。
+  class Document
+    attr_reader :cursor, :roots, :issues
+
+    # 使用平台提供的注释及边界规则构建来源文档。
+    def initialize(source, comments: nil, boundaries: nil)
+      @cursor = source.is_a?(Cursor) ? source : Cursor.new(source)
+      @comments, @boundaries, @issues = comments, boundaries, []
+      @roots = Block.read(cursor) { |line| classify(line) }
+      finish
+      @issues.freeze
+    end
+
+    # 选择符合目标命令语法的根配置块。
+    def sections(pattern) = roots.select { |entry| pattern.match?(entry.text) }
+    # 序列化诊断元数据，不包含原始来源文本。
+    def as_json(*) = { sections: roots.size, issues: issues.size, cursor: cursor.as_json }
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} sections=#{roots.size} issues=#{issues.size}>"
+    alias to_s inspect
+
+    protected
+
+    # 允许有状态词法分析器将行分类为配置条目、忽略行或边界。
+    def classify(line)
+      return :boundary if @boundaries&.match?(line.text)
+      return :ignored if line.text.empty? || @comments&.match?(line.text)
+
+      :entry
+    end
+
+    # 允许词法分析器在文档结束时报告未闭合上下文，不向公共配置块添加词法状态。
+    def finish; end
+  end
+end

data/lib/ctx_parser/immutable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CtxParser
+  # 复制并冻结普通数据，避免解析快照共享调用方可变状态。
+  module Immutable
+    # 深度复制并冻结普通数据，拒绝可执行或不支持的对象。
+    def self.copy(value)
+      # 容器已冻结也可能持有可变子对象，仍须递归复制；冻结字符串可直接复用。
+      case value
+      when Hash then value.to_h { |key, item| [ copy(key), copy(item) ] }.freeze
+      when Array then value.map { |item| copy(item) }.freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      when Symbol, Numeric, NilClass, TrueClass, FalseClass then value
+      else raise ArgumentError, "Values must contain plain data"
+      end
+    end
+  end
+end

data/lib/ctx_parser/input.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CtxParser
+  # 按显式编码、NUL 和大小策略归一化输入字节及换行。
+  module Input
+    module_function
+
+    # 校验来源文本，仅按请求调整编码或换行形式。
+    def text(content, encoding: :preserve, newlines: :preserve, allow_nul: false, max_bytes: nil)
+      raise ArgumentError, "CLI output must be text" unless content.is_a?(String)
+      raise ArgumentError, "Invalid encoding policy" unless %i[preserve utf8 transcode].include?(encoding)
+      raise ArgumentError, "Invalid newline policy" unless %i[preserve lf delete_cr].include?(newlines)
+      raise ArgumentError, "NUL policy must be boolean" unless [ true, false ].include?(allow_nul)
+      raise ArgumentError, "Invalid byte limit" unless max_bytes.nil? || (max_bytes.is_a?(Integer) && max_bytes >= 0)
+      raise ArgumentError, "CLI output exceeds byte limit" if max_bytes && content.bytesize > max_bytes
+
+      value = content.dup
+      value.force_encoding(Encoding::UTF_8) if encoding == :utf8 || value.encoding == Encoding::BINARY
+      raise EncodingError, "CLI output encoding is invalid" unless value.valid_encoding?
+
+      value = value.encode(Encoding::UTF_8) if encoding == :transcode
+      raise ArgumentError, "CLI output contains a NUL byte" if !allow_nul && value.include?("\0")
+
+      case newlines
+      when :lf then value.gsub(/\r\n?/, "\n")
+      when :delete_cr then value.delete("\r")
+      else value
+      end
+    end
+  end
+end

data/lib/ctx_parser/line.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CtxParser
+  # 不可变来源行保留原始换行，同时提供用于语法匹配的归一化文本。
+  Line = Data.define(:index, :raw) do
+    # 保留原始来源文本，并生成索引、正文及缩进信息。
+    def initialize(index:, raw:)
+      raise ArgumentError, "Line index must be nonnegative" unless index.is_a?(Integer) && index >= 0
+      raise ArgumentError, "Line content must be text" unless raw.is_a?(String)
+
+      @text = raw.chomp.strip.freeze
+      @indent = raw[/\A[ \t]*/].size
+      super(index: index, raw: raw.dup.freeze)
+    end
+
+    # 返回诊断使用的一起始行号。
+    def number = index + 1
+    # 返回已去除外围缩进和行结束符的来源内容。
+    def text = @text
+    # 返回构建配置树使用的前导缩进。
+    def indent = @indent
+    # 序列化诊断元数据，不包含原始来源文本。
+    def as_json(*) = { number: number }
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} number=#{number}>"
+    alias to_s inspect
+  end
+end

data/lib/ctx_parser/parser.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module CtxParser
+  # 提供公共命令解析契约；厂商语法、编码与完整性由子类负责。
+  class Parser
+    attr_reader :cursor, :blocks, :document
+
+    # 每次调用使用新实例解析，避免共享来源状态。
+    def self.parse(text, complete: false)
+      new.parse(text, complete: complete)
+    end
+
+    # 校验输入及完整性，重置来源状态后执行命令解析器。
+    def parse(text, complete: false)
+      @document, @cursor, @blocks = nil, nil, [].freeze
+      raise ArgumentError, "Runtime output must be text" unless text.is_a?(String)
+      raise ArgumentError, "Completeness must be boolean" unless [ true, false ].include?(complete)
+
+      parse_output(text, complete: complete)
+    end
+
+    # 序列化诊断元数据，不包含原始来源文本。
+    def as_json(*) = { parser: self.class.name, cursor: cursor&.as_json, blocks: Array(blocks).size }
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name}>"
+
+    private
+
+    # 每次解析创建私有游标与配置树；序列化结果不包含来源正文。
+    def read_configuration(text, comments: nil, boundaries: nil, document_class: Document)
+      @document = document_class.new(text, comments: comments, boundaries: boundaries)
+      @cursor, @blocks = document.cursor, document.roots
+      @blocks
+    end
+
+    # 解释当前命令回显，保留不支持或格式错误的证据。
+    def parse_output(text, complete:)
+      raise NotImplementedError, "Command parsers must implement parse_output"
+    end
+  end
+end
+
+# 在依赖可能触发 Rails 自动加载此命名空间前，先定义基础类。
+require_relative "result"
+require_relative "result_set"
+require_relative "document"