mdom 0.2.0 → 0.3.0

data/lib/mdom/translator.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "node/inline_nodes"
+require_relative "node/nodes"
+
+module MDOM
+  # (2) AST1 → Ruby 源码（CSM §3.1；docs/IMPLEMENTATION.md §3）。
+  #
+  # 把一棵 AST1 翻译成**一段顶层顺序执行的 Ruby 程序**：排版节点变成 builder
+  # 调用，嵌入节点（RubyEmbed / 行内插值）原样注入。产出的只是源码字符串，不
+  # 绑定任何执行方式（docs/IMPLEMENTATION.md §6.2）——`eval`、落盘后 `require`、
+  # 交给 mruby 都可以。
+  #
+  #   MDOM::Translator.to_ruby(MDOM::Parser.parse("# 标题\n"))
+  #   # => "builder = MDOM::Builder.new\nbuilder.heading(1, \"标题\")\nbuilder.to_document"
+  #
+  # 两侧的结构约束（docs/IMPLEMENTATION.md §6.3）：排版段一律经由 +builder.*+
+  # 接收者，形式可辨识；嵌入段保持原样，边界明确（Ruby 块原文 / 字符串字面量里的
+  # `#{}`）。这样宿主才有可能判断一段产物是否能在 mruby 上跑。
+  #
+  # == 安全闸门（CSM §3.14）
+  #
+  # +unsafe+ 是**翻译期**参数，默认 +false+（安全）：嵌入节点不写进产物，所以
+  # 产物静态上不含用户代码——块级 `RubyEmbed` 只留一行注释占位，行内插值退化为
+  # 字面 `#{expr}`。+unsafe: true+ 才把嵌入原样注入。
+  #
+  # 安全模式下宿主不需要（也不应该）拿产物去 `eval`：未求值的嵌入由 (6) 直接吃
+  # AST1 就能按独立样式输出。求值本身只是宿主的一行 `eval`，mdom 不含求值器。
+  #
+  # 本类**不依赖 prism**：行内边界已由 InlineParser 判好，这里只做序列化。它只
+  # +require+ 节点定义（builder 侧）。
+  #
+  # == 行内内容为什么重新生成标记
+  #
+  # 行内容器（段落、标题……）在产物里以**字符串参数**交给 builder，而 builder
+  # 会用 InlineParser 重新解析这些字符串。因此本类要把 AST1 的行内子树重新序列化
+  # 成 CSM 标记文本（`**粗**`、`[标签](uri)`……）。
+  #
+  # 插值单独处理：+unsafe: true+ 时 `#{}` 在产物里是**真正的 Ruby 插值**（CSM §3.13），
+  # 由 Ruby 求值；安全模式与字面 `#{` 都写成字面。字面 `#{` 会被转义成 `\#{`。两者在 AST1 里已经分开——真插值是
+  # +Node::Interpolation+，字面的 `#{` 落在 +Node::Text+ 里——所以边界不必再扫描
+  # （CSM §3.12：配对与屏蔽交给 prism）。
+  #
+  # == 两个转义层
+  #
+  # 产物里的纯文本要过两层转义，顺序不能颠倒：
+  #
+  # 1. #escape_markup：让 InlineParser 把纯文本当**字面**（`*星*` 必须写成
+  #    `\*星\*`，否则重新解析会得到紧强调）；
+  # 2. #escape_ruby：把该文本编码进 Ruby 双引号字面量（`\` → `\\`、`"` → `\"`、
+  #    `#` → `\#` 以免与插值混淆）。
+  #
+  # 已由节点结构提供的标记（`**`、`[`……）只过第 2 层。
+  class Translator
+    # 会被 InlineParser 当作语法开启的字符（CSM §1.5–§1.11、§2、§3.13）。纯文本
+    # 里出现它们时必须转义；`/`、`:`、`-` 等只在特定上下文里才有意义，不在表内。
+    MARKUP_CHARS = ["\\", "`", "*", "~", "[", "]", "!", "<", "$", "#", "@"].freeze
+
+    # Ruby 双引号字面量的转义表。`#` 也转义，避免 `\#{` 里的 `#` 与随后的 `{`
+    # 被 Ruby 重新拼成插值。
+    RUBY_ESCAPES = { "\\" => "\\\\", "\"" => "\\\"", "#" => "\\#", "\n" => "\\n", "\t" => "\\t" }.freeze
+
+    # 行内代码的定界符上限（CSM §1.5：最多 2 个反引号）。
+    MAX_CODE_TICKS = 2
+
+    # 没有行内内容时传给 builder 的空字符串参数。
+    EMPTY_ARGUMENT = '""'
+
+    # 安全模式下块级嵌入的占位注释（CSM §3.14）。
+    EMBED_PLACEHOLDER = "# [csm] ruby 嵌入已省略（unsafe: false）"
+
+    def self.to_ruby(node, **options)
+      new(**options).to_ruby(node)
+    end
+
+    # +indent+ 是产物每层嵌套的缩进宽度；+builder+ 是产物里 builder 变量的名字。
+    # +unsafe+ 为 +false+（默认）时嵌入节点不写进产物（CSM §3.14）。
+    def initialize(indent: 2, builder: "builder", unsafe: false)
+      @indent = " " * indent
+      @builder = builder
+      @unsafe = unsafe
+    end
+
+    # 翻译一棵树（+Node::Document+ 或任意子节点），返回 Ruby 源码字符串。
+    #
+    # 第一个 `__END__` 必须排在 `to_document` **之后**：Ruby 的 `__END__` 会截断
+    # 其后的程序文本，排在它后面的语句不会执行（CSM §3.1、§4）。
+    def to_ruby(node)
+      parts = [assignment] + statements(node, 0) + [finish]
+      marker = end_marker_of(node)
+      parts.concat(end_marker_statement(marker)) if marker
+      parts.join("\n")
+    end
+
+    private
+
+    def assignment = "#{@builder} = MDOM::Builder.new"
+
+    def finish = "#{@builder}.to_document"
+
+    def children_of(node)
+      node.type == :document ? node.children : [node]
+    end
+
+    def end_marker_of(node)
+      children_of(node).find { |child| child.type == :end_marker }
+    end
+
+    # -- 骨架 -----------------------------------------------------------------
+
+    def statements(node, depth)
+      children_of(node).reject { |child| child.type == :end_marker }
+                       .flat_map { |child| statement(child, depth) }
+    end
+
+    def line(depth, text) = (@indent * depth) + text
+
+    # 逐节点分派。返回语句行数组（已含缩进）。
+    def statement(node, depth)
+      case node.type
+      when :heading         then [line(depth, heading_call(node))]
+      when :paragraph       then [line(depth, paragraph_call(node))]
+      when :hrule           then [line(depth, "#{@builder}.hrule")]
+      when :code_block      then [line(depth, code_block_call(node))]
+      when :math_block      then [line(depth, math_block_call(node))]
+      when :table           then block_statement(node, depth, "#{@builder}.table")
+      when :table_row       then block_statement(node, depth, "#{@builder}.row")
+      when :table_header_cell then [line(depth, cell_call(node, "header_cell"))]
+      when :table_cell      then [line(depth, cell_call(node, "cell"))]
+      when :term            then [line(depth, term_call(node))]
+      when :cite            then [line(depth, cite_call(node))]
+      when :definition      then block_statement(node, depth, "#{@builder}.definition")
+      when :list_item       then block_statement(node, depth, item_head(node))
+      when :blockquote      then block_statement(node, depth, "#{@builder}.blockquote")
+      when :list            then block_statement(node, depth, list_head(node))
+      when :definition_list then block_statement(node, depth, "#{@builder}.definition_list")
+      when :div             then block_statement(node, depth, "#{@builder}.division")
+      when :ruby_embed      then ruby_embed_statement(node, depth)
+      when :end_marker      then end_marker_statement(node)
+      else raise Error, "cannot translate #{node.type.inspect} to Ruby"
+      end
+    end
+
+    # 块级调用：无子节点时退化为单行，有子节点时用 `do ... end` 包住。
+    # 内容策略为 FLOW 的容器只收块级子节点（CSM 元素表），这里原样递归它们。
+    def block_statement(node, depth, head)
+      body = node.children.flat_map { |child| statement(child, depth + 1) }
+      return [line(depth, head)] if body.empty?
+
+      [line(depth, "#{head} do"), *body, line(depth, "end")]
+    end
+
+    # -- 块级节点 -------------------------------------------------------------
+
+    def heading_call(node)
+      args = [node.level.to_s]
+      argument = inline_argument(node)
+      args << argument if argument
+      args << "closed: true" if node.closed?
+      call(@builder, "heading", args)
+    end
+
+    # 引用来源（`>-`，PHRASING）。现在它是 Blockquote 的普通子节点。
+    def cite_call(node)
+      "#{@builder}.cite(#{inline_argument(node) || EMPTY_ARGUMENT})"
+    end
+
+    def paragraph_call(node)
+      "#{@builder}.paragraph(#{inline_argument(node) || EMPTY_ARGUMENT})"
+    end
+
+    def term_call(node)
+      "#{@builder}.term(#{inline_argument(node) || EMPTY_ARGUMENT})"
+    end
+
+    def item_head(node)
+      call(@builder, "item", item_arguments(node))
+    end
+
+    def item_arguments(node)
+      args = ["marker: #{ruby_literal(node.marker)}"]
+      args << "task: true" if node.task?
+      args << "checked: #{node.checked.inspect}" unless node.checked.nil?
+      args
+    end
+
+    def list_head(node)
+      args = [
+        "ordered: #{node.ordered?}",
+        "task: #{node.task?}",
+        "marker: #{ruby_literal(node.attributes[:marker])}"
+      ]
+      call(@builder, "list", args)
+    end
+
+    def code_block_call(node)
+      args = [ruby_literal(node.code)]
+      args << "lang: #{ruby_literal(node.lang)}" if node.lang
+      args << "params: #{ruby_literal(node.params)}" if node.params
+      fence = node.attributes[:fence]
+      args << "fence: #{fence}" unless fence.nil? || fence == 3
+      call(@builder, "code_block", args)
+    end
+
+    # 块级公式：+tex+ 按字面（CSM §1.11）。
+    def math_block_call(node)
+      "#{@builder}.math_block(#{ruby_literal(node.tex)})"
+    end
+
+    # 表格单元格：正文（PHRASING）作字符串参数，+align+ 按需带上。
+    def cell_call(node, name)
+      args = [inline_argument(node) || EMPTY_ARGUMENT]
+      args << "align: #{node.align.inspect}" if node.align
+      call(@builder, name, args)
+    end
+
+    def call(receiver, name, args)
+      args.empty? ? "#{receiver}.#{name}" : "#{receiver}.#{name}(#{args.join(", ")})"
+    end
+
+    # Ruby 嵌入块：源码原文（已剥离 N 层 CSM 缩进）按所在层级重新缩进后原样注入
+    # （CSM §3.6）。`begin`/`end` 标志与 `.render` 收尾都在原文里，不再改动。
+    # 安全模式下不写源码，只留一行注释占位（CSM §3.14）。
+    def ruby_embed_statement(node, depth)
+      return [line(depth, EMBED_PLACEHOLDER)] unless @unsafe
+
+      prefix = @indent * depth
+      node.source.split("\n", -1).map { |text| text.empty? ? text : prefix + text }
+    end
+
+    # 第一个 `__END__` 原样写入，其后内容交给 Ruby 的 `DATA`（CSM §4）。
+    def end_marker_statement(node)
+      data = node.attributes[:data]
+      return ["__END__"] if data.nil? || data.empty?
+
+      ["__END__", *data.split("\n", -1)]
+    end
+
+    # -- 行内内容 -------------------------------------------------------------
+
+    def inline?(node) = node.is_a?(Node::Inline)
+
+    def inline_nodes(node)
+      node.children.select { |child| inline?(child) }
+    end
+
+    # 行内内容的 Ruby 字符串字面量；没有行内内容时返回 +nil+。
+    #
+    # 兜底：以 +inline: false+ 解析出的 AST 没有行内节点，此时原文本身就是 CSM
+    # 源码，直接交给 builder 重新解析。
+    def inline_argument(node)
+      nodes = inline_nodes(node)
+      return "\"#{inline_fragments(nodes)}\"" unless nodes.empty?
+
+      text = node.attributes[:text].to_s
+      return nil if text.empty?
+
+      "\"#{escape_ruby(text)}\""
+    end
+
+    # 行内节点序列化：返回**Ruby 字面量体**（已转义，插值保持为裸 `#{}`）。
+    #
+    # 标记（`**`、`[`……）由节点结构给出，只过 Ruby 转义；纯文本额外过一层 CSM
+    # 转义，让 InlineParser 重新解析时把它当字面。
+    def inline_fragments(nodes)
+      nodes.map { |node| inline_fragment(node) }.join
+    end
+
+    def inline_fragment(node)
+      case node.type
+      when :text          then escape_ruby(escape_markup(node.text))
+      when :interpolation then interpolation_fragment(node)
+      when :emphasis      then wrap_markup(node, "*")
+      when :strong        then wrap_markup(node, "**")
+      when :del           then wrap_markup(node, "~~")
+      when :ins           then wrap_markup(node, "~+", "+~")
+      when :code_span     then code_span_fragment(node.code)
+      when :link          then link_fragment(node, "")
+      when :image         then link_fragment(node, "!")
+      when :inline_quote  then inline_quote_fragment(node)
+      when :wiki_link     then wiki_link_fragment(node)
+      when :mention       then mention_fragment(node)
+      when :meter         then bar_fragment(node, "[=")
+      when :progress      then bar_fragment(node, "[->")
+      when :math          then wrap_markup(node, "$")
+      when :hard_break    then escape_ruby("\\\n")
+      else raise Error, "cannot translate inline #{node.type.inspect} to Ruby"
+      end
+    end
+
+    # 插值：不安全时是真正的 Ruby 插值（交 Ruby 求值）；安全时退化为**字面**
+    # `#{expr}`——求值后它落回 CSM 源码，由 builder 重新解析成未求值的
+    # Interpolation 节点，供 (6) 按独立样式输出（CSM §3.14）。
+    def interpolation_fragment(node)
+      literal = "\#{#{node.expr}}"
+      @unsafe ? literal : escape_ruby(literal)
+    end
+
+    def wrap_markup(node, opener, closer = opener)
+      "#{escape_ruby(opener)}#{inline_fragments(node.children)}#{escape_ruby(closer)}"
+    end
+
+    # `[标签](uri "title")` / `![alt](uri "title")`。
+    def link_fragment(node, sigil)
+      label = escape_ruby("#{sigil}[")
+      body = inline_fragments(node.children)
+      target = escape_ruby("](#{destination(node)})")
+      "#{label}#{body}#{target}"
+    end
+
+    # `[文本](@uri)` → `<q cite="uri">`。
+    def inline_quote_fragment(node)
+      label = escape_ruby("[")
+      body = inline_fragments(node.children)
+      target = escape_ruby("](@#{node.uri})")
+      "#{label}#{body}#{target}"
+    end
+
+    # `[[target|label]]`；省略 label 时用 +[[target]]+。
+    def wiki_link_fragment(node)
+      target = node.attributes[:target]
+      return escape_ruby("[[#{target}]]") if node.attributes[:label].nil?
+
+      "#{escape_ruby("[[#{target}|")}#{inline_fragments(node.children)}#{escape_ruby("]]")}"
+    end
+
+    def mention_fragment(node)
+      scope = node.attributes[:kind]
+      escape_ruby("@#{scope ? "#{scope}:" : ""}#{node.attributes[:name]}")
+    end
+
+    def bar_fragment(node, opener)
+      "#{escape_ruby(opener)}#{inline_fragments(node.children)}#{escape_ruby("]")}"
+    end
+
+    # 链接/图片的目的地（`uri "title"`）。uri 与 title 是字面，不做 CSM 转义。
+    def destination(node)
+      title = node.attributes[:title]
+      title ? "#{node.uri} \"#{title}\"" : node.uri.to_s
+    end
+
+    # 行内代码：反引号数量要与内容里的反引号错开（CSM §1.5），内容按字面。
+    def code_span_fragment(code)
+      ticks = "`" * (code.include?("`") ? MAX_CODE_TICKS : 1)
+      escape_ruby("#{ticks}#{code}#{ticks}")
+    end
+
+    # -- 转义 -----------------------------------------------------------------
+
+    # 第 1 层：纯文本 → 其 CSM 源码形式（给每个标记字符加 `\`）。
+    def escape_markup(text)
+      text.each_char.map { |char| MARKUP_CHARS.include?(char) ? "\\#{char}" : char }.join
+    end
+
+    # 第 2 层：CSM 源码 → Ruby 双引号字面量的体。
+    def escape_ruby(text)
+      text.each_char.map { |char| RUBY_ESCAPES.fetch(char, char) }.join
+    end
+
+    # 值 → Ruby 字面量（含引号）。
+    def ruby_literal(value)
+      return "nil" if value.nil?
+
+      "\"#{escape_ruby(value.to_s)}\""
+    end
+  end
+end
+
+module MDOM
+  module Node
+    # 便捷入口：+node.to_ruby(**options)+ ≡ +MDOM::Translator.to_ruby(node, **options)+。
+    class BaseNode
+      def to_ruby(**options)
+        Translator.to_ruby(self, **options)
+      end
+    end
+  end
+end

data/lib/mdom/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MDOM
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/mdom.rb

@@ -1,16 +1,67 @@
 # frozen_string_literal: true
 
+require_relative "mdom/error"
 require_relative "mdom/version"
-require_relative "mdom/node"
-require_relative "mdom/nodes"
+require_relative "mdom/hooks"
 require_relative "mdom/parser"
-require_relative "mdom/inline_parser"
-require_relative "mdom/serializer"
+require_relative "mdom/translator"
 require_relative "mdom/builder"
+require_relative "mdom/html_serializer"
+require_relative "mdom/markdown_serializer"
 
+# CSM（Complex Simple Markup）的 Ruby 工具链。
+#
+# `require "mdom"` 是**总入口**，会把两侧都加载进来（解析侧需要 `prism`）。只想在
+# mruby/WASM 上构造文档时，直接 `require "mdom/builder"` 即可——那一侧零 gem 依赖。
+#
+# 六个转换关系见 `docs/CSM.md` §6；这里接的是其中已经实现的四段：
+# (1) 解析、(2) 翻译、(3)(5) `to_markdown`、(6) HTML 序列化。(4) 执行不在 mdom
+# 范围内——它就是宿主的一行 `eval`。
 module MDOM
-  # Serialize a node (or subtree) back to a Markdown string.
-  def self.serialize(node)
-    Serializer.serialize(node)
+  # 一次 #compile 的结果。
+  #
+  # 三个阶段的产物都在这里；钩子改写过的版本就是这里看到的版本。
+  Compiled = Struct.new(:document, :ruby, :html, :meta, keyword_init: true)
+
+  # (1)：CSM 源码 → AST1。等价于 +MDOM::Parser.parse+。
+  def self.parse(source, **options)
+    Parser.parse(source, **options)
+  end
+
+  # (1)(2)(6) 全链路，并在五个点上触发钩子（CSM §5.3）。
+  #
+  # 顺序：
+  #
+  # 1. `Parser.parse` → 触发 `:after_parse(doc)`
+  # 2. 触发 **`:before_compile(doc)`** —— 此时树仍可改写，程序化生成目录就放这里
+  # 3. `Translator.to_ruby` → 触发 `:after_compile(doc, ruby)`
+  # 4. 触发 `:before_serialize(doc)`
+  # 5. `HtmlSerializer.serialize` → 触发 `:after_serialize(html, meta)`
+  #
+  # 参数：
+  # * +hooks:+ —— 本次调用专用的临时钩子，形如 +{ before_compile: [proc] }+；
+  #   与类级注册表里的钩子一起执行，顺序是「全局 → 临时」；
+  # * +parser:+ / +translator:+ / +serializer:+ —— 分别透传给三个阶段。
+  #
+  # 返回值：+MDOM::Compiled+（含 +document+ / +ruby+ / +html+ / +meta+）。
+  def self.compile(source, hooks: {}, parser: {}, translator: {}, serializer: {})
+    document = Parser.parse(source, **parser)
+    run_hooks(:after_parse, hooks, document)
+
+    run_hooks(:before_compile, hooks, document)
+    ruby = Translator.to_ruby(document, **translator)
+    run_hooks(:after_compile, hooks, document, ruby)
+
+    run_hooks(:before_serialize, hooks, document)
+    html = HtmlSerializer.serialize(document, **serializer)
+    run_hooks(:after_serialize, hooks, html, document.meta)
+
+    Compiled.new(document: document, ruby: ruby, html: html, meta: document.meta)
+  end
+
+  # 触发一个钩子点：先全局注册表，再本次调用传入的临时钩子。
+  def self.run_hooks(point, hooks, *args)
+    Hooks.run(point, *args, extra: hooks.fetch(point, []))
   end
+  private_class_method :run_hooks
 end

metadata

@@ -1,27 +1,60 @@
 --- !ruby/object:Gem::Specification
 name: mdom
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - mdom
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: MDOM parses Markdown into a node tree (block + inline), supports traversal,
-  querying and mutation, and serializes back to a Markdown string.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'MDOM parses CSM documents into a document tree (AST) and translates
+  it to Ruby source (safe by default: no embedded code is emitted) or to HTML. Markdown
+  is treated as syntactic sugar for Ruby, so a `.rb.md` document is both readable
+  Markdown and an executable Ruby program.'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- USAGE.md
 - lib/mdom.rb
+- lib/mdom/block_detector.rb
 - lib/mdom/builder.rb
+- lib/mdom/error.rb
+- lib/mdom/hooks.rb
+- lib/mdom/html_serializer.rb
 - lib/mdom/inline_parser.rb
+- lib/mdom/markdown_serializer.rb
 - lib/mdom/node.rb
-- lib/mdom/nodes.rb
+- lib/mdom/node/inline_nodes.rb
+- lib/mdom/node/nodes.rb
 - lib/mdom/parser.rb
-- lib/mdom/serializer.rb
+- lib/mdom/tokenizer.rb
+- lib/mdom/translator.rb
 - lib/mdom/version.rb
 licenses:
 - MIT
@@ -43,5 +76,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: 'A Markdown DOM: a self-contained AST for Markdown.'
+summary: CSM (Complex Simple Markup) toolchain for Ruby.
 test_files: []