mdom 0.3.0 → 0.4.0

data/lib/mdom/translator.rb

@@ -8,65 +8,68 @@ module MDOM
   # (2) AST1 → Ruby 源码（CSM §3.1；docs/IMPLEMENTATION.md §3）。
   #
   # 把一棵 AST1 翻译成**一段顶层顺序执行的 Ruby 程序**：排版节点变成 builder
-  # 调用，嵌入节点（RubyEmbed / 行内插值）原样注入。产出的只是源码字符串，不
-  # 绑定任何执行方式（docs/IMPLEMENTATION.md §6.2）——`eval`、落盘后 `require`、
-  # 交给 mruby 都可以。
+  # 调用，嵌入节点（块级嵌入 / 行内插值）按 +unsafe+ 决定是否原样注入。产出的
+  # 只是源码字符串，不绑定任何执行方式（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"
+  #   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 块原文 / 字符串字面量里的
-  # `#{}`）。这样宿主才有可能判断一段产物是否能在 mruby 上跑。
+  # 接收者，形式可辨识；嵌入段保持原样，边界明确（Ruby 块原文 / `interpolation`
+  # 的块）。这样宿主才有可能判断一段产物是否能在 mruby 上跑。
   #
-  # == 安全闸门（CSM §3.14）
+  # == 行内内容结构化，不回吐标记
   #
-  # +unsafe+ 是**翻译期**参数，默认 +false+（安全）：嵌入节点不写进产物，所以
-  # 产物静态上不含用户代码——块级 `RubyEmbed` 只留一行注释占位，行内插值退化为
-  # 字面 `#{expr}`。+unsafe: true+ 才把嵌入原样注入。
+  # 行内容器（段落、标题、单元格……）在产物里是**块形式**的 builder 调用，每个
+  # 行内子节点翻译成对应的 builder 行内方法：
   #
-  # 安全模式下宿主不需要（也不应该）拿产物去 `eval`：未求值的嵌入由 (6) 直接吃
-  # AST1 就能按独立样式输出。求值本身只是宿主的一行 `eval`，mdom 不含求值器。
+  #   builder.paragraph do
+  #     builder.text("正文 ")
+  #     builder.strong do
+  #       builder.text("粗")
+  #     end
+  #   end
   #
-  # 本类**不依赖 prism**：行内边界已由 InlineParser 判好，这里只做序列化。它只
-  # +require+ 节点定义（builder 侧）。
+  # 产物因此**不经过 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) 按独立样式输出。
   #
-  # 行内容器（段落、标题……）在产物里以**字符串参数**交给 builder，而 builder
-  # 会用 InlineParser 重新解析这些字符串。因此本类要把 AST1 的行内子树重新序列化
-  # 成 CSM 标记文本（`**粗**`、`[标签](uri)`……）。
+  # == 安全闸门（CSM §3.14）
   #
-  # 插值单独处理：+unsafe: true+ 时 `#{}` 在产物里是**真正的 Ruby 插值**（CSM §3.13），
-  # 由 Ruby 求值；安全模式与字面 `#{` 都写成字面。字面 `#{` 会被转义成 `\#{`。两者在 AST1 里已经分开——真插值是
-  # +Node::Interpolation+，字面的 `#{` 落在 +Node::Text+ 里——所以边界不必再扫描
-  # （CSM §3.12：配对与屏蔽交给 prism）。
+  # +unsafe+ 是**翻译期**参数，默认 +false+（安全）：块级嵌入不写进产物（只留一
+  # 行注释占位），插值构造未求值节点，所以产物静态上不含用户代码。+unsafe: true+
+  # 才把嵌入原样注入。
   #
-  # == 两个转义层
+  # 安全模式下宿主不需要（也不应该）拿产物去 `eval`：未求值的嵌入由 (6) 直接吃
+  # AST1 就能按独立样式输出。求值本身只是宿主的一行 `eval`，mdom 不含求值器。
   #
-  # 产物里的纯文本要过两层转义，顺序不能颠倒：
+  # 本类**不依赖 prism**：行内边界已由 InlineParser 判好，这里只做序列化。它只
+  # +require+ 节点定义（builder 侧）。
   #
-  # 1. #escape_markup：让 InlineParser 把纯文本当**字面**（`*星*` 必须写成
-  #    `\*星\*`，否则重新解析会得到紧强调）；
-  # 2. #escape_ruby：把该文本编码进 Ruby 双引号字面量（`\` → `\\`、`"` → `\"`、
-  #    `#` → `\#` 以免与插值混淆）。
+  # == 转义
   #
-  # 已由节点结构提供的标记（`**`、`[`……）只过第 2 层。
+  # 只有一层转义（#escape_ruby）：把值编码进 Ruby 双引号字面量（`\` → `\\`、
+  # `"` → `\"`、`#` → `\#`）。旧版为「让 InlineParser 把纯文本当字面」而有的
+  # 第二层 CSM 转义（CSM §3.2 的 `\*`、`` \` ``）随行内结构化一起消失——产物里
+  # 不再有任何等待重新解析的 CSM 文本。
   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）"
 
@@ -119,17 +122,17 @@ module MDOM
     # 逐节点分派。返回语句行数组（已含缩进）。
     def statement(node, depth)
       case node.type
-      when :heading         then [line(depth, heading_call(node))]
-      when :paragraph       then [line(depth, paragraph_call(node))]
+      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 [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 :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")
@@ -153,25 +156,10 @@ module MDOM
 
     # -- 块级节点 -------------------------------------------------------------
 
-    def heading_call(node)
+    def heading_arguments(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})"
+      args
     end
 
     def item_head(node)
@@ -181,6 +169,8 @@ module MDOM
     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
@@ -208,11 +198,9 @@ module MDOM
       "#{@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)
+    # 表格单元格：正文（PHRASING）由 #inline_block_statement 填充，+align+ 按需带上。
+    def cell_arguments(node)
+      node.align ? ["align: #{node.align.inspect}"] : []
     end
 
     def call(receiver, name, args)
@@ -245,118 +233,125 @@ module MDOM
       node.children.select { |child| inline?(child) }
     end
 
-    # 行内内容的 Ruby 字符串字面量；没有行内内容时返回 +nil+。
+    # 行内容器（段落、标题、单元格……）与带行内子节点的行内节点：有行内子节点时
+    # 用 `do ... end` 逐条构造，没有时退化为单行调用。
     #
-    # 兜底：以 +inline: false+ 解析出的 AST 没有行内节点，此时原文本身就是 CSM
-    # 源码，直接交给 builder 重新解析。
-    def inline_argument(node)
+    # 唯一的例外是 +inline: false+ 解析出的 AST：树里只有 +attributes[:text]+ 原文，
+    # 没有行内节点。此时把原文作为**字符串参数**追加到调用上交给 builder 重新解析
+    # ——这是产物里唯一仍需要行内解析器的形态。
+    def inline_block_statement(node, depth, name, args = [])
       nodes = inline_nodes(node)
-      return "\"#{inline_fragments(nodes)}\"" unless nodes.empty?
+      return inline_block_lines(nodes, depth, call(@builder, name, args)) unless nodes.empty?
 
       text = node.attributes[:text].to_s
-      return nil if text.empty?
-
-      "\"#{escape_ruby(text)}\""
+      args = text.empty? ? args : insert_text_argument(args, ruby_literal(text))
+      [line(depth, call(@builder, name, args))]
     end
 
-    # 行内节点序列化：返回**Ruby 字面量体**（已转义，插值保持为裸 `#{}`）。
-    #
-    # 标记（`**`、`[`……）由节点结构给出，只过 Ruby 转义；纯文本额外过一层 CSM
-    # 转义，让 InlineParser 重新解析时把它当字面。
-    def inline_fragments(nodes)
-      nodes.map { |node| inline_fragment(node) }.join
+    # 文本是**位置参数**，必须排在关键字参数之前（`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
 
-    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"
+    # 形如 `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
 
-    # 插值：不安全时是真正的 Ruby 插值（交 Ruby 求值）；安全时退化为**字面**
-    # `#{expr}`——求值后它落回 CSM 源码，由 builder 重新解析成未求值的
-    # Interpolation 节点，供 (6) 按独立样式输出（CSM §3.14）。
-    def interpolation_fragment(node)
-      literal = "\#{#{node.expr}}"
-      @unsafe ? literal : escape_ruby(literal)
+    def inline_block_lines(nodes, depth, head)
+      [line(depth, "#{head} do"), *inline_statements(nodes, depth + 1), line(depth, "end")]
     end
 
-    def wrap_markup(node, opener, closer = opener)
-      "#{escape_ruby(opener)}#{inline_fragments(node.children)}#{escape_ruby(closer)}"
+    def inline_statements(nodes, depth)
+      nodes.flat_map { |node| inline_statement(node, depth) }
     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}"
+    # 行内节点 → 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
 
-    # `[文本](@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}"
+    # `@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
 
-    # `[[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("]]")}"
+    # `[标签](uri "title")` / `<uri>`。
+    def link_arguments(node)
+      args = [ruby_literal(node.uri)]
+      args << "title: #{ruby_literal(node.title)}" unless node.title.nil?
+      args
     end
 
-    def mention_fragment(node)
-      scope = node.attributes[:kind]
-      escape_ruby("@#{scope ? "#{scope}:" : ""}#{node.attributes[:name]}")
+    # `![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
 
-    def bar_fragment(node, opener)
-      "#{escape_ruby(opener)}#{inline_fragments(node.children)}#{escape_ruby("]")}"
+    # `[[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
 
-    # 链接/图片的目的地（`uri "title"`）。uri 与 title 是字面，不做 CSM 转义。
-    def destination(node)
-      title = node.attributes[:title]
-      title ? "#{node.uri} \"#{title}\"" : node.uri.to_s
+    # `[=m/n]` / `[->m/n]`：+value+ / +max+ 按字面。
+    def bar_arguments(node)
+      [ruby_literal(node.value), ruby_literal(node.max)]
     end
 
-    # 行内代码：反引号数量要与内容里的反引号错开（CSM §1.5），内容按字面。
-    def code_span_fragment(code)
-      ticks = "`" * (code.include?("`") ? MAX_CODE_TICKS : 1)
-      escape_ruby("#{ticks}#{code}#{ticks}")
+    # 插值（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")
 
-    # 第 1 层：纯文本 → 其 CSM 源码形式（给每个标记字符加 `\`）。
-    def escape_markup(text)
-      text.each_char.map { |char| MARKUP_CHARS.include?(char) ? "\\#{char}" : char }.join
+      body = expr.split("\n", -1).map { |text| line(depth + 1, text) }
+      [line(depth, "#{@builder}.interpolation do"), *body, line(depth, "end")]
     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)
@@ -364,6 +359,11 @@ module MDOM
 
       "\"#{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
 

data/lib/mdom/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mdom
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - mdom
@@ -29,10 +29,10 @@ dependencies:
     - - "<"
       - !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.'
+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: []