mdom 0.2.0 → 0.4.0

data/lib/mdom/tokenizer.rb

@@ -0,0 +1,458 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+require_relative "error"
+require_relative "block_detector"
+
+module MDOM
+  # 行级 Tokenizer：按 CSM §3 的分类规则逐行分类（docs/IMPLEMENTATION.md §2.1）。
+  #
+  # 分类顺序（优先级从高到低）：**围栏 → 表格 → 块级公式 → `\` 转义 → `~` →
+  # 候选嵌入 → 排版**。
+  # `~` 的判定必须先于候选嵌入——`~ list.each do |item|` 是 `~` 行，不能按候选
+  # 行交给 Prism。
+  #
+  # 产出的最小 Token 集合见 docs/IMPLEMENTATION.md §2.3。对嵌入，Tokenizer 只
+  # 交出**源码原文 + 位置 + 形态**，不判断哪行是赋值、哪行要渲染——「是否注入」
+  # 完全由嵌入代码是否调用 `render` 决定（CSM §3.3）。
+  class Tokenizer
+    # 一个行级 token。+indent+ 是该行的 CSM 缩进（前导空格数）。
+    Token = Struct.new(:type, :line, :indent, :value, keyword_init: true)
+
+    # 缩进单位：1 个制表符或 4 个空格（CSM §1.1）。制表符按下表展开为空格。
+    INDENT_UNIT = 4
+
+    FENCE_RE   = /\A(`{3,6})(.*)\z/
+    TILDE_RE   = /\A~ (.*)\z/
+    # ATX 标题。第 3 组捕获可选的收尾 `#`（含其前导空白），CSM §1.2 的 `<hgroup>`
+    # 用法要求收尾 `#` 与引导 `#` 数量相同。
+    HEADING_RE = /\A(\#{1,6})[ \t]+(.*?)([ \t]+\#{1,6})?[ \t]*\z/
+    HRULE_RE   = /\A-{3,72}\z/
+    # CSM §1.3 只定义一种无序列表标记（`- `）与一种有序形式（`N. `）。
+    ULIST_RE   = /\A-[ \t]+(.*)\z/
+    OLIST_RE   = /\A(\d{1,9})\.[ \t]+(.*)\z/
+    TASK_RE    = /\A\[([ xX])\][ \t]+(.*)\z/
+    QUOTE_RE   = /\A> ?(.*)\z/
+    CITE_RE    = /\A>- ?(.*)\z/
+    DEF_RE     = /\A:[ \t]+(.*)\z/
+
+    # CSM §1.12：表格行以 `|` 开头和结尾；单元格由未转义的 `|` 分割。
+    TABLE_ROW_RE = /\A\|.*\|\z/
+    # 分隔行的单元格：一个或多个 `-`，可选 `:` 前缀 / 后缀。
+    SEPARATOR_CELL_RE = /\A:?-+:?\z/
+    # 单元格内容：一个转义对（`\` + 任意字符）或一个非 `|` 字符，成段出现。
+    CELL_RUN = /(?:\\.|[^|])+/m
+    CELL_SEPARATOR = /\|/
+
+    # CSM §1.11：块级公式。`$$…$$` 一行成块，或 `$$` 独占一行的包围式。
+    MATH_FENCE = "$$"
+    FULL_LINE_MATH_RE = /\A\$\$(.+)\$\$\z/
+
+    END_MARKER = "__END__"
+
+    # 行首 `\` 后若是这些字符之一，`\` 同时承担行内转义，必须留给 InlineParser。
+    # 与 InlineParser::ESCAPABLE 保持一致（tokenizer_test 有同步断言）。
+    INLINE_ESCAPABLE = %w[` * _ { } [ ] ( ) # + - . ! " $ % & ' , / : ; < = > ? @ ^ | ~ \\].freeze
+
+    def initialize(detector: BlockDetector.new)
+      @detector = detector
+    end
+
+    # 把 CSM 源码切成 token 数组。
+    def tokenize(source)
+      lines = normalize(source)
+      tokens = []
+      index = 0
+
+      while index < lines.size
+        line = lines[index]
+        indent = indent_width(line)
+        content = line[indent..] || ""
+        line_number = index + 1
+
+        if content.empty?
+          index = emit_blank(tokens, lines, index)
+          next
+        end
+
+        fence = FENCE_RE.match(content)
+        if fence && indent.zero?
+          index = emit_fence(tokens, lines, index, indent, line_number, fence)
+          next
+        end
+
+        # 表格：连续的同缩进表格行合成一个 token（CSM §1.12）。
+        if table_row?(content)
+          index = emit_table(tokens, lines, index, indent, line_number)
+          next
+        end
+
+        # 块级公式（CSM §1.11）：`$$…$$` 一行，或 `$$` 独占一行的包围式。
+        # 与围栏一样，「层级方式」不允许缩进，因此只在顶层识别。
+        if indent.zero? && content == MATH_FENCE
+          index = emit_fenced_math(tokens, lines, index, line_number)
+          next
+        end
+
+        if indent.zero? && full_line_math?(content)
+          tokens << math_token(content, line_number)
+          index += 1
+          next
+        end
+
+        # `\` 行首转义：只跳过块级判定。若 `\` 后是行内可转义字符，则把它留给
+        # InlineParser（`\*` ≠ 强调）；否则 `\` 只是块级转义标记，剥离
+        # （`\while` → `while`）。CSM §3.11。
+        if content.start_with?("\\")
+          escaped = content.length > 1 && INLINE_ESCAPABLE.include?(content[1])
+          tokens << text_token(escaped ? content : content[1..], line_number, indent)
+          index += 1
+          next
+        end
+
+        tilde = TILDE_RE.match(content)
+        if tilde
+          tokens << Token.new(
+            type: :ruby_block, line: line_number, indent: indent,
+            value: { source: tilde[1], form: :tilde, lines: (line_number..line_number),
+                     indent: indent, render: false }
+          )
+          index += 1
+          next
+        end
+
+        if BlockDetector.candidate_start?(content) && candidate?(content)
+          detection = @detector.detect(lines, index, indent)
+          if detection
+            index = emit_ruby_block(tokens, lines, index, indent, line_number, detection)
+            next
+          end
+        end
+
+        if indent.zero? && content == END_MARKER
+          tokens << Token.new(
+            type: :end_marker, line: line_number, indent: indent,
+            value: { line: line_number, data: join_tail(lines, index + 1) }
+          )
+          break
+        end
+
+        tokens << layout_token(content, line_number, indent)
+        index += 1
+      end
+
+      tokens
+    end
+
+    private
+
+    # 块判定前的预筛（CSM §3.5.4 的收窄 + A 类门控）。
+    #
+    # 判定器响应 +candidate?+ 时先问一句，从而对注定不会被判定的行——英文散文，
+    # 或不在 A 类白名单里的行——连 +detect+ 都不必调用，**零次 Prism 调用**。
+    # 自定义判定器没有这个谓词时按「值得判定」处理，行为与从前一致。
+    #
+    # +content+ 是**已剥离 CSM 缩进**的首行内容。
+    def candidate?(content)
+      return true unless @detector.respond_to?(:candidate?)
+
+      @detector.candidate?(content)
+    end
+
+    def normalize(source)
+      text = source.to_s
+      # 绝大多数源没有 `\r`：省掉一次全量 gsub 与它那份中间串。
+      text = text.gsub(/\r\n?/, "\n") if text.include?("\r")
+      text = text.sub(/\n+\z/, "")
+      return [] if text.empty?
+
+      text.split("\n", -1).map { |line| expand_leading_tabs(line) }
+    end
+
+    # 把行首的制表符展开为空格（制表位每 4 列一个），行中内容原样保留。
+    def expand_leading_tabs(line)
+      return line unless line.include?("\t")
+
+      width = 0
+      index = 0
+      while index < line.length
+        case line[index]
+        when " " then width += 1
+        when "\t" then width += INDENT_UNIT - (width % INDENT_UNIT)
+        else break
+        end
+        index += 1
+      end
+      return line if index.zero?
+
+      (" " * width) + (line[index..] || "")
+    end
+
+    # 合并连续空行，count 是空行行数（1 → 新块，3 → 新节块）。
+    def emit_blank(tokens, lines, index)
+      cursor = index
+      cursor += 1 while cursor < lines.size && content_of(lines[cursor]).empty?
+      tokens << Token.new(type: :blank, line: index + 1, indent: 0, value: { count: cursor - index })
+      cursor
+    end
+
+    # 围栏代码块整体跳过，不做任何嵌入判定（CSM §1.5）。
+    def emit_fence(tokens, lines, index, indent, line_number, match)
+      marker = match[1]
+      info = match[2].strip
+      code = []
+      cursor = index + 1
+      closed = false
+
+      while cursor < lines.size
+        if content_of(lines[cursor]) == marker
+          closed = true
+          break
+        end
+        code << lines[cursor]
+        cursor += 1
+      end
+
+      raise UnclosedFenceError, "unclosed code fence opened at line #{line_number}" unless closed
+
+      lang, params = split_info(info)
+      tokens << Token.new(
+        type: :fence, line: line_number, indent: indent,
+        value: { fence: marker.length, lang: lang, params: params, code: code.join("\n") }
+      )
+      cursor + 1
+    end
+
+    # -- 表格（CSM §1.12）---------------------------------------------------------
+
+    # 一行是否属于表格：以 `|` 开头和结尾。
+    def table_row?(content)
+      content.rstrip.match?(TABLE_ROW_RE)
+    end
+
+    # 收集连续的同缩进表格行，解析成行数组后产出一个 +:table+ token。
+    #
+    # 行的载荷是 +{ rows: [...] }+，每行 +{ cells:, header:, align: }+：
+    # * +cells+ —— 单元格原文（交给 Parser 做行内解析）；
+    # * +header+ —— 是否表头（由分隔行把前一行提升而来）；
+    # * +align+ —— 该行各列的对齐（+nil+ / +:left+ / +:center+ / +:right+）。
+    def emit_table(tokens, lines, index, indent, line_number)
+      cursor = index
+      cursor += 1 while cursor < lines.size && indent_width(lines[cursor]) == indent &&
+                        table_row?(content_of(lines[cursor]))
+
+      source = (index...cursor).map { |i| content_of(lines[i]).rstrip }
+      tokens << Token.new(type: :table, line: line_number, indent: indent,
+                          value: { rows: parse_table(source) })
+      cursor
+    end
+
+    # 逐行解析表格：分隔行把**前面那一行**提升为表头，并更新其后各行的对齐。
+    # 分隔行自身不产生数据行（CSM §1.12）。
+    def parse_table(lines)
+      rows = []
+      align = []
+
+      lines.each do |line|
+        if separator_row?(line)
+          align = separator_aligns(line)
+          rows.last[:header] = true if rows.any?
+          rows.last[:align] = align if rows.any?
+          next
+        end
+
+        rows << { cells: split_cells(line), header: false, align: align }
+      end
+
+      rows
+    end
+
+    # 每个单元格都是 `-` 串（可带 `:`）的行是分隔行。
+    def separator_row?(line)
+      cells = split_cells(line)
+      cells.any? && cells.all? { |cell| cell.match?(SEPARATOR_CELL_RE) }
+    end
+
+    def separator_aligns(line)
+      split_cells(line).map { |cell| alignment_of(cell) }
+    end
+
+    # `:---` → 左；`---:` → 右；`:--:` → 居中；`---` → 默认。
+    def alignment_of(cell)
+      return :center if cell.start_with?(":") && cell.end_with?(":")
+      return :left if cell.start_with?(":")
+      return :right if cell.end_with?(":")
+
+      nil
+    end
+
+    # 按**未转义的** `|` 切出单元格；首尾的 `|` 不产生空单元格。`\|` 原样留在
+    # 单元格里，交给 InlineParser 按 CSM §3.11 的转义语义处理。
+    #
+    # 用 StringScanner 一次收下一整段单元格内容（`\\.` 或非 `|` 的连续串），
+    # 而不是逐字符判断——表格行的单元格往往很长，这一点很划算。
+    def split_cells(line)
+      scanner = StringScanner.new(line)
+      cells = []
+      cell = line[0, 0] # 空字符串，继承 line 的编码
+
+      until scanner.eos?
+        if (run = scanner.scan(CELL_RUN))
+          cell << run
+        elsif scanner.skip(CELL_SEPARATOR)
+          cells << cell
+          cell = line[0, 0]
+        else
+          break # 到不了：CELL_RUN 覆盖除 `|` 之外的所有字符
+        end
+      end
+
+      cells << cell
+
+      # 移除尾部未转义 | 产生的空单元格。
+      # 注意：先判断尾部，再处理首部，避免 "|" 这种输入留下多余空串。
+      cells.pop if cells.size > 1 && cells.last.empty?
+
+      # 行首的 | 不可能被前面的反斜杠转义
+      cells.shift if line.start_with?("|") && !cells.empty? && cells.first.empty?
+
+      cells.map!(&:strip)
+      cells
+    end
+
+    # -- 块级公式（CSM §1.11）-----------------------------------------------------
+
+    def full_line_math?(content)
+      content.strip.match?(FULL_LINE_MATH_RE)
+    end
+
+    def math_token(content, line_number)
+      Token.new(type: :math_block, line: line_number, indent: 0,
+                value: { tex: full_line_math(content) })
+    end
+
+    def full_line_math(content)
+      content.strip[FULL_LINE_MATH_RE, 1].strip
+    end
+
+    # `$$` 独占一行的包围式：收集到下一个独占一行的 `$$`。行的内容原样保留
+    # （字面，与围栏一致）；CSM §1.11。
+    def emit_fenced_math(tokens, lines, index, line_number)
+      body = []
+      cursor = index + 1
+
+      while cursor < lines.size && content_of(lines[cursor]) != MATH_FENCE
+        body << lines[cursor]
+        cursor += 1
+      end
+
+      raise UnclosedMathError, "unclosed block math opened at line #{line_number}" if cursor >= lines.size
+
+      tokens << Token.new(type: :math_block, line: line_number, indent: 0,
+                          value: { tex: body.join("\n").strip })
+      cursor + 1
+    end
+
+    def emit_ruby_block(tokens, lines, index, indent, line_number, detection)
+      last = detection.end_index
+      source = (index..last).map { |i| drop_indent(lines[i], indent) }.join("\n")
+      tokens << Token.new(
+        type: :ruby_block, line: line_number, indent: indent,
+        value: { source: source, form: detection.form, lines: (line_number..(last + 1)),
+                 indent: indent, render: detection.render }
+      )
+      last + 1
+    end
+
+    def layout_token(content, line_number, indent)
+      if (match = HEADING_RE.match(content))
+        return Token.new(type: :heading, line: line_number, indent: indent,
+                         value: heading_value(match))
+      end
+
+      return Token.new(type: :hrule, line: line_number, indent: indent, value: {}) if HRULE_RE.match?(content)
+
+      if (match = CITE_RE.match(content))
+        return Token.new(type: :cite, line: line_number, indent: indent, value: { text: match[1] })
+      end
+
+      if (match = QUOTE_RE.match(content))
+        return Token.new(type: :blockquote, line: line_number, indent: indent, value: { text: match[1] })
+      end
+
+      if (match = ULIST_RE.match(content))
+        return list_item_token(match[1], line_number, indent, "-")
+      end
+
+      if (match = OLIST_RE.match(content))
+        return list_item_token(match[2], line_number, indent, "#{match[1]}.")
+      end
+
+      if (match = DEF_RE.match(content))
+        return Token.new(type: :definition, line: line_number, indent: indent, value: { text: match[1] })
+      end
+
+      text_token(content, line_number, indent)
+    end
+
+    # 标题载荷：收尾 `#` 与引导 `#` 数量相同才算「收尾」（CSM §1.2），否则那些
+    # `#` 只是标题正文的一部分。
+    def heading_value(match)
+      level = match[1].length
+      closer = match[3]
+      closed = !closer.nil? && closer.strip.length == level
+      text = match[2]
+      text = "#{text}#{closer}" if !closed && !closer.nil?
+      { level: level, text: text, closed: closed }
+    end
+
+    def list_item_token(text, line_number, indent, marker)
+      ordered = marker.end_with?(".")
+      task = TASK_RE.match(text)
+      value =
+        if task
+          { text: task[2], marker: marker, ordered: ordered, task: true, checked: task[1].casecmp?("x") }
+        else
+          { text: text, marker: marker, ordered: ordered, task: false, checked: nil }
+        end
+      Token.new(type: :list_item, line: line_number, indent: indent, value: value)
+    end
+
+    def text_token(text, line_number, indent)
+      Token.new(type: :text, line: line_number, indent: indent, value: { text: text })
+    end
+
+    # 围栏 info string：第一个词是语言，其余是参数。
+    def split_info(info)
+      return [nil, nil] if info.empty?
+
+      lang, _separator, params = info.partition(/\s+/)
+      [lang.empty? ? nil : lang, params.empty? ? nil : params]
+    end
+
+    def join_tail(lines, from)
+      return nil if from >= lines.size
+
+      lines[from..].join("\n")
+    end
+
+    def content_of(line)
+      drop_indent(line, indent_width(line))
+    end
+
+    # 前导空白（空格或制表符）的宽度。用 +index+ 找第一个非空白字符——比
+    # 「匹配一段空白再取长度」少一次子串分配。
+    def indent_width(line)
+      line.index(/[^ \t]/) || line.length
+    end
+
+    def drop_indent(line, count)
+      return line if count.zero?
+
+      index = 0
+      index += 1 while index < count && index < line.length && line[index] == " "
+      line[index..] || ""
+    end
+  end
+end