mdom 0.2.0 → 0.3.0

data/lib/mdom/error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MDOM
+  # CSM 处理的错误基类。
+  class Error < StandardError; end
+
+  # CSM 源码不合法（解析期）。消息中带文档行号，便于定位。
+  class ParseError < Error; end
+
+  # 判定为 Ruby 块，但块首行与块尾行的 CSM 缩进不同（CSM §3.5.2 条件 1）。
+  class CrossLevelError < ParseError; end
+
+  # 围栏代码块没有找到对称的结束围栏（扫描到文档末尾）。
+  class UnclosedFenceError < ParseError; end
+
+  # 块级公式的 `$$` 包围式没有找到独占一行的结束标记（扫描到文档末尾）。
+  class UnclosedMathError < ParseError; end
+
+  # 块里出现 heredoc。CSM §3.12 明确**不支持** heredoc（附录 E），一旦出现就报错，
+  # 而不是把它当普通块收下。
+  class UnsupportedHeredocError < ParseError; end
+end

data/lib/mdom/hooks.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module MDOM
+  # 钩子 / 回调系统（CSM §5.3）。
+  #
+  # 一次 `MDOM.compile` 依次经过五个点，注册的回调按**注册顺序**执行：
+  #
+  # | 点 | 时机 | 载荷 |
+  # |----|------|------|
+  # | `:after_parse` | (1) 完成、行内已解析 | `doc` |
+  # | `:before_compile` | (2) 翻译之前——树仍可改写 | `doc` |
+  # | `:after_compile` | (2) 完成 | `doc, ruby` |
+  # | `:before_serialize` | (6) 之前 | `doc` |
+  # | `:after_serialize` | (6) 之后 | `html, meta` |
+  #
+  # **返回值被忽略**：载荷里的可变对象（节点树、产物字符串）由回调直接改写——这与
+  # CSM §5.3 例子里 `html.insert(...)` 是同一风格。
+  #
+  # 两种作用域：类级注册表（`Document.register_hook`）对所有文档生效；
+  # `MDOM.compile(source, hooks: { before_compile: [proc] })` 传入的**临时**钩子只对
+  # 那一次调用生效。执行顺序是「全局 → 临时」。
+  #
+  # 属 **builder 侧**（docs/IMPLEMENTATION.md §1.1）：只用 Hash / Array / 闭包，
+  # 零 gem 依赖，可在 mruby/WASM 上跑。
+  module Hooks
+    # 五个触发点。
+    POINTS = %i[
+      after_parse before_compile after_compile before_serialize after_serialize
+    ].freeze
+
+    class << self
+      # 在 +point+ 上注册一个回调（块），返回该回调。
+      def register(point, &block)
+        assert_point!(point)
+        raise ArgumentError, "a hook needs a block" if block.nil?
+
+        table(point) << block
+        block
+      end
+
+      # 取消 +point+ 上的某个回调；没注册过时返回 +nil+。
+      def unregister(point, block)
+        assert_point!(point)
+        table(point).delete(block)
+      end
+
+      # 清空 +point+ 上的回调；不给点时清空全部。
+      def clear(point = nil)
+        point.nil? ? @table = {} : table(point).clear
+        self
+      end
+
+      # +point+ 上已注册的回调（副本，改动它不影响注册表）。
+      def registered(point)
+        assert_point!(point)
+        table(point).dup
+      end
+
+      # 依次运行 +point+ 上的回调：先全局（注册顺序），再 +extra+（本次调用传入的
+      # 临时钩子）。返回值被忽略；回调抛出的异常**直接传播**。
+      def run(point, *args, extra: [])
+        assert_point!(point)
+        (table(point) + extra).each { |hook| hook.call(*args) }
+        nil
+      end
+
+      private
+
+      def table(point = nil)
+        @table ||= {}
+        point.nil? ? @table : (@table[point] ||= [])
+      end
+
+      def assert_point!(point)
+        return if POINTS.include?(point)
+
+        raise ArgumentError, "unknown hook point #{point.inspect} (expected one of #{POINTS.inspect})"
+      end
+    end
+  end
+end

data/lib/mdom/html_serializer.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "node/inline_nodes"
+require_relative "node/nodes"
+
+module MDOM
+  # (6) AST → HTML（CSM §1/§2/§7；docs/IMPLEMENTATION.md §7）。
+  #
+  # 输入可以是 **AST1 或 AST2**：两者是同一棵树类型，区别只在是否还残留未求值的
+  # 嵌入节点。未求值的嵌入（`RubyEmbed` / 行内 `Interpolation`）按**独立的嵌入
+  # 样式**输出——结构与相应的代码块同构，另加 `csm-ruby` class。因此「安全渲染」
+  # 与「不安全渲染」的差别只在于 (4) 是否执行嵌入代码，而不是两条序列化路径
+  # （CSM §3.14）。
+  #
+  #   MDOM::HtmlSerializer.serialize(MDOM::Parser.parse("正文 **粗**\n"))
+  #   # => "<p>正文 <strong>粗</strong></p>"
+  #
+  # == 依赖边界
+  #
+  # 本文件属 **builder 侧**（docs/IMPLEMENTATION.md §1.1）：零 gem 依赖、不
+  # `require` prism、不使用正则字面量（`Regexp` 在 mruby 上需外部 gem，§5.5.3），
+  # 因此 mruby / WASM 也能跑。这也是它只消费 AST、**从不解析字符串**的原因——
+  # 例如引用的 `cite` 只有原文，行内不在这里解析。
+  class HtmlSerializer
+    # 文本节点的转义表。
+    TEXT_ESCAPES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;" }.freeze
+
+    # 属性值的转义表（多一个引号）。
+    ATTRIBUTE_ESCAPES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", "\"" => "&quot;" }.freeze
+
+    # 块级公式的容器 class（CSM §1.11）。
+    MATH_CLASS = "math"
+
+    # 未求值嵌入的容器 class。
+    EMBED_CLASS = "csm-ruby"
+
+    def self.serialize(node, **options)
+      new(**options).serialize(node)
+    end
+
+    # +known_targets+ 是 WikiLink 的目标集合（可迭代，元素按 #slug 归一并忽略大小写）；给定时
+    # 不在其中的链接会带上 +orphan-link+ class（CSM §2.1），省略时不作判定。
+    def initialize(known_targets: nil)
+      @known_targets = known_targets && known_targets.map { |target| [slug(target), true] }.to_h
+    end
+
+    # 序列化一棵树（+Node::Document+ 或任意子节点），返回 HTML 字符串。
+    def serialize(node)
+      return document(node) if node.type == :document
+
+      block(node)
+    end
+
+    private
+
+    # -- 文档 -----------------------------------------------------------------
+
+    # 一级标题会把自身和文档内容包进 `<article>`（CSM §1.2）。
+    def document(node)
+      children = visible_children(node)
+      body = sections(children)
+
+      return body unless children.any? { |child| heading?(child, 1) }
+
+      element("article", body)
+    end
+
+    # 二级标题会把自身到下一个二级标题（或文末）之前的内容包进 `<section>`
+    # （CSM §1.2）。h3 及以下不再包裹。
+    def sections(children)
+      groups = [[]]
+      children.each do |child|
+        groups << [] if heading?(child, 2)
+        groups.last << child
+      end
+
+      groups.reject(&:empty?).map do |group|
+        body = block_statements(group)
+        heading?(group.first, 2) ? element("section", body) : body
+      end.join("\n")
+    end
+
+    # 依次输出块级子节点。标题带收尾 `#` 时，紧跟着的段落与它同处一个 `<hgroup>`
+    # （CSM §1.2）。
+    def block_statements(children)
+      html = []
+      index = 0
+      while index < children.size
+        child = children[index]
+        follower = children[index + 1]
+        if hgroup?(child, follower)
+          html << element("hgroup", [block(child), block(follower)].join("\n"))
+          index += 2
+        else
+          html << block(child)
+          index += 1
+        end
+      end
+      html.reject(&:empty?).join("\n")
+    end
+
+    def hgroup?(heading, follower)
+      heading.type == :heading && heading.closed? &&
+        !follower.nil? && follower.type == :paragraph
+    end
+
+    def visible_children(node)
+      node.children.reject { |child| child.type == :end_marker }
+    end
+
+    def heading?(node, level)
+      node.type == :heading && node.level == level
+    end
+
+    # -- 块级 -----------------------------------------------------------------
+
+    def block(node)
+      case node.type
+      when :div              then element("div", children_html(node))
+      when :paragraph        then tag("p", inline_children(node))
+      when :heading          then heading_html(node)
+      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_row        then element("tr", children_html(node))
+      when :table_header_cell then cell_html(node, "th")
+      when :table_cell       then cell_html(node, "td")
+      when :list             then list_html(node)
+      when :list_item        then list_item_html(node)
+      when :definition_list  then element("dl", children_html(node))
+      when :term             then tag("dt", inline_children(node))
+      when :cite             then tag("cite", inline_children(node))
+      when :definition       then element("dd", children_html(node))
+      when :hrule            then "<hr />"
+      when :ruby_embed       then ruby_embed_html(node)
+      when :end_marker       then ""
+      else raise Error, "cannot serialize #{node.type.inspect} to HTML"
+      end
+    end
+
+    def children_html(node)
+      block_statements(node.children)
+    end
+
+    # ATX 标题：`<h1>`–`<h6>` 带 +id+ 锚点（CSM §1.2）。
+    def heading_html(node)
+      attrs = { id: slug(plain_text(node)) }
+      tag("h#{node.level}", inline_children(node), attrs)
+    end
+
+    # 引用：`>-` 的出处是普通的 +Node::Cite+ 子节点（CSM §1.4）。
+    def blockquote_html(node)
+      element("blockquote", children_html(node))
+    end
+
+    def code_block_html(node)
+      tag("pre", tag("code", escape(node.code, TEXT_ESCAPES), code_attributes(node)))
+    end
+
+    # +lang+ → `class="language-<lang>"`；+params+ 原样放进 +data-params+。
+    def code_attributes(node)
+      attrs = {}
+      attrs[:class] = "language-#{node.lang}" if node.lang
+      attrs[:params] = node.params if node.params
+      attrs
+    end
+
+    # 未求值的嵌入块：与围栏代码块同构，另加 #EMBED_CLASS。
+    def ruby_embed_html(node)
+      tag("pre", tag("code", escape(node.source, TEXT_ESCAPES), class: EMBED_CLASS))
+    end
+
+    def cell_html(node, name)
+      attrs = {}
+      attrs[:align] = node.align if node.align
+      tag(name, inline_children(node), attrs)
+    end
+
+    def list_html(node)
+      attrs = {}
+      attrs[:task] = "true" if node.task?
+      element(node.ordered? ? "ol" : "ul", children_html(node), attrs)
+    end
+
+    # 任务项的状态由 `<input type="checkbox">` 承载（CSM §1.3）。
+    def list_item_html(node)
+      body = [checkbox_html(node), children_html(node)].reject(&:empty?).join("\n")
+      element("li", body)
+    end
+
+    def checkbox_html(node)
+      return "" unless node.task?
+
+      attrs = { type: "checkbox" }
+      attrs[:checked] = "checked" if node.checked
+      tag("input", nil, attrs)
+    end
+
+    # -- 行内 -----------------------------------------------------------------
+
+    def inline_children(node)
+      node.children.map { |child| inline(child) }.join
+    end
+
+    def inline(node)
+      case node.type
+      when :text          then escape(node.text, TEXT_ESCAPES)
+      when :emphasis      then tag("em", inline_children(node))
+      when :strong        then tag("strong", inline_children(node))
+      when :code_span     then tag("code", escape(node.code, TEXT_ESCAPES))
+      when :link          then tag("a", inline_children(node), href: node.uri, title: node.title)
+      when :inline_quote  then tag("q", inline_children(node), cite: node.uri)
+      when :image         then tag("img", nil, src: node.uri, alt: node.alt, title: node.title)
+      when :wiki_link     then wiki_link_html(node)
+      when :mention       then mention_html(node)
+      when :del           then tag("del", inline_children(node))
+      when :ins           then tag("ins", inline_children(node))
+      when :hard_break    then "<br />"
+      when :meter         then tag("meter", "", value: node.value, max: node.max)
+      when :progress      then tag("progress", "", value: node.value, max: node.max)
+      when :math          then tag("span", escape(node.tex, TEXT_ESCAPES), class: MATH_CLASS)
+      when :interpolation then tag("code", escape(node.expr, TEXT_ESCAPES), class: EMBED_CLASS)
+      else raise Error, "cannot serialize inline #{node.type.inspect} to HTML"
+      end
+    end
+
+    # WikiLink → `<a>`；目标不在 +known_targets+ 里时带 `orphan-link`（CSM §2.1）。
+    def wiki_link_html(node)
+      target = node.attributes[:target]
+      attrs = { href: slug(target) }
+      attrs[:class] = "orphan-link" if orphan?(target)
+      tag("a", inline_children(node), attrs)
+    end
+
+    def orphan?(target)
+      return false if @known_targets.nil?
+
+      !@known_targets.key?(slug(target))
+    end
+
+    def mention_html(node)
+      scope = node.attributes[:kind]
+      label = "@#{scope ? "#{scope}:" : ""}#{node.attributes[:name]}"
+      tag("a", escape(label, TEXT_ESCAPES), class: "mention", href: label)
+    end
+
+    # -- 输出原语 -------------------------------------------------------------
+
+    def element(name, body, attrs = nil)
+      opening = "<#{name}#{render_attributes(attrs)}>"
+      return "#{opening}</#{name}>" if body.empty?
+
+      "#{opening}\n#{body}\n</#{name}>"
+    end
+
+    # +body+ 为 +nil+ 时按 void 元素自闭合（`<hr />`）。
+    def tag(name, body, attrs = nil)
+      opening = "<#{name}#{render_attributes(attrs)}"
+      return "#{opening} />" if body.nil?
+
+      "#{opening}>#{body}</#{name}>"
+    end
+
+    # 紧凑写法：`attrs` 是 +属性名 => 值+ 的散列，+nil+ 值被跳过。少数属性用
+    # 「名字」而非属性承载（`task`、`align`），这里各自映射成 HTML 形式。
+    def render_attributes(attrs)
+      return "" if attrs.nil?
+
+      attrs.reject { |_name, value| value.nil? }.map do |name, value|
+        rendered = escape(html_attribute_value(name, value), ATTRIBUTE_ESCAPES)
+        %( #{html_attribute_name(name)}="#{rendered}")
+      end.join
+    end
+
+    def html_attribute_name(name)
+      case name
+      when :align then "style"
+      when :task then "class"
+      when :params then "data-params"
+      else name.to_s
+      end
+    end
+
+    def html_attribute_value(name, value)
+      case name
+      when :align then "text-align: #{value};"
+      when :task then "task"
+      else value.to_s
+      end
+    end
+
+    # -- 转义与文本 -----------------------------------------------------------
+
+    def escape(text, table)
+      result = +""
+      text.to_s.each_char { |char| result << table.fetch(char, char) }
+      result
+    end
+
+    # 标题锚点 / WikiLink 目标的规范化：去首尾空白，内部的空白连成 `-`
+    # （CSM §2.1「空格自动转为 `-`」）。
+    # 标题锚点与 WikiLink 目标共用同一套 slug：去空白、把空白连成 `-`，并统一成
+    # **小写**（CSM §2.1 要求 WikiLink 目标不区分大小写）。两者一致，`[[笔记#锚点]]`
+    # 才能对上标题的 `id`。
+    def slug(text)
+      text.to_s.split.join("-").downcase
+    end
+
+    # 行内子树的纯文本（用于标题锚点）：字符串不在这里解析，只取已有内容。
+    def plain_text(node)
+      return node.text.to_s if node.type == :text
+      return node.code.to_s if node.type == :code_span
+
+      node.children.map { |child| plain_text(child) }.join
+    end
+  end
+end
+
+module MDOM
+  module Node
+    # 便捷入口：+node.to_html+ ≡ +MDOM::HtmlSerializer.serialize(node)+。
+    class BaseNode
+      def to_html
+        HtmlSerializer.serialize(self)
+      end
+    end
+  end
+end