mdom 0.2.0 → 0.4.0

data/lib/mdom/markdown_serializer.rb

@@ -0,0 +1,390 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "node/inline_nodes"
+require_relative "node/nodes"
+
+module MDOM
+  # (3)/(5) AST → CSM 源（CSM §6；docs/IMPLEMENTATION.md §6）。
+  #
+  # 同一个方法服务两种输入状态：
+  #
+  # | 输入 | 嵌入节点 | 输出 | 保真 |
+  # |------|----------|------|------|
+  # | AST1 | 源码原文 | 原样回吐源码 | **保真往返** |
+  # | AST2 | 已被结果替换 | 只有结果 | **降级**（无法还原成 Ruby） |
+  #
+  #   MDOM::MarkdownSerializer.serialize(MDOM::Parser.parse("# 标题\n"))
+  #   # => "# 标题"
+  #
+  # 序列化**从节点结构重建**，不读 +attributes[:text]+ 那类原文缓存——树被改过之后
+  # 输出反映改动。唯一的例外是嵌入节点：它本来就承载 +source+ 原文，AST1 因此保真。
+  #
+  # == 缩进
+  #
+  # 输出统一用 4 个空格作 1 个缩进单位（CSM §1.1：1 个制表符或 4 个空格）。嵌入块
+  # 在 AST 里只存「已剥离块首缩进」的字符串（CSM §3.6），回吐时按**节点在树中的
+  # 深度**重新缩进——层级由树位置决定，不由字符串承载。
+  #
+  # == 转义
+  #
+  # 行内文本采取**保守转义**：凡是可能重新触发解析的字符（`\` `` ` `` `*` `~` `[`
+  # `]` `$`）以及插值起始的 `#{` 一律转义（CSM §3.11 的 `\` 规则）。代价是输出比
+  # 手写的 CSM 更谨慎，换来的是「不会被自己的内容重新解析」这一稳定性质。
+  #
+  # == 依赖边界
+  #
+  # 本文件属 **builder 侧**（docs/IMPLEMENTATION.md §1.1）：零 gem 依赖、不
+  # `require` prism、不使用正则字面量，因此 mruby / WASM 也能跑。
+  class MarkdownSerializer
+    # 一个缩进单位（CSM §1.1）。
+    INDENT = "    "
+
+    # 行内文本的单字符转义表（保守策略）。
+    TEXT_ESCAPES = {
+      "\\" => "\\\\",
+      "`" => "\\`",
+      "*" => "\\*",
+      "~" => "\\~",
+      "[" => "\\[",
+      "]" => "\\]",
+      "$" => "\\$",
+      "<" => "\\<",
+      "@" => "\\@",
+      "!" => "\\!"
+    }.freeze
+
+    # 出现在文本节点**开头**时可能开启块级构造的字符。行首 `\` 只跳过块级判定，
+    # 随后的 `\` 仍按行内转义处理，所以这里加一个 `\` 就能让整行保持为段落。
+    BLOCK_START_ESCAPES = ["#", ">", "-", ":", "|", "_", "(", "{", "%"].freeze
+
+    # 分隔线（CSM §1.6：3–72 个 `-`）。
+    HRULE = "---"
+
+    # 行内节点的类型名，用来区分 #serialize 收到的是一棵行内子树还是块。
+    INLINE_TYPES = %i[
+      text emphasis strong code_span link inline_quote image wiki_link mention
+      del ins hard_break meter progress math interpolation
+    ].freeze
+
+    def self.serialize(node)
+      new.serialize(node)
+    end
+
+    # 序列化一棵树（+Node::Document+ / 任意块级节点 / 任意行内节点），返回 CSM 源码。
+    # 块级输出**不带**末尾换行。
+    def serialize(node)
+      case node.type
+      when :document then blocks(node.children, 0).join("\n")
+      when *INLINE_TYPES then inline(node)
+      else block(node, 0).join("\n")
+      end
+    end
+
+    private
+
+    # -- 块级 -----------------------------------------------------------------
+
+    # 一串同级块，行数组。块之间空一行；**节块**（+Div+，CSM §1.1 的 `\n\n\n\n`）
+    # 与邻居之间空三行，这样往返时 +Div+ 还能重建出来。
+    def blocks(children, depth)
+      buffer = []
+      previous = nil
+      children.each do |child|
+        lines = block(child, depth)
+        next if lines.empty?
+
+        buffer.concat(gap_for(previous, child.type)) if previous
+        buffer.concat(lines)
+        previous = child.type
+      end
+      buffer
+    end
+
+    def gap_for(previous, current)
+      previous == :div || current == :div ? ["", "", ""] : [""]
+    end
+
+    # 单个块 → 行数组（每行已含 +depth+ 级缩进）。
+    def block(node, depth)
+      pad = INDENT * depth
+      case node.type
+      when :paragraph       then indented_text(pad, inline_children(node))
+      when :heading         then ["#{pad}#{heading_text(node)}"]
+      when :hrule           then ["#{pad}#{HRULE}"]
+      when :code_block      then code_block(node, pad)
+      when :math_block then math_block(node, pad)
+      when :list            then list(node, depth)
+      when :definition_list then definition_list(node, depth)
+      when :blockquote      then blockquote(node, depth)
+      when :table           then table(node, pad)
+      when :div             then blocks(node.children, depth)
+      when :ruby_embed      then embed(node, pad)
+      when :end_marker      then end_marker(node)
+      else indented_text(pad, inline_children(node))
+      end
+    end
+
+    # 段落内容可能因 #HardBreak 而断开，所以按行铺开。
+    def indented_text(pad, content)
+      "#{pad}#{content}".split("\n", -1)
+    end
+
+    def heading_text(node)
+      hashes = "#" * node.level.to_i
+      line = "#{hashes} #{inline_children(node)}"
+      node.closed? ? "#{line} #{hashes}" : line
+    end
+
+    def code_block(node, pad)
+      fence = "`" * (node.fence || 3).to_i
+      header = [node.lang, node.params].compact.reject(&:empty?).join(" ")
+      opening = header.empty? ? fence : "#{fence}#{header}"
+      body = node.code.to_s.split("\n", -1).map { |line| line.empty? ? "" : "#{pad}#{line}" }
+      ["#{pad}#{opening}", *body, "#{pad}#{fence}"]
+    end
+
+    # 块级公式：单行形式（`$$…$$`）能装下就用单行，否则退回 `$$` 独占一行的包围式。
+    def math_block(node, pad)
+      tex = node.tex.to_s
+      return ["#{pad}$$#{tex}$$"] unless tex.include?("\n")
+
+      ["#{pad}$$", *tex.split("\n", -1).map { |line| line.empty? ? "" : "#{pad}#{line}" }, "#{pad}$$"]
+    end
+
+    # -- 列表 -----------------------------------------------------------------
+
+    def list(node, depth)
+      node.children.flat_map.with_index do |item, index|
+        list_item(item, depth, marker_for(node, item, index))
+      end
+    end
+
+    def marker_for(list_node, item, index)
+      return "#{index + 1}. " if list_node.ordered?
+      return "- [#{item.checked ? "x" : " "}] " if list_node.task?
+
+      "#{item.marker || "-"} "
+    end
+
+    # 列表项的首个子块接在标记后面，其余子块整块缩进一级。
+    def list_item(item, depth, marker)
+      pad = INDENT * depth
+      body = item.children.flat_map { |child| block(child, depth + 1) }
+      return ["#{pad}#{marker.strip}"] if body.empty?
+
+      ["#{pad}#{marker}#{body.first.strip}", *body.drop(1)]
+    end
+
+    def definition_list(node, depth)
+      pad = INDENT * depth
+      node.children.flat_map do |child|
+        if child.type == :term
+          ["#{pad}#{inline_children(child)}"]
+        else
+          body = child.children.flat_map { |grandchild| block(grandchild, depth) }
+          first = body.first || ""
+          ["#{pad}: #{first.strip}", *body.drop(1)]
+        end
+      end
+    end
+
+    # -- 引用 -----------------------------------------------------------------
+
+    # 正文各行加 `> ` 前缀；最后一行以 `>-` 收尾时提取为 `cite`（CSM §1.4）。
+    def blockquote(node, depth)
+      pad = INDENT * depth
+      body = node.children.reject { |child| child.type == :cite }
+      quoted = body.flat_map { |child| block(child, depth) }.map { |line| quote(line, pad) }
+      cite = node.children.find { |child| child.type == :cite }
+      quoted << "#{pad}>- #{inline_children(cite)}" if cite
+      quoted
+    end
+
+    # 空行保留成 `>`，其余行剥掉公共缩进后加 `> `（不重复缩进）。
+    def quote(line, pad)
+      rest = line.start_with?(pad) ? line[pad.length..] : line
+      rest.empty? ? "#{pad}>" : "#{pad}> #{rest}"
+    end
+
+    # -- 表格 -----------------------------------------------------------------
+
+    def table(node, pad)
+      rows = node.children.reject { |row| row.children.empty? }
+      return [] if rows.empty?
+
+      lines = []
+      first = rows.first
+      # 没有表头但需要对齐时，用开头的分隔行表达（CSM §1.12）；它不产生行。
+      lines << separator_row(first, pad) if !header_row?(first) && first.children.any?(&:align)
+
+      rows.each do |row|
+        lines << table_row(row, pad)
+        # 分隔行既把前一行提升为表头，也设定它自己与后续行的对齐。每个表头行后面
+        # 都要跟一条，否则连续表头/中途表头会在往返时退化成数据行。
+        lines << separator_row(row, pad) if header_row?(row)
+      end
+      lines
+    end
+
+    def header_row?(row)
+      row.children.all? { |cell| cell.type == :table_header_cell }
+    end
+
+    def table_row(row, pad)
+      cells = row.children.map { |cell| " #{escape_table_pipes(inline_children(cell))} " }
+      "#{pad}|#{cells.join("|")}|"
+    end
+
+    # 表格在行内解析**之前**按未转义的 `|` 切格，因此单元格里的字面 `|` 必须
+    # 变成奇数个反斜杠 + `|`，切格器才会把它当内容而不是分隔符。
+    def escape_table_pipes(text)
+      out = +""
+      slashes = +""
+      text.each_char do |char|
+        if char == "\\"
+          slashes << char
+          next
+        end
+
+        out << slashes
+        out << "\\" if char == "|" && slashes.length.even?
+        slashes.clear
+        out << char
+      end
+      out << slashes unless slashes.empty?
+      out
+    end
+
+    def separator_row(row, pad)
+      cells = row.children.map { |cell| separator_cell(cell.align) }
+      "#{pad}|#{cells.join("|")}|"
+    end
+
+    def separator_cell(align)
+      case align
+      when :left then ":--"
+      when :right then "--:"
+      when :center then ":-:"
+      else "---"
+      end
+    end
+
+    # -- 嵌入与元数据 ---------------------------------------------------------
+
+    # 回吐嵌入源码（AST1 保真）；按节点深度重新缩进（CSM §3.6）。`~` 形式每行都
+    # 要重新加 `~ ` 前缀（CSM §3.4）。
+    def embed(node, pad)
+      lines = node.source.to_s.split("\n", -1)
+      return lines.map { |line| line.empty? ? "" : "#{pad}~ #{line}" } if node.form == :tilde
+
+      lines.map { |line| line.empty? ? "" : "#{pad}#{line}" }
+    end
+
+    def end_marker(node)
+      data = node.data.to_s
+      return ["__END__"] if data.empty?
+
+      ["__END__", *data.split("\n", -1)]
+    end
+
+    # -- 行内 -----------------------------------------------------------------
+
+    def inline_children(node)
+      node.children.map { |child| inline(child) }.join
+    end
+
+    def inline(node)
+      case node.type
+      when :text          then escape_text(node.text)
+      when :emphasis      then "*#{inline_children(node)}*"
+      when :strong        then "**#{inline_children(node)}**"
+      when :code_span     then code_span(node)
+      when :link          then "[#{inline_children(node)}](#{node.uri}#{title_suffix(node.title)})"
+      when :inline_quote  then "[#{inline_children(node)}](@#{node.uri})"
+      when :image         then "![#{node.alt}](#{node.uri}#{title_suffix(node.title)})"
+      when :wiki_link     then wiki_link(node)
+      when :mention       then mention(node)
+      when :del           then "~~#{inline_children(node)}~~"
+      when :ins           then "~+#{inline_children(node)}+~"
+      when :hard_break    then "\\\n"
+      when :meter         then "[=#{node.value}/#{node.max}]"
+      when :progress      then "[->#{node.value}/#{node.max}]"
+      when :math          then "$#{node.tex}$"
+      when :interpolation then "\#{#{node.expr}}"
+      else ""
+      end
+    end
+
+    def code_span(node)
+      code = node.code.to_s
+      fence = code.include?("`") ? "``" : "`"
+      "#{fence}#{code}#{fence}"
+    end
+
+    def wiki_link(node)
+      label = node.label
+      return "[[#{node.target}]]" if label.nil? || label.to_s.empty?
+
+      "[[#{node.target}|#{label}]]"
+    end
+
+    def mention(node)
+      kind = node.kind
+      kind.nil? || kind.to_s.empty? ? "@#{node.name}" : "@#{kind}:#{node.name}"
+    end
+
+    # `[文本](uri "title")` 的可选 title 部分。
+    def title_suffix(title)
+      title.nil? || title.to_s.empty? ? "" : " \"#{title}\""
+    end
+
+    # 保守转义：单字符查表 + `#{` 的起始 `#`（CSM §3.11、§3.13）。
+    #
+    # 文本节点可能正好落在输出行的开头（段落第一段，或硬换行之后）。这时再补一个
+    # 行首 `\`，避免 `#` / `>` / `-` / `:` / `|` / `__END__` 被重新识别为块级构造。
+    # 行首 `\` 不参与块级判定，但仍按行内转义处理，所以不会污染文本内容。
+    def escape_text(text)
+      source = text.to_s
+      characters = source.chars
+      ordered_dot = ordered_list_dot_index(characters)
+      out = +""
+
+      characters.each_with_index do |char, index|
+        if char == "#" && characters[index + 1] == "{"
+          out << "\\#"
+        else
+          out << "\\" if index.zero? && block_start?(char)
+          out << (index == ordered_dot ? "\\." : (TEXT_ESCAPES[char] || char))
+        end
+      end
+      out
+    end
+
+    def block_start?(char)
+      BLOCK_START_ESCAPES.include?(char)
+    end
+
+    # 行首的 `N.` 会被识别为有序列表；反斜杠不能转义数字，改为转义那个点。
+    def ordered_list_dot_index(characters)
+      cursor = 0
+      cursor += 1 while cursor < characters.length && cursor < 9 &&
+                        characters[cursor] >= "0" && characters[cursor] <= "9"
+
+      return cursor if cursor.positive? && characters[cursor] == "."
+
+      nil
+    end
+  end
+end
+
+module MDOM
+  module Node
+    # 便捷入口：+node.to_markdown+ ≡ +MDOM::MarkdownSerializer.serialize(node)+。
+    class BaseNode
+      def to_markdown
+        MarkdownSerializer.serialize(self)
+      end
+    end
+  end
+end

data/lib/mdom/node/inline_nodes.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require_relative "../node"
+
+# 行内节点：由 +InlineParser+ 从一段行内文本产出，只出现在行内容器
+# （段落、标题、列表项、引用、定义……）的 +children+ 里。
+#
+# 与块级节点一样，每个类只固定自己的 +type+ 与语义属性。产出的是**未求值**的
+# 节点：`#{}` 只保存表达式原文，公式只保存 TeX 原文。
+module MDOM
+  module Node
+    # 行内节点的标记模块，便于与块级节点区分。
+    module Inline; end
+
+    # 行内纯文本。
+    class Text < BaseNode
+      include Inline
+
+      def initialize(text = "", attributes: {}, children: [])
+        super(:text, attributes: { text: text }.merge(attributes), children: children)
+      end
+
+      def text
+        attributes[:text]
+      end
+
+      def text=(value)
+        attributes[:text] = value
+      end
+    end
+
+    # `*文本*` → `<em>`。
+    class Emphasis < BaseNode
+      include Inline
+
+      def initialize(children: [], attributes: {})
+        super(:emphasis, attributes: attributes, children: children)
+      end
+    end
+
+    # `**文本**` → `<strong>`。
+    class Strong < BaseNode
+      include Inline
+
+      def initialize(children: [], attributes: {})
+        super(:strong, attributes: attributes, children: children)
+      end
+    end
+
+    # `` `代码` `` → `<code>`。内容按字面处理，不再解析。
+    class CodeSpan < BaseNode
+      include Inline
+
+      def initialize(code = "", attributes: {}, children: [])
+        super(:code_span, attributes: { code: code }.merge(attributes), children: children)
+      end
+
+      def code
+        attributes[:code]
+      end
+    end
+
+    # `[文本](uri "title")`、`<uri>` → `<a>`。
+    class Link < BaseNode
+      include Inline
+
+      def initialize(uri, title: nil, children: [], attributes: {})
+        super(:link, attributes: { uri: uri, title: title }.merge(attributes), children: children)
+      end
+
+      def uri
+        attributes[:uri]
+      end
+
+      def title
+        attributes[:title]
+      end
+    end
+
+    # `[文本](@uri)` → `<q cite="uri">`。
+    class InlineQuote < BaseNode
+      include Inline
+
+      def initialize(uri, children: [], attributes: {})
+        super(:inline_quote, attributes: { uri: uri }.merge(attributes), children: children)
+      end
+
+      def uri
+        attributes[:uri]
+      end
+    end
+
+    # `![alt](uri "title")` → `<img>`（空元素）。+alt+ 保持原文，+children+ 是它
+    # 解析出的行内节点（含 `#{}` 插值）——`<img>` 没有子内容，这里只承载替代文本。
+    class Image < BaseNode
+      include Inline
+
+      def initialize(uri, alt: "", title: nil, children: [], attributes: {})
+        super(:image, attributes: { uri: uri, alt: alt, title: title }.merge(attributes), children: children)
+      end
+
+      def uri
+        attributes[:uri]
+      end
+
+      def alt
+        attributes[:alt]
+      end
+
+      def title
+        attributes[:title]
+      end
+    end
+
+    # `[[target|label]]` → `<a>`。+label+ 省略时用 +target+ 作显示文本。
+    # +children+ 是显示文本解析出的行内节点（含 `#{}` 插值）。
+    class WikiLink < BaseNode
+      include Inline
+
+      def initialize(target, label: nil, children: [], attributes: {})
+        super(:wiki_link, attributes: { target: target, label: label }.merge(attributes), children: children)
+      end
+
+      def target
+        attributes[:target]
+      end
+
+      def label
+        attributes[:label]
+      end
+    end
+
+    # `@user` / `@project:x` / `@tag:kw` → `<a>`。+kind+ 是 `:` 前的作用域。
+    class Mention < BaseNode
+      include Inline
+
+      def initialize(name, kind: nil, attributes: {})
+        super(:mention, attributes: { name: name, kind: kind }.merge(attributes))
+      end
+
+      def name
+        attributes[:name]
+      end
+
+      def kind
+        attributes[:kind]
+      end
+    end
+
+    # `~~文本~~` → `<del>`。
+    class Del < BaseNode
+      include Inline
+
+      def initialize(children: [], attributes: {})
+        super(:del, attributes: attributes, children: children)
+      end
+    end
+
+    # `~+文本+~` → `<ins>`。
+    class Ins < BaseNode
+      include Inline
+
+      def initialize(children: [], attributes: {})
+        super(:ins, attributes: attributes, children: children)
+      end
+    end
+
+    # 行尾 `\` → `<br>`（空元素）。
+    class HardBreak < BaseNode
+      include Inline
+
+      def initialize(attributes: {})
+        super(:hard_break, attributes: attributes)
+      end
+    end
+
+    # `[=m/n]` → `<meter value="m" max="n">`（空元素）。+value+ / +max+ 保持原文，
+    # +children+ 是 `m/n` 解析出的行内节点（含 `#{}` 插值）。
+    class Meter < BaseNode
+      include Inline
+
+      def initialize(value, max, children: [], attributes: {})
+        super(:meter, attributes: { value: value, max: max }.merge(attributes), children: children)
+      end
+
+      def value
+        attributes[:value]
+      end
+
+      def max
+        attributes[:max]
+      end
+    end
+
+    # `[->m/n]` → `<progress value="m" max="n">`（空元素）。语义同 +Meter+。
+    class Progress < BaseNode
+      include Inline
+
+      def initialize(value, max, children: [], attributes: {})
+        super(:progress, attributes: { value: value, max: max }.merge(attributes), children: children)
+      end
+
+      def value
+        attributes[:value]
+      end
+
+      def max
+        attributes[:max]
+      end
+    end
+
+    # `$\TeX$` → 行内 `<span class="math">`（TeX 原文，不渲染成 SVG）。+tex+ 保持
+    # 原文，+children+ 是 TeX 解析出的行内节点（含 `#{}` 插值）。
+    class Math < BaseNode
+      include Inline
+
+      def initialize(tex = "", children: [], attributes: {})
+        super(:math, attributes: { tex: tex }.merge(attributes), children: children)
+      end
+
+      def tex
+        attributes[:tex]
+      end
+    end
+
+    # `#{expr}`：交给 Ruby 求值，此处只保存表达式原文、不求值。
+    class Interpolation < BaseNode
+      include Inline
+
+      def initialize(expr = "", attributes: {}, children: [])
+        super(:interpolation, attributes: { expr: expr }.merge(attributes), children: children)
+      end
+
+      def expr
+        attributes[:expr]
+      end
+    end
+  end
+end