mdom 0.3.0 → 0.4.0

data/lib/mdom/builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "error"
+require_relative "markdown_serializer"
 require_relative "node/inline_nodes"
 require_relative "node/nodes"
 
@@ -35,9 +36,14 @@ module MDOM
   # +instance_eval+，因此不依赖 metaprog。
   #
   # 依赖边界（docs/IMPLEMENTATION.md §1.1）：本文件属 **builder 侧**——只用 mruby
-  # 子集、不 +require+ 任何外部 gem。字符串参数的行内解析与 `render(parse: true)`
-  # 的 CSM 解析都通过**依赖注入**取得：默认在首次需要时读取 +MDOM::InlineParser+ /
-  # +MDOM::Parser+ 常量，宿主可以替换成别的实现。
+  # 子集、不 +require+ 任何**外部 gem**。行内内容的**结构化构造**（节点参数 / 块）
+  # 完全不需要解析器，因此既不需要 prism 也不依赖宿主的配置；只有字符串参数这一
+  # 便利形式需要行内解析器，且它是**注入**的：默认在首次需要时读取
+  # +MDOM::InlineParser+ / +MDOM::Parser+ 常量，宿主可以替换成别的实现。
+  #
+  # 块形式的行内内容会用 +MDOM::MarkdownSerializer+ 重建 +attributes[:text]+ 原文
+  # 缓存（`text` / `cite` 这类读取靠它）。它与本文件同属 builder 侧、零 gem 依赖，
+  # 所以是本文件唯一的 +require+。
   class Builder
     # 能直接收下行内节点的容器：内容策略为 **PHRASING** 的块
     # （`docs/CSM.md` 元素表，与 Parser 的边界一致）。
@@ -84,13 +90,14 @@ module MDOM
 
     # +document+ 省略时新建一个空文档。
     #
-    # +inline_parser+ / +parser+ 省略时，在首次需要时读取 +MDOM::InlineParser+ /
-    # +MDOM::Parser+ 常量。
-    def initialize(document: nil, inline_parser: nil, parser: nil)
+    # +inline_parser+ / +parser+ / +text_serializer+ 省略时，在首次需要时读取
+    # +MDOM::InlineParser+ / +MDOM::Parser+ / +MDOM::MarkdownSerializer+ 常量。
+    def initialize(document: nil, inline_parser: nil, parser: nil, text_serializer: nil)
       @document = document || Node::Document.new
       @stack = [@document]
       @inline_parser = inline_parser
       @parser = parser
+      @text_serializer = text_serializer
       @lock = LOCK_CLASS&.new
       Builder.enter(self)
     end
@@ -145,7 +152,9 @@ module MDOM
         within(node, &block)
       else
         item_marker = node.attributes[:marker]
-        within(node) { items.each { |text| item(text, marker: item_marker) } }
+        within(node) do
+          items.each { |text| item(text, marker: item_marker, task: task, checked: task ? false : nil) }
+        end
       end
       self
     end
@@ -154,8 +163,15 @@ module MDOM
     def ol(*items, &block) = list(*items, ordered: true, &block)
 
     # 列表项。+parts+ 各自成为一个段落（`li` 的内容策略是 FLOW，见 CSM 元素表）；
-    # 有块时在段落之后继续嵌套。省略 +marker+ 时沿用最近一层列表的标记形式。
-    def item(*parts, marker: nil, task: false, checked: nil, &block)
+    # 有块时在段落之后继续嵌套。省略 +marker+ 时沿用最近一层列表的标记形式；
+    # 省略 +task+ 时沿用最近一层列表的任务状态。
+    def item(*parts, marker: nil, task: nil, checked: nil, &block)
+      list = current_list
+      task = list.task? if task.nil? && list
+      task = false if task.nil?
+      list.attributes[:task] = true if task && list
+      checked = false if task && checked.nil?
+
       node = Node::ListItem.new(marker: marker || current_list_marker, task: task, checked: checked)
       append(node)
       fill_flow(node, parts, &block)
@@ -215,13 +231,15 @@ module MDOM
     end
 
     # 表头单元格（`th`）。+align+ 为 +:left+ / +:center+ / +:right+，省略为默认对齐。
-    def header_cell(text = "", align: nil)
-      append_cell(Node::TableHeaderCell, text, align)
+    # 内容策略是 PHRASING（CSM 元素表），因此正文与 #paragraph 一样可以给节点
+    # 参数或块——`cell` 从来不只是「一个字符串」。
+    def header_cell(*parts, align: nil, &block)
+      append_cell(Node::TableHeaderCell, parts, align, &block)
     end
 
     # 数据单元格（`td`）。+align+ 同上。
-    def cell(text = "", align: nil)
-      append_cell(Node::TableCell, text, align)
+    def cell(*parts, align: nil, &block)
+      append_cell(Node::TableCell, parts, align, &block)
     end
 
     # 分隔线。
@@ -266,6 +284,10 @@ module MDOM
     end
 
     # -- 行内 -----------------------------------------------------------------
+    #
+    # 每个 CSM 行内构造都有对应的构造方法。**结构化构造**是首选形式：内容给节点
+    # 参数或块，产物因此不依赖任何解析器；字符串参数是给手写用的便利形式，它需要
+    # 一个行内解析器（注入，或 `require "mdom/inline_parser"`）。
 
     # `*斜体*` → `<em>`。
     def em(*parts, &block)
@@ -283,17 +305,64 @@ module MDOM
       inline_node(Node::CodeSpan.new(value.to_s))
     end
 
+    # `~~文本~~` → `<del>`。
+    def del(*parts, &block)
+      inline_node(Node::Del.new, parts, &block)
+    end
+
+    # `~+文本+~` → `<ins>`。
+    def ins(*parts, &block)
+      inline_node(Node::Ins.new, parts, &block)
+    end
+
+    # 行内纯文本。参数按字面。
+    def text(value = "")
+      inline_node(Node::Text.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)
+    # `[文本](@uri)` → `<q>`。
+    def inline_quote(uri, *parts, &block)
+      inline_node(Node::InlineQuote.new(uri), parts, &block)
+    end
+
+    # `[[target|label]]` → `<a>`。+label+ 省略时显示 +target+，行内内容也因此取
+    # +target+（与解析侧一致）。
+    def wiki_link(target, label = nil, *parts, &block)
+      literal_inline(Node::WikiLink.new(target, label: label), parts, label || target, &block)
+    end
+
+    # `@user` / `@project:x` → `<a>`。+kind+ 是 `:` 前的作用域。
+    def mention(name, kind: nil)
+      inline_node(Node::Mention.new(name.to_s, kind: kind))
+    end
+
+    # `![alt](uri "title")` → `<img>`（空元素）。+alt+ 是替代文本原文，行内内容
+    # （含 `#{}`）由 +parts+ / 块给出；省略时按**字面**解析 +alt+（CSM §2.3）。
+    def image(uri, *parts, alt: nil, title: nil, &block)
       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)
+      literal_inline(Node::Image.new(uri, alt: alt, title: title), parts, alt, &block)
+    end
+
+    # `[=m/n]` → `<meter>`（CSM §1.10）。+value+ / +max+ 保持原文，行内内容省略时
+    # 按**字面**解析 `m/n`。
+    def meter(value, max, *parts, &block)
+      literal_inline(Node::Meter.new(value.to_s, max.to_s), parts, "#{value}/#{max}", &block)
+    end
+
+    # `[->m/n]` → `<progress>`。语义同 #meter。
+    def progress(value, max, *parts, &block)
+      literal_inline(Node::Progress.new(value.to_s, max.to_s), parts, "#{value}/#{max}", &block)
+    end
+
+    # `$\TeX$` → 行内 `<span class="math">`（CSM §1.11）。+tex+ 保持原文，行内内容
+    # 省略时按**字面**解析 +tex+。
+    def math(tex = "", *parts, &block)
+      literal_inline(Node::Math.new(tex.to_s), parts, tex.to_s, &block)
     end
 
     # 行尾 `\` → `<br>`。
@@ -301,6 +370,15 @@ module MDOM
       inline_node(Node::HardBreak.new)
     end
 
+    # `#{expr}`（CSM §3.13）。无块时构造**未求值**的插值节点，保存表达式原文
+    # （安全渲染用）；有块时块的值按 #render 的分派表插入当前位置（不安全渲染用，
+    # 此时表达式由 Ruby 求值）。
+    def interpolation(expr = nil, &block)
+      return render(block.call) if block
+
+      inline_node(Node::Interpolation.new(expr.to_s))
+    end
+
     # -- 注入通道 -------------------------------------------------------------
 
     # 嵌入代码进入文档树的唯一通道（CSM §3.3）：值挂在**当前容器**，插入位置就是
@@ -338,11 +416,11 @@ module MDOM
       fill_inline(source, [cite.to_s])
     end
 
-    # 单元格：正文按 CSM 行内语法解析（PHRASING）。
-    def append_cell(klass, text, align)
+    # 单元格：正文是行内内容（PHRASING），填充方式与段落一致。
+    def append_cell(klass, parts, align, &block)
       node = klass.new("", align: align)
       append(node)
-      fill_inline(node, [text.to_s])
+      fill_inline(node, parts, &block)
       self
     end
 
@@ -385,9 +463,14 @@ module MDOM
       node
     end
 
+    # 最近一层列表，没有则 +nil+。
+    def current_list
+      @stack.reverse.find { |node| node.is_a?(Node::List) }
+    end
+
     # 最近一层列表的标记形式（有序列表得到 `N.`），没有则 `-`。
     def current_list_marker
-      list = @stack.reverse.find { |node| node.is_a?(Node::List) }
+      list = current_list
       list ? list.attributes[:marker] : "-"
     end
 
@@ -403,17 +486,48 @@ module MDOM
       node
     end
 
-    # 填充行内内容：给块就用块（进入节点作为容器），否则解析 +parts+。
+    # 填充行内内容：给块就用块（进入节点作为容器），否则填充 +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)
+        within(node, &block)
+        return cache_text(node)
       end
 
       fill_inline_parts(node, parts)
     end
 
+    # 行内子节点挂好后，用（可注入的）序列化器重建 +attributes[:text]+ 原文缓存。
+    #
+    # 块形式的内容没有原文可存（内容本身就是节点），所以从子节点重建——`text` /
+    # `cite` 这类读取因此对 builder 构造的节点同样成立。只对 PHRASING 容器做：
+    # 行内格式节点（`em` / `strong` …）不需要原文缓存。
+    def cache_text(node)
+      return node unless PHRASING_CONTAINERS.include?(node.type)
+      return node unless node.attributes[:text].to_s.empty? # 解析期原文优先
+
+      serializer = text_serializer.new
+      node.attributes[:text] = node.children.map { |child| serializer.serialize(child) }.join
+      node
+    end
+
+    # 「字段 + 行内内容」型行内节点：内容给 +parts+ / 块，否则把 +literal+ 按字面
+    # 解析成子节点（与解析侧的策略一致）。
+    def literal_inline(node, parts, literal, &block)
+      append(node)
+      return fill_inline(node, parts, &block) if block || !parts.empty?
+
+      fill_inline(node, literal_nodes(literal)) if literal
+      node
+    end
+
+    # 一段原文的**字面**行内节点（只认 `#{}`，不认强调等；CSM §2.3 的字面策略）。
+    def literal_nodes(text)
+      inline_parser.parse(text.to_s, literal: true)
+    end
+
     # FLOW 容器的填充（CSM 元素表：`blockquote` / `li` / `dd` 的内容策略是 FLOW）：
     # +parts+ 各自成为一个段落，随后进入块（嵌套的块级子节点）。
     def fill_flow(node, parts, &block)
@@ -466,6 +580,12 @@ module MDOM
       raise ArgumentError,
             "render(parse: true) needs a parser: require \"mdom/parser\" or pass parser:"
     end
+
+    # 原文缓存（块形式的行内内容）用的序列化器：默认 +MDOM::MarkdownSerializer+。
+    # 它与本文件同属 builder 侧（零 gem 依赖），所以是唯一的直接依赖。
+    def text_serializer
+      @text_serializer ||= MarkdownSerializer
+    end
   end
 end
 
@@ -475,12 +595,16 @@ end
 # `Array`、`nil`……）。代价是给宿主的每个对象都加了 `render`——docs/IMPLEMENTATION.md
 # §5.2 已接受这一点，并说明为什么这是唯一可行的落点。
 class Object
-  # 把自身渲染进当前文档；没有正在渲染的文档时抛错。
-  def render(**options)
+  # 把值渲染进当前文档；没有正在渲染的文档时抛错。
+  #
+  # 两种写法走同一条路（CSM §3.3）：**给了位置参数就用它，否则用接收者本身**——
+  # 于是块内裸 `render(value)` 与 `值.render` 等价。`render(nil)` 仍然是「渲染 nil」
+  # （按 §3.3 的值分派表被忽略），多余的位置参数由 Ruby 自己报错。
+  def render(value = self, **options)
     builder = MDOM::Builder.current
     raise MDOM::Error, "render outside of a document" if builder.nil?
 
-    builder.render(self, **options)
+    builder.render(value, **options)
     self
   end
 end

data/lib/mdom/error.rb

@@ -15,8 +15,4 @@ module MDOM
 
   # 块级公式的 `$$` 包围式没有找到独占一行的结束标记（扫描到文档末尾）。
   class UnclosedMathError < ParseError; end
-
-  # 块里出现 heredoc。CSM §3.12 明确**不支持** heredoc（附录 E），一旦出现就报错，
-  # 而不是把它当普通块收下。
-  class UnsupportedHeredocError < ParseError; end
 end

data/lib/mdom/html_serializer.rb

@@ -123,7 +123,7 @@ module MDOM
       when :blockquote       then blockquote_html(node)
       when :code_block       then code_block_html(node)
       when :math_block       then tag("div", escape(node.tex, TEXT_ESCAPES), class: MATH_CLASS)
-      when :table            then element("table", children_html(node))
+      when :table            then table_html(node)
       when :table_row        then element("tr", children_html(node))
       when :table_header_cell then cell_html(node, "th")
       when :table_cell       then cell_html(node, "td")
@@ -178,6 +178,24 @@ module MDOM
       tag(name, inline_children(node), attrs)
     end
 
+    # 表格（CSM §1.12）：开头的连续表头行包进 `<thead>`，其余行包进 `<tbody>`。
+    #
+    # 分隔线可以把**相邻的任意一行**提升为表头（§1.12：`|1|2|` 也可以是标题），而
+    # HTML 只允许 `<thead>` 位于表格最前——所以出现在中途的表头行留在 `<tbody>` 里
+    # （仍输出 `<th>`），行顺序因此不被重排。零数据行时没有 `<tbody>`（与 GFM 一致）。
+    def table_html(node)
+      headers = node.children.take_while { |row| header_row?(row) }
+      bodies = node.children.drop(headers.size)
+      sections = []
+      sections << element("thead", block_statements(headers)) unless headers.empty?
+      sections << element("tbody", block_statements(bodies)) unless bodies.empty?
+      element("table", sections.join("\n"))
+    end
+
+    def header_row?(node)
+      node.type == :table_row && node.children.any? { |cell| cell.type == :table_header_cell }
+    end
+
     def list_html(node)
       attrs = {}
       attrs[:task] = "true" if node.task?