mdom 0.2.0 → 0.4.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
+  # 调用，嵌入节点（块级嵌入 / 行内插值）按 +unsafe+ 决定是否原样注入。产出的
+  # 只是源码字符串，不绑定任何执行方式（docs/IMPLEMENTATION.md §6.2）——`eval`、
+  # 落盘后 `require`、交给 mruby 都可以。
+  #
+  #   puts MDOM::Translator.to_ruby(MDOM::Parser.parse("# 标题\n"))
+  #   # builder = MDOM::Builder.new
+  #   # builder.heading(1) do
+  #   #   builder.text("标题")
+  #   # end
+  #   # builder.to_document
+  #
+  # 两侧的结构约束（docs/IMPLEMENTATION.md §6.3）：排版段一律经由 +builder.*+
+  # 接收者，形式可辨识；嵌入段保持原样，边界明确（Ruby 块原文 / `interpolation`
+  # 的块）。这样宿主才有可能判断一段产物是否能在 mruby 上跑。
+  #
+  # == 行内内容结构化，不回吐标记
+  #
+  # 行内容器（段落、标题、单元格……）在产物里是**块形式**的 builder 调用，每个
+  # 行内子节点翻译成对应的 builder 行内方法：
+  #
+  #   builder.paragraph do
+  #     builder.text("正文 ")
+  #     builder.strong do
+  #       builder.text("粗")
+  #     end
+  #   end
+  #
+  # 产物因此**不经过 InlineParser**：翻译器不输出 CSM 标记文本，也就没有「产物
+  # 执行时再解析一次」这一步，排版段真正落在 mruby 子集里（CSM §3.1）。唯一仍
+  # 需要行内解析器的形态是 +inline: false+ 解析出的 AST——那时树里只有原文、没有
+  # 行内节点（见 #inline_block_statement）。
+  #
+  # == 插值
+  #
+  # +unsafe: true+ 时插值是 `builder.interpolation { expr }`：表达式由 Ruby 求值，
+  # 值按 #render 的分派表插入当前位置（CSM §3.3）。+unsafe: false+（默认）时是
+  # `builder.interpolation("expr")`，构造**未求值**的插值节点（CSM §3.14），交
+  # (6) 按独立样式输出。
+  #
+  # == 安全闸门（CSM §3.14）
+  #
+  # +unsafe+ 是**翻译期**参数，默认 +false+（安全）：块级嵌入不写进产物（只留一
+  # 行注释占位），插值构造未求值节点，所以产物静态上不含用户代码。+unsafe: true+
+  # 才把嵌入原样注入。
+  #
+  # 安全模式下宿主不需要（也不应该）拿产物去 `eval`：未求值的嵌入由 (6) 直接吃
+  # AST1 就能按独立样式输出。求值本身只是宿主的一行 `eval`，mdom 不含求值器。
+  #
+  # 本类**不依赖 prism**：行内边界已由 InlineParser 判好，这里只做序列化。它只
+  # +require+ 节点定义（builder 侧）。
+  #
+  # == 转义
+  #
+  # 只有一层转义（#escape_ruby）：把值编码进 Ruby 双引号字面量（`\` → `\\`、
+  # `"` → `\"`、`#` → `\#`）。旧版为「让 InlineParser 把纯文本当字面」而有的
+  # 第二层 CSM 转义（CSM §3.2 的 `\*`、`` \` ``）随行内结构化一起消失——产物里
+  # 不再有任何等待重新解析的 CSM 文本。
+  class Translator
+    # Ruby 双引号字面量的转义表。`#` 也转义，避免 `\#{` 里的 `#` 与随后的 `{`
+    # 被 Ruby 重新拼成插值。
+    RUBY_ESCAPES = { "\\" => "\\\\", "\"" => "\\\"", "#" => "\\#", "\n" => "\\n", "\t" => "\\t" }.freeze
+
+    # 安全模式下块级嵌入的占位注释（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 inline_block_statement(node, depth, "heading", heading_arguments(node))
+      when :paragraph       then inline_block_statement(node, depth, "paragraph")
+      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 inline_block_statement(node, depth, "header_cell", cell_arguments(node))
+      when :table_cell      then inline_block_statement(node, depth, "cell", cell_arguments(node))
+      when :term            then inline_block_statement(node, depth, "term")
+      when :cite            then inline_block_statement(node, depth, "cite")
+      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_arguments(node)
+      args = [node.level.to_s]
+      args << "closed: true" if node.closed?
+      args
+    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?
+      # 任务列表里的普通项：必须显式写 false，否则 builder 会从列表继承 task。
+      args << "task: false" if !node.task? && node.parent.is_a?(Node::List) && node.parent.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）由 #inline_block_statement 填充，+align+ 按需带上。
+    def cell_arguments(node)
+      node.align ? ["align: #{node.align.inspect}"] : []
+    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
+
+    # 行内容器（段落、标题、单元格……）与带行内子节点的行内节点：有行内子节点时
+    # 用 `do ... end` 逐条构造，没有时退化为单行调用。
+    #
+    # 唯一的例外是 +inline: false+ 解析出的 AST：树里只有 +attributes[:text]+ 原文，
+    # 没有行内节点。此时把原文作为**字符串参数**追加到调用上交给 builder 重新解析
+    # ——这是产物里唯一仍需要行内解析器的形态。
+    def inline_block_statement(node, depth, name, args = [])
+      nodes = inline_nodes(node)
+      return inline_block_lines(nodes, depth, call(@builder, name, args)) unless nodes.empty?
+
+      text = node.attributes[:text].to_s
+      args = text.empty? ? args : insert_text_argument(args, ruby_literal(text))
+      [line(depth, call(@builder, name, args))]
+    end
+
+    # 文本是**位置参数**，必须排在关键字参数之前（`heading(1, "x", closed: true)`）。
+    def insert_text_argument(args, literal)
+      keyword = args.index { |arg| keyword_argument?(arg) }
+      return args + [literal] if keyword.nil?
+
+      args.dup.insert(keyword, literal)
+    end
+
+    # 形如 `name: value` 的产物片段（`closed: true` / `align: :left`）。
+    def keyword_argument?(argument)
+      colon = argument.index(": ")
+      return false if colon.nil? || colon.zero?
+
+      argument[0...colon].each_char.all? do |char|
+        char == "_" || (char >= "a" && char <= "z") || (char >= "0" && char <= "9")
+      end
+    end
+
+    def inline_block_lines(nodes, depth, head)
+      [line(depth, "#{head} do"), *inline_statements(nodes, depth + 1), line(depth, "end")]
+    end
+
+    def inline_statements(nodes, depth)
+      nodes.flat_map { |node| inline_statement(node, depth) }
+    end
+
+    # 行内节点 → builder 行内方法（CSM 元素表里的每一种行内构造）。
+    #
+    # 顺序与 +MDOM::InlineParser+ 的分派一致：叶子单行，带内容的走块；`interpolation`
+    # 是嵌入通道，单独处理（见 #interpolation_statement）。
+    def inline_statement(node, depth)
+      case node.type
+      when :text          then [line(depth, "#{@builder}.text(#{ruby_literal(node.text)})")]
+      when :code_span     then [line(depth, "#{@builder}.code_span(#{ruby_literal(node.code)})")]
+      when :hard_break    then [line(depth, "#{@builder}.hardbreak")]
+      when :mention       then mention_statement(node, depth)
+      when :emphasis      then inline_block_statement(node, depth, "em")
+      when :strong        then inline_block_statement(node, depth, "strong")
+      when :del           then inline_block_statement(node, depth, "del")
+      when :ins           then inline_block_statement(node, depth, "ins")
+      when :link          then inline_block_statement(node, depth, "link", link_arguments(node))
+      when :image         then inline_block_statement(node, depth, "image", image_arguments(node))
+      when :inline_quote  then inline_block_statement(node, depth, "inline_quote", [ruby_literal(node.uri)])
+      when :wiki_link     then inline_block_statement(node, depth, "wiki_link", wiki_link_arguments(node))
+      when :meter         then inline_block_statement(node, depth, "meter", bar_arguments(node))
+      when :progress      then inline_block_statement(node, depth, "progress", bar_arguments(node))
+      when :math          then inline_block_statement(node, depth, "math", [ruby_literal(node.tex)])
+      when :interpolation then interpolation_statement(node, depth)
+      else raise Error, "cannot translate inline #{node.type.inspect} to Ruby"
+      end
+    end
+
+    # `@user` / `@project:x` → `builder.mention("user", kind: "project")`。
+    def mention_statement(node, depth)
+      args = [ruby_literal(node.name)]
+      kind = node.attributes[:kind]
+      args << "kind: #{ruby_literal(kind)}" unless kind.nil?
+      [line(depth, call(@builder, "mention", args))]
+    end
+
+    # `[标签](uri "title")` / `<uri>`。
+    def link_arguments(node)
+      args = [ruby_literal(node.uri)]
+      args << "title: #{ruby_literal(node.title)}" unless node.title.nil?
+      args
+    end
+
+    # `![alt](uri "title")`：+alt+ 是替代文本原文，显示内容由子节点给出。
+    def image_arguments(node)
+      args = [ruby_literal(node.uri), "alt: #{ruby_literal(node.alt)}"]
+      args << "title: #{ruby_literal(node.title)}" unless node.title.nil?
+      args
+    end
+
+    # `[[target|label]]`：+label+ 省略时不传。
+    def wiki_link_arguments(node)
+      args = [ruby_literal(node.attributes[:target])]
+      label = node.attributes[:label]
+      args << ruby_literal(label) unless label.nil?
+      args
+    end
+
+    # `[=m/n]` / `[->m/n]`：+value+ / +max+ 按字面。
+    def bar_arguments(node)
+      [ruby_literal(node.value), ruby_literal(node.max)]
+    end
+
+    # 插值（CSM §3.13）：不安全时把表达式交给 Ruby 求值（结果按 #render 的分派表
+    # 插入当前位置），安全时构造**未求值**的插值节点（CSM §3.14）。
+    def interpolation_statement(node, depth)
+      return [line(depth, "#{@builder}.interpolation(#{ruby_literal(node.expr)})")] unless @unsafe
+
+      expression_statements(node.expr, depth)
+    end
+
+    # `builder.interpolation { 表达式 }`；表达式含换行时改用 `do ... end`。
+    def expression_statements(expr, depth)
+      return [line(depth, "#{@builder}.interpolation { #{expr} }")] unless expr.include?("\n")
+
+      body = expr.split("\n", -1).map { |text| line(depth + 1, text) }
+      [line(depth, "#{@builder}.interpolation do"), *body, line(depth, "end")]
+    end
+
+    # -- 转义 -----------------------------------------------------------------
+
+    # 值 → Ruby 字面量（含引号）。
+    def ruby_literal(value)
+      return "nil" if value.nil?
+
+      "\"#{escape_ruby(value.to_s)}\""
+    end
+
+    # CSM 源码文本（或任意值）→ Ruby 双引号字面量的体。
+    def escape_ruby(text)
+      text.each_char.map { |char| RUBY_ESCAPES.fetch(char, char) }.join
+    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.4.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.4.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 is the Ruby toolchain for CSM (Complex Simple Markup). It parses
+  CSM documents into an AST, translates them to safe-by-default Ruby source, re-serializes
+  them to CSM, and renders HTML. CSM treats Markdown 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: []