mdom 0.3.0 → 0.4.0

data/lib/mdom/markdown_serializer.rb

@@ -48,9 +48,16 @@ module MDOM
       "~" => "\\~",
       "[" => "\\[",
       "]" => "\\]",
-      "$" => "\\$"
+      "$" => "\\$",
+      "<" => "\\<",
+      "@" => "\\@",
+      "!" => "\\!"
     }.freeze
 
+    # 出现在文本节点**开头**时可能开启块级构造的字符。行首 `\` 只跳过块级判定，
+    # 随后的 `\` 仍按行内转义处理，所以这里加一个 `\` 就能让整行保持为段落。
+    BLOCK_START_ESCAPES = ["#", ">", "-", ":", "|", "_", "(", "{", "%"].freeze
+
     # 分隔线（CSM §1.6：3–72 个 `-`）。
     HRULE = "---"
 
@@ -206,9 +213,17 @@ module MDOM
       rows = node.children.reject { |row| row.children.empty? }
       return [] if rows.empty?
 
-      lines = [table_row(rows.first, pad)]
-      lines << separator_row(rows.first, pad) if header_row?(rows.first)
-      rows.drop(1).each { |row| lines << table_row(row, pad) }
+      lines = []
+      first = rows.first
+      # 没有表头但需要对齐时，用开头的分隔行表达（CSM §1.12）；它不产生行。
+      lines << separator_row(first, pad) if !header_row?(first) && first.children.any?(&:align)
+
+      rows.each do |row|
+        lines << table_row(row, pad)
+        # 分隔行既把前一行提升为表头，也设定它自己与后续行的对齐。每个表头行后面
+        # 都要跟一条，否则连续表头/中途表头会在往返时退化成数据行。
+        lines << separator_row(row, pad) if header_row?(row)
+      end
       lines
     end
 
@@ -217,10 +232,30 @@ module MDOM
     end
 
     def table_row(row, pad)
-      cells = row.children.map { |cell| " #{inline_children(cell)} " }
+      cells = row.children.map { |cell| " #{escape_table_pipes(inline_children(cell))} " }
       "#{pad}|#{cells.join("|")}|"
     end
 
+    # 表格在行内解析**之前**按未转义的 `|` 切格，因此单元格里的字面 `|` 必须
+    # 变成奇数个反斜杠 + `|`，切格器才会把它当内容而不是分隔符。
+    def escape_table_pipes(text)
+      out = +""
+      slashes = +""
+      text.each_char do |char|
+        if char == "\\"
+          slashes << char
+          next
+        end
+
+        out << slashes
+        out << "\\" if char == "|" && slashes.length.even?
+        slashes.clear
+        out << char
+      end
+      out << slashes unless slashes.empty?
+      out
+    end
+
     def separator_row(row, pad)
       cells = row.children.map { |cell| separator_cell(cell.align) }
       "#{pad}|#{cells.join("|")}|"
@@ -305,18 +340,41 @@ module MDOM
     end
 
     # 保守转义：单字符查表 + `#{` 的起始 `#`（CSM §3.11、§3.13）。
+    #
+    # 文本节点可能正好落在输出行的开头（段落第一段，或硬换行之后）。这时再补一个
+    # 行首 `\`，避免 `#` / `>` / `-` / `:` / `|` / `__END__` 被重新识别为块级构造。
+    # 行首 `\` 不参与块级判定，但仍按行内转义处理，所以不会污染文本内容。
     def escape_text(text)
-      characters = text.to_s.chars
+      source = text.to_s
+      characters = source.chars
+      ordered_dot = ordered_list_dot_index(characters)
       out = +""
+
       characters.each_with_index do |char, index|
-        out << if char == "#" && characters[index + 1] == "{"
-                 "\\#"
-               else
-                 TEXT_ESCAPES[char] || char
-               end
+        if char == "#" && characters[index + 1] == "{"
+          out << "\\#"
+        else
+          out << "\\" if index.zero? && block_start?(char)
+          out << (index == ordered_dot ? "\\." : (TEXT_ESCAPES[char] || char))
+        end
       end
       out
     end
+
+    def block_start?(char)
+      BLOCK_START_ESCAPES.include?(char)
+    end
+
+    # 行首的 `N.` 会被识别为有序列表；反斜杠不能转义数字，改为转义那个点。
+    def ordered_list_dot_index(characters)
+      cursor = 0
+      cursor += 1 while cursor < characters.length && cursor < 9 &&
+                        characters[cursor] >= "0" && characters[cursor] <= "9"
+
+      return cursor if cursor.positive? && characters[cursor] == "."
+
+      nil
+    end
   end
 end
 

data/lib/mdom/node.rb

@@ -515,7 +515,15 @@ module MDOM
       def ancestor_of?(other)
         raise ArgumentError, "other cannot be nil" if other.nil?
 
-        other.ancestors.include?(self)
+        # 沿父链走而不是先建一份 +ancestors+ 数组：挂载路径上这个方法调用极频繁
+        # （每次 +<<+ / +prepend+ 都要查一次环），而答案通常在前一两跳就确定。
+        node = other.parent
+        while node
+          return true if node.equal?(self)
+
+          node = node.parent
+        end
+        false
       end
     end
 

data/lib/mdom/parser.rb

@@ -31,8 +31,21 @@ module MDOM
       new(**options).parse(source)
     end
 
-    def initialize(detector: BlockDetector.new, inline: true)
-      @tokenizer = Tokenizer.new(detector: detector)
+    # 参数：
+    # * +detector:+ —— 块判定器，默认 +BlockDetector.new+。**自定义判定器时，A 类的
+    #   开关与白名单要配在判定器自己身上**，不要再传下面两个选项（同时给出会报错）。
+    # * +inline:+ —— 是否做行内解析；+false+ 只做块结构。
+    # * +free_blocks:+ —— **A 类（自由块）判定开关**（CSM §3.5），默认 +true+。
+    #   +false+ 时不做任何 A 类判定，命中行按**排版**处理（CSM §3.5.3，不报错）；
+    #   B 类（引导关键字）与 `~` 行不受影响。
+    # * +free_blocks_allowed:+ —— A 类判定的**白名单**，默认 +nil+（不限制）。给出后
+    #   只有行首标识符命中的行才尝试 A 类判定：+String+ 精确相等，+Regexp+ 对已剥离
+    #   缩进的整行匹配。空数组等价于 +free_blocks: false+。
+    #
+    # 后两个选项服务于英文散文文档：那里「以字母开头的行」比比皆是，逐一交给 Prism
+    # 增量 parse 会产生几百到上万次调用（docs/IMPLEMENTATION.md §2.2.4）。
+    def initialize(detector: nil, inline: true, free_blocks: true, free_blocks_allowed: nil)
+      @tokenizer = Tokenizer.new(detector: resolve_detector(detector, free_blocks, free_blocks_allowed))
       @inline = inline
     end
 
@@ -59,6 +72,21 @@ module MDOM
 
     private
 
+    # 组装块判定器：没给 +detector+ 就把两个 A 类选项用在默认判定器上；给了就要求
+    # 那两个选项保持默认——配置的**单一来源**，避免「传了却不生效」的静默失效。
+    def resolve_detector(detector, free_blocks, free_blocks_allowed)
+      if detector.nil?
+        BlockDetector.new(free_blocks: free_blocks, free_blocks_allowed: free_blocks_allowed)
+      else
+        unless free_blocks == true && free_blocks_allowed.nil?
+          raise ArgumentError,
+                "`detector:` cannot be combined with `free_blocks:` / `free_blocks_allowed:` " \
+                "— configure the detector itself instead"
+        end
+        detector
+      end
+    end
+
     def dispatch(token, root, stack)
       case token.type
       when :blank

data/lib/mdom/tokenizer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "strscan"
+
 require_relative "error"
 require_relative "block_detector"
 
@@ -39,6 +41,9 @@ module MDOM
     TABLE_ROW_RE = /\A\|.*\|\z/
     # 分隔行的单元格：一个或多个 `-`，可选 `:` 前缀 / 后缀。
     SEPARATOR_CELL_RE = /\A:?-+:?\z/
+    # 单元格内容：一个转义对（`\` + 任意字符）或一个非 `|` 字符，成段出现。
+    CELL_RUN = /(?:\\.|[^|])+/m
+    CELL_SEPARATOR = /\|/
 
     # CSM §1.11：块级公式。`$$…$$` 一行成块，或 `$$` 独占一行的包围式。
     MATH_FENCE = "$$"
@@ -46,6 +51,10 @@ module MDOM
 
     END_MARKER = "__END__"
 
+    # 行首 `\` 后若是这些字符之一，`\` 同时承担行内转义，必须留给 InlineParser。
+    # 与 InlineParser::ESCAPABLE 保持一致（tokenizer_test 有同步断言）。
+    INLINE_ESCAPABLE = %w[` * _ { } [ ] ( ) # + - . ! " $ % & ' , / : ; < = > ? @ ^ | ~ \\].freeze
+
     def initialize(detector: BlockDetector.new)
       @detector = detector
     end
@@ -92,9 +101,12 @@ module MDOM
           next
         end
 
-        # `\` 行首转义：剥离 `\`，强制按 Markdown 文本（CSM §3.11）。
+        # `\` 行首转义：只跳过块级判定。若 `\` 后是行内可转义字符，则把它留给
+        # InlineParser（`\*` ≠ 强调）；否则 `\` 只是块级转义标记，剥离
+        # （`\while` → `while`）。CSM §3.11。
         if content.start_with?("\\")
-          tokens << text_token(content[1..], line_number, indent)
+          escaped = content.length > 1 && INLINE_ESCAPABLE.include?(content[1])
+          tokens << text_token(escaped ? content : content[1..], line_number, indent)
           index += 1
           next
         end
@@ -110,7 +122,7 @@ module MDOM
           next
         end
 
-        if content.match?(/\A[A-Za-z]/)
+        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)
@@ -135,8 +147,24 @@ module MDOM
 
     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.gsub(/\r\n?/, "\n").sub(/\n+\z/, "")
+      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) }
@@ -144,6 +172,8 @@ module MDOM
 
     # 把行首的制表符展开为空格（制表位每 4 列一个），行中内容原样保留。
     def expand_leading_tabs(line)
+      return line unless line.include?("\t")
+
       width = 0
       index = 0
       while index < line.length
@@ -259,27 +289,36 @@ module MDOM
 
     # 按**未转义的** `|` 切出单元格；首尾的 `|` 不产生空单元格。`\|` 原样留在
     # 单元格里，交给 InlineParser 按 CSM §3.11 的转义语义处理。
+    #
+    # 用 StringScanner 一次收下一整段单元格内容（`\\.` 或非 `|` 的连续串），
+    # 而不是逐字符判断——表格行的单元格往往很长，这一点很划算。
     def split_cells(line)
-      cells = [""]
-      index = 0
-
-      while index < line.length
-        char = line[index]
-        if char == "\\"
-          cells[-1] = cells[-1] + line[index, 2]
-          index += 2
-        elsif char == "|"
-          cells << ""
-          index += 1
+      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
-          cells[-1] = cells[-1] + char
-          index += 1
+          break # 到不了：CELL_RUN 覆盖除 `|` 之外的所有字符
         end
       end
 
-      cells.shift if line.start_with?("|")
-      cells.pop if line.end_with?("|")
-      cells.map(&:strip)
+      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）-----------------------------------------------------
@@ -402,11 +441,15 @@ module MDOM
       drop_indent(line, indent_width(line))
     end
 
+    # 前导空白（空格或制表符）的宽度。用 +index+ 找第一个非空白字符——比
+    # 「匹配一段空白再取长度」少一次子串分配。
     def indent_width(line)
-      line[/\A[ \t]*/].to_s.length
+      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..] || ""