mdom 0.1.0 → 0.3.0

data/lib/mdom/block_detector.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "error"
+
+module MDOM
+  # 用 Ruby 官方解析器（Prism）判定「不带 `begin` 前缀的 Ruby 块」与
+  # 「引导块关键字段落」（CSM §3.5）。
+  #
+  # 之所以必须交给 Prism，是因为 `do` / `end` 在英语里也是常见单词，纯词法
+  # 无法区分「Ruby 块」与「英文散文」（CSM §3.5.1）。判定只在 CSM → AST1
+  # 这一侧发生（docs/IMPLEMENTATION.md §1.1）；AST1 一旦产出，后续阶段不再
+  # 需要任何词法能力。
+  #
+  # 判定按候选块**增量 parse**（CSM §3.5.4）：从候选行开始逐行增加，只解析
+  # 这一段，而不是整篇一次解析——文档里的英文散文可能构成语法错误，整篇解析
+  # 会让一处错误波及全篇。
+  class BlockDetector
+    # 会引导块的关键字（CSM §3.5.1 的 B 类）。大小写严格匹配。
+    GUIDING_KEYWORDS = %w[begin while until for if unless case def class module do].freeze
+
+    # 关键字 → Prism 节点类。
+    KEYWORD_NODES = {
+      "begin" => Prism::BeginNode,
+      "while" => Prism::WhileNode,
+      "until" => Prism::UntilNode,
+      "for" => Prism::ForNode,
+      "if" => Prism::IfNode,
+      "unless" => Prism::UnlessNode,
+      "case" => Prism::CaseNode,
+      "def" => Prism::DefNode,
+      "class" => Prism::ClassNode,
+      "module" => Prism::ModuleNode
+    }.freeze
+
+    # 判定结果。
+    #
+    # * +end_index+ —— 块尾行在 +lines+ 中的下标（0 起）；
+    # * +form+ —— +:begin+（B 类）/ +:free+（A 类）；
+    # * +render+ —— 是否以 `.render` 收尾。
+    Detection = Struct.new(:end_index, :form, :render, keyword_init: true)
+
+    # 在 +lines+（已规范化：tab 展开、去 `\r`）中，从 +start_index+ 起判定候选块。
+    #
+    # +indent+ 是候选行的 CSM 缩进（前导空格数）。返回 +Detection+ 或 +nil+。
+    #
+    # 抛出 +CrossLevelError+，当 Prism 判定为块、但块尾行的缩进与块首行不同
+    # （CSM §3.5.2 条件 1）。
+    def detect(lines, start_index, indent)
+      first = drop_indent(lines[start_index], indent)
+      kind, keyword = classify(first)
+      return nil unless kind
+
+      # 增量 parse 只在**候选所在的 CSM 块范围内**进行（CSM §3.5.4）：块由空行
+      # 或更浅的缩进收尾。逐行增加，直到解析成为以候选行起始的完整顶层语句，
+      # 立即给出结论——不做整篇一次解析，散文里的语法错误不会波及全篇。
+      (start_index..block_end(lines, start_index, indent)).each do |last|
+        line_count = last - start_index + 1
+        code = (start_index..last).map { |i| drop_indent(lines[i], indent) }.join("\n")
+        result = parse(code)
+        next unless result
+
+        node = result.value.statements.body.last
+        next if node.nil?
+        # 顶层语句必须恰好从候选行开始、到当前行结束；一旦成立就说明
+        # 「从候选行起的一个完整 Ruby 语句到此为止」，无论是否匹配块结构，
+        # 都不必再往下扩展。
+        next unless covers?(node, code, line_count)
+
+        match = kind == :keyword ? keyword_match(node, keyword) : call_match(node)
+        return nil unless match
+
+        assert_same_indent!(lines, start_index, last, indent)
+        assert_no_heredoc!(code, start_index, last)
+        return Detection.new(end_index: last, form: match[:form], render: match[:render])
+      end
+      nil
+    end
+
+    private
+
+    # 候选所在的 CSM 块的最后一行（CSM §1.1：块由空行或更浅的缩进收尾）。
+    #
+    # 更浅缩进的那一行**包含在内**——块尾缩进与块首不同时要能按 §3.5.2 报错，
+    # 而不是静默降级成排版。
+    def block_end(lines, start_index, indent)
+      (start_index + 1...lines.size).each do |i|
+        return i - 1 if lines[i].strip.empty?
+        return i if indent_width(lines[i]) < indent
+      end
+      lines.size - 1
+    end
+
+    # 收窄：行首词是引导块关键字 → B 类；否则行首是字母 → A 类；否则不判定。
+    def classify(first)
+      word = first[/\A[A-Za-z_][A-Za-z0-9_]*/]
+      return [nil, nil] unless word
+
+      if GUIDING_KEYWORDS.include?(word)
+        [:keyword, word]
+      elsif first.match?(/\A[A-Za-z]/)
+        [:call, nil]
+      else
+        [nil, nil]
+      end
+    end
+
+    def parse(code)
+      result = Prism.parse(code)
+      result.success? ? result : nil
+    rescue StandardError
+      nil
+    end
+
+    # 顶层语句是否恰好覆盖「整段代码」。
+    def covers?(node, code, line_count)
+      loc = node.location
+      last_line = code.lines.last.to_s.rstrip
+      loc.start_line == 1 &&
+        loc.start_column.zero? &&
+        loc.end_line == line_count &&
+        loc.end_column == last_line.length
+    end
+
+    # A 类：`CallNode`（一个或多个）→ 带 `closing_loc` 的 `BlockNode`。
+    #
+    # 允许链上出现多个 `CallNode`，这自然覆盖了 `end.render` 这类收尾。
+    def call_match(node)
+      render = false
+      if render_call?(node)
+        render = true
+        node = node.receiver
+      end
+      return nil unless node.is_a?(Prism::CallNode)
+
+      cursor = node
+      while cursor.is_a?(Prism::CallNode)
+        block = cursor.block
+        return { form: :free, render: render } if block.is_a?(Prism::BlockNode) && block.closing_loc
+
+        cursor = cursor.receiver
+      end
+      nil
+    end
+
+    # B 类：Prism 给出的节点类必须与首行关键字一致。
+    def keyword_match(node, keyword)
+      render = false
+      if render_call?(node)
+        render = true
+        node = node.receiver
+      end
+
+      expected = KEYWORD_NODES[keyword]
+      return nil unless expected && node.is_a?(expected)
+
+      { form: :begin, render: render }
+    end
+
+    def render_call?(node)
+      node.is_a?(Prism::CallNode) && node.name == :render && node.block.nil?
+    end
+
+    # CSM §3.5.2 条件 1：块首行与块尾行的缩进必须完全相同。
+    def assert_same_indent!(lines, start_index, last_index, indent)
+      found = indent_width(lines[last_index])
+      return if found == indent
+
+      raise CrossLevelError,
+            "ruby block opens with #{indent} space(s) of indentation " \
+            "(line #{start_index + 1}) but closes with #{found} (line #{last_index + 1})"
+    end
+
+    # CSM §3.12 / 附录 E：heredoc（`<<~SQL` 等）**明确不支持**。既然块判定本来就
+    # 要交给 Prism，就顺便让它把 heredoc 也认出来——被判定为块的内容里出现
+    # +HEREDOC_START+ 就报错，而不是当普通块收下。
+    def assert_no_heredoc!(code, start_index, last_index)
+      return unless heredoc?(code)
+
+      raise UnsupportedHeredocError,
+            "heredoc is not supported (CSM §3.12): " \
+            "line #{start_index + 1}..#{last_index + 1}"
+    end
+
+    def heredoc?(code)
+      Prism.lex(code).value.any? { |token, _state| token.type.to_s == "HEREDOC_START" }
+    end
+
+    def indent_width(line)
+      line[/\A[ \t]*/].to_s.length
+    end
+
+    def drop_indent(line, count)
+      index = 0
+      index += 1 while index < count && index < line.length && line[index] == " "
+      line[index..]
+    end
+  end
+end

data/lib/mdom/builder.rb

@@ -0,0 +1,486 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "node/inline_nodes"
+require_relative "node/nodes"
+
+module MDOM
+  # 文档构造 DSL（docs/IMPLEMENTATION.md §4.3、§4.4）。
+  #
+  # **排版**：节点挂到「当前容器」，也就是*游标栈*的栈顶。块方法进入一个新容器、
+  # 退出时恢复，嵌套调用因此自然形成层级。
+  #
+  # **嵌入**：+render+ 是嵌入代码进入文档树的唯一通道（CSM §3.3）。它的插入位置
+  # 就是调用位置——不需要槽位 id、回填，也不需要「0 个消失 / n 个展开」的规则。
+  #
+  # **当前文档**：`值.render` 与求值作用域里的裸 `render` 都要知道「往哪篇文档挂」。
+  # 载体是类级的 +Builder.current+（一个文档栈）：+Builder.new+ 入栈、+to_document+
+  # 出栈，+Builder.with+ 提供显式作用域。类实例变量在 **Ractor** 之间天然隔离，所以
+  # CRuby 上的并行用 Ractor；`Thread` 并行会串上下文，不支持（docs/IMPLEMENTATION.md
+  # §5.1、§8.1 #5）。
+  #
+  # **并发**：+render+ 内部持一把互斥锁（CSM §3.3），只保证结构不被撕裂、不保证挂载
+  # 位置；mruby 的默认构建没有 `Mutex`，此时退化为无锁。
+  #
+  #   doc = MDOM::Builder.build do |b|
+  #     b.heading(1, "标题")
+  #     b.paragraph("正文 *强调*。")
+  #     b.list do |l|
+  #       l.item "一"
+  #       l.item "二"
+  #     end
+  #   end
+  #
+  # 块按**显式传参**取 builder（CSM §5.2.1）：块参数就是 builder 自身，不用
+  # +instance_eval+，因此不依赖 metaprog。
+  #
+  # 依赖边界（docs/IMPLEMENTATION.md §1.1）：本文件属 **builder 侧**——只用 mruby
+  # 子集、不 +require+ 任何外部 gem。字符串参数的行内解析与 `render(parse: true)`
+  # 的 CSM 解析都通过**依赖注入**取得：默认在首次需要时读取 +MDOM::InlineParser+ /
+  # +MDOM::Parser+ 常量，宿主可以替换成别的实现。
+  class Builder
+    # 能直接收下行内节点的容器：内容策略为 **PHRASING** 的块
+    # （`docs/CSM.md` 元素表，与 Parser 的边界一致）。
+    PHRASING_CONTAINERS = %i[paragraph heading term cite table_header_cell table_cell].freeze
+
+    # +render+ 的互斥锁类（CSM §3.3）。mruby 的默认构建既没有 `Thread` 也没有
+    # `Mutex`（属外部 mrbgem），此时为 +nil+ ⇒ 退化为无锁。
+    LOCK_CLASS = defined?(Mutex) ? Mutex : nil
+
+    # 构造一个文档并返回它。块参数是 builder，见类说明。
+    def self.build(builder = new, &block)
+      builder.document(&block)
+      builder.to_document
+    end
+
+    # -- 当前文档 -------------------------------------------------------------
+
+    # 「当前文档」的 builder；没有正在渲染的文档时为 +nil+（CSM §3.3）。
+    def self.current
+      (@current ||= []).last
+    end
+
+    # 把 +builder+ 设为当前文档。+new+ 会自动入栈，一般不必直接调用。
+    def self.enter(builder)
+      (@current ||= []).push(builder)
+      builder
+    end
+
+    # 退出当前文档。只在栈顶是 +builder+ 时出栈——因此可以反复调用（幂等），
+    # +to_document+ 被读多次也不会把栈弄乱。
+    def self.leave(builder)
+      stack = @current
+      stack.pop if stack && stack.last.equal?(builder)
+      builder
+    end
+
+    # 显式作用域：块内 +current+ 指向 +builder+，退出时恢复。
+    def self.with(builder)
+      enter(builder)
+      yield
+    ensure
+      leave(builder)
+    end
+
+    # +document+ 省略时新建一个空文档。
+    #
+    # +inline_parser+ / +parser+ 省略时，在首次需要时读取 +MDOM::InlineParser+ /
+    # +MDOM::Parser+ 常量。
+    def initialize(document: nil, inline_parser: nil, parser: nil)
+      @document = document || Node::Document.new
+      @stack = [@document]
+      @inline_parser = inline_parser
+      @parser = parser
+      @lock = LOCK_CLASS&.new
+      Builder.enter(self)
+    end
+
+    # -- 结果 -----------------------------------------------------------------
+
+    # 正在构造的文档（根节点）。同时把它从「当前文档」栈上退出。
+    def to_document
+      Builder.leave(self)
+      @document
+    end
+    alias finish to_document
+
+    # 把块的内容挂到文档根下。
+    def document(&block)
+      within(@document, &block) if block
+      self
+    end
+
+    # -- 块级 -----------------------------------------------------------------
+
+    # ATX 标题。+level+ 为 1–6，其余参数是行内内容。+closed+ 表示以等长 `#` 收尾
+    # （CSM §1.2 的 `<hgroup>` 用法）。
+    def heading(level = 1, *parts, closed: false, &block)
+      node = Node::Heading.new(level, closed: closed)
+      append(node)
+      fill_inline(node, parts, &block)
+      self
+    end
+
+    def h1(*parts, closed: false, &block) = heading(1, *parts, closed: closed, &block)
+    def h2(*parts, closed: false, &block) = heading(2, *parts, closed: closed, &block)
+    def h3(*parts, closed: false, &block) = heading(3, *parts, closed: closed, &block)
+    def h4(*parts, closed: false, &block) = heading(4, *parts, closed: closed, &block)
+    def h5(*parts, closed: false, &block) = heading(5, *parts, closed: closed, &block)
+    def h6(*parts, closed: false, &block) = heading(6, *parts, closed: closed, &block)
+
+    # 段落。字符串参数按 CSM 行内语法解析。
+    def paragraph(*parts, &block)
+      node = Node::Paragraph.new
+      append(node)
+      fill_inline(node, parts, &block)
+      self
+    end
+    alias p paragraph
+
+    # 列表。+ordered+: 有序列表；+task+: 任务列表。无块时 +items+ 逐个成为列表项。
+    def list(*items, ordered: false, task: false, marker: nil, &block)
+      node = Node::List.new(ordered: ordered, task: task, marker: marker || (ordered ? "1." : "-"))
+      append(node)
+      if block
+        within(node, &block)
+      else
+        item_marker = node.attributes[:marker]
+        within(node) { items.each { |text| item(text, marker: item_marker) } }
+      end
+      self
+    end
+
+    def ul(*items, &block) = list(*items, ordered: false, &block)
+    def ol(*items, &block) = list(*items, ordered: true, &block)
+
+    # 列表项。+parts+ 各自成为一个段落（`li` 的内容策略是 FLOW，见 CSM 元素表）；
+    # 有块时在段落之后继续嵌套。省略 +marker+ 时沿用最近一层列表的标记形式。
+    def item(*parts, marker: nil, task: false, checked: nil, &block)
+      node = Node::ListItem.new(marker: marker || current_list_marker, task: task, checked: checked)
+      append(node)
+      fill_flow(node, parts, &block)
+      self
+    end
+    alias li item
+
+    # 任务列表项。
+    def task(checked, *parts, &block)
+      item(*parts, task: true, checked: checked, &block)
+    end
+
+    # 块引用。+parts+ 各自成为一个段落（FLOW 内容）；+cite+ 对应 `>-` 收尾。
+    def blockquote(*parts, cite: nil, &block)
+      node = Node::Blockquote.new
+      append(node)
+      fill_flow(node, parts, &block)
+      append_cite(node, cite)
+      self
+    end
+    alias quote blockquote
+
+    # 引用来源（`<cite>`）。字符串参数按 CSM 行内语法解析。
+    def cite(*parts, &block)
+      node = Node::Cite.new(parts.grep(String).join)
+      append(node)
+      fill_inline(node, parts, &block)
+      self
+    end
+
+    # 围栏代码块。+code+ 按字面收下。
+    def code_block(code, lang: nil, params: nil, fence: 3)
+      append(Node::CodeBlock.new(code.to_s, lang: lang, params: params, fence: fence))
+      self
+    end
+
+    # 块级公式（`$$…$$`）。+tex+ 按字面收下（CSM §1.11）。
+    def math_block(tex)
+      append(Node::MathBlock.new(tex.to_s))
+      self
+    end
+
+    # 表格（纯结构，CSM §1.12）：块内给出若干 #row。
+    def table(&block)
+      node = Node::Table.new
+      append(node)
+      within(node, &block) if block
+      self
+    end
+
+    # 表格行：块内给出若干单元格。
+    def row(&block)
+      node = Node::TableRow.new
+      append(node)
+      within(node, &block) if block
+      self
+    end
+
+    # 表头单元格（`th`）。+align+ 为 +:left+ / +:center+ / +:right+，省略为默认对齐。
+    def header_cell(text = "", align: nil)
+      append_cell(Node::TableHeaderCell, text, align)
+    end
+
+    # 数据单元格（`td`）。+align+ 同上。
+    def cell(text = "", align: nil)
+      append_cell(Node::TableCell, text, align)
+    end
+
+    # 分隔线。
+    def hrule
+      append(Node::Hrule.new)
+      self
+    end
+    alias hr hrule
+
+    # 节块（`<div>`）。
+    def division(&block)
+      node = Node::Div.new
+      append(node)
+      within(node, &block) if block
+      self
+    end
+    alias div division
+
+    # 定义列表：块内依次给出 #term 与 #definition。
+    def definition_list(&block)
+      node = Node::DefinitionList.new
+      append(node)
+      within(node, &block) if block
+      self
+    end
+    alias dl definition_list
+
+    # 定义术语（`<dt>`）。字符串参数按 CSM 行内语法解析。
+    def term(*parts, &block)
+      node = Node::Term.new(parts.grep(String).join)
+      append(node)
+      fill_inline(node, parts, &block)
+      self
+    end
+
+    # 定义内容（`<dd>`）。+parts+ 各自成为一个段落（FLOW 内容）。
+    def definition(*parts, &block)
+      node = Node::Definition.new
+      append(node)
+      fill_flow(node, parts, &block)
+      self
+    end
+
+    # -- 行内 -----------------------------------------------------------------
+
+    # `*斜体*` → `<em>`。
+    def em(*parts, &block)
+      inline_node(Node::Emphasis.new, parts, &block)
+    end
+    alias emphasis em
+
+    # `**加粗**` → `<strong>`。
+    def strong(*parts, &block)
+      inline_node(Node::Strong.new, parts, &block)
+    end
+
+    # `` `代码` `` → `<code>`。参数按字面。
+    def code_span(value)
+      inline_node(Node::CodeSpan.new(value.to_s))
+    end
+
+    # `[标签](uri "title")` → `<a>`。
+    def link(uri, *label, title: nil, &block)
+      inline_node(Node::Link.new(uri, title: title), label, &block)
+    end
+
+    # `![alt](uri "title")` → `<img>`。
+    def image(uri, alt: nil, title: nil)
+      alt = alt&.to_s
+      node = Node::Image.new(uri, alt: alt || "", title: title,
+                                  children: alt.nil? ? [] : inline_parser.parse(alt, literal: true))
+      inline_node(node)
+    end
+
+    # 行尾 `\` → `<br>`。
+    def hardbreak
+      inline_node(Node::HardBreak.new)
+    end
+
+    # -- 注入通道 -------------------------------------------------------------
+
+    # 嵌入代码进入文档树的唯一通道（CSM §3.3）：值挂在**当前容器**，插入位置就是
+    # 调用位置。`render` 是排版指令的一种，与 `heading` / `paragraph` / `list` 同级。
+    #
+    # 值按类型分派，**包装方式取决于当前容器**（行内容器收行内节点，块级容器收块）：
+    #
+    # | 值 | 行内容器中 | 块级容器中 |
+    # |----|-----------|-----------|
+    # | `nil` | 忽略 | 忽略 |
+    # | 节点 | 直接插入（自动从原父脱离） | 同左 |
+    # | 字符串 | 文本节点 | 段落 |
+    # | `Array` / `Enumerable` | 逐项递归 | 逐项递归 |
+    # | 其它 | `to_s` 后同上 | `to_s` 后同上 |
+    #
+    # +parse: true+ 时字符串按 CSM 递归解析，解析出的**子节点**逐个插入——不再按
+    # 容器包装，因为解析结果自带块级结构。
+    def render(value, parse: false)
+      if @lock
+        @lock.synchronize { emit(value, parse) }
+      else
+        emit(value, parse)
+      end
+      self
+    end
+
+    private
+
+    # 把 +>-+ 的出处作为 +Node::Cite+ 挂到引用末尾；正文按行内语法解析。
+    def append_cite(node, cite)
+      return if cite.nil?
+
+      source = Node::Cite.new
+      node << source
+      fill_inline(source, [cite.to_s])
+    end
+
+    # 单元格：正文按 CSM 行内语法解析（PHRASING）。
+    def append_cell(klass, text, align)
+      node = klass.new("", align: align)
+      append(node)
+      fill_inline(node, [text.to_s])
+      self
+    end
+
+    # 分派一个值。见 #render 的说明表。
+    def emit(value, parse)
+      case value
+      when nil then nil
+      when Node::BaseNode then @stack.last << value
+      when String then emit_string(value, parse)
+      when Enumerable then value.each { |item| emit(item, parse) }
+      else emit_string(value.to_s, parse)
+      end
+    end
+
+    def emit_string(text, parse)
+      return attach_tree(text) if parse
+      return @stack.last << Node::Text.new(text) if inline_container?
+
+      # 块级容器收不下裸文本，包成段落。
+      paragraph = Node::Paragraph.new(text)
+      paragraph << Node::Text.new(text)
+      @stack.last << paragraph
+    end
+
+    # 当前容器能否直接收下行内节点。
+    def inline_container?
+      PHRASING_CONTAINERS.include?(@stack.last.type)
+    end
+
+    # 进入 +node+ 作为当前容器，块结束后恢复。
+    def within(node)
+      @stack.push(node)
+      yield self
+    ensure
+      @stack.pop
+    end
+
+    def append(node)
+      @stack.last << node
+      node
+    end
+
+    # 最近一层列表的标记形式（有序列表得到 `N.`），没有则 `-`。
+    def current_list_marker
+      list = @stack.reverse.find { |node| node.is_a?(Node::List) }
+      list ? list.attributes[:marker] : "-"
+    end
+
+    # 解析 +source+，把结果的**子节点**逐个挂到当前容器（不是挂整个 Document）。
+    def attach_tree(source)
+      parser.parse(source).children.dup.each { |child| @stack.last << child }
+    end
+
+    # 行内节点方法：挂载后返回节点本身，便于 `b.p { b.em "x" }` 这样的显式构造。
+    def inline_node(node, parts = [], &block)
+      append(node)
+      fill_inline(node, parts, &block)
+      node
+    end
+
+    # 填充行内内容：给块就用块（进入节点作为容器），否则解析 +parts+。
+    def fill_inline(node, parts, &block)
+      if block
+        raise ArgumentError, "cannot combine inline arguments with a block" unless parts.empty?
+
+        return within(node, &block)
+      end
+
+      fill_inline_parts(node, parts)
+    end
+
+    # FLOW 容器的填充（CSM 元素表：`blockquote` / `li` / `dd` 的内容策略是 FLOW）：
+    # +parts+ 各自成为一个段落，随后进入块（嵌套的块级子节点）。
+    def fill_flow(node, parts, &block)
+      parts.each { |part| append_paragraph(node, part) }
+      within(node, &block) if block
+      node
+    end
+
+    # 把一个 part 作为段落挂到 +node+ 下：字符串按 CSM 行内语法解析，节点原样收下。
+    def append_paragraph(node, part)
+      paragraph = Node::Paragraph.new
+      node << paragraph
+      return node << part if part.is_a?(Node::BaseNode)
+
+      fill_inline(paragraph, [part.to_s])
+      node
+    end
+
+    # 把 +parts+ 解析成行内节点挂到 +node+。
+    def fill_inline_parts(node, parts)
+      # `text` 保留原文，与 Parser 构造出的节点一致；只有全字符串参数才成立。
+      node.attributes[:text] = parts.join if !parts.empty? && parts.all?(String)
+      inline_parts(parts).each { |part| node << part }
+      node
+    end
+
+    # 把参数转成行内节点：字符串按 CSM 行内语法解析，节点原样收下。
+    def inline_parts(parts)
+      parts.flat_map do |part|
+        case part
+        when Node::BaseNode then [part]
+        when String then inline_parser.parse(part)
+        else [Node::Text.new(part.to_s)]
+        end
+      end
+    end
+
+    # 行内解析器（用于字符串参数）：默认取 +MDOM::InlineParser+，本文件不 require 它。
+    def inline_parser
+      @inline_parser ||= MDOM::InlineParser
+    rescue NameError
+      raise ArgumentError,
+            "string arguments need an inline parser: require \"mdom/inline_parser\" or pass inline_parser:"
+    end
+
+    # 块级解析器（用于 `render(parse: true)`）：默认取 +MDOM::Parser+。
+    def parser
+      @parser ||= MDOM::Parser
+    rescue NameError
+      raise ArgumentError,
+            "render(parse: true) needs a parser: require \"mdom/parser\" or pass parser:"
+    end
+  end
+end
+
+# `值.render`（CSM §3.3）：把值交给**当前文档**的 builder。
+#
+# 定义在 `Object` 上，所以 `begin ... end.render` 对任意块值都成立（`String`、
+# `Array`、`nil`……）。代价是给宿主的每个对象都加了 `render`——docs/IMPLEMENTATION.md
+# §5.2 已接受这一点，并说明为什么这是唯一可行的落点。
+class Object
+  # 把自身渲染进当前文档；没有正在渲染的文档时抛错。
+  def render(**options)
+    builder = MDOM::Builder.current
+    raise MDOM::Error, "render outside of a document" if builder.nil?
+
+    builder.render(self, **options)
+    self
+  end
+end

data/lib/mdom/error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MDOM
+  # CSM 处理的错误基类。
+  class Error < StandardError; end
+
+  # CSM 源码不合法（解析期）。消息中带文档行号，便于定位。
+  class ParseError < Error; end
+
+  # 判定为 Ruby 块，但块首行与块尾行的 CSM 缩进不同（CSM §3.5.2 条件 1）。
+  class CrossLevelError < ParseError; end
+
+  # 围栏代码块没有找到对称的结束围栏（扫描到文档末尾）。
+  class UnclosedFenceError < ParseError; end
+
+  # 块级公式的 `$$` 包围式没有找到独占一行的结束标记（扫描到文档末尾）。
+  class UnclosedMathError < ParseError; end
+
+  # 块里出现 heredoc。CSM §3.12 明确**不支持** heredoc（附录 E），一旦出现就报错，
+  # 而不是把它当普通块收下。
+  class UnsupportedHeredocError < ParseError; end
+end