mdom 0.2.0 → 0.4.0

data/lib/mdom/inline_parser.rb

@@ -1,185 +1,817 @@
 # frozen_string_literal: true
 
+require "prism"
+require "strscan"
+
+require_relative "node/inline_nodes"
+
 module MDOM
-  # Tokenizes a run of inline text into inline nodes: Text, Emphasis, Strong,
-  # Code, Link, Image, Softbreak, Hardbreak and escaped characters.
+  # 行内解析器：把一段**行内文本**解析为行内节点数组（docs/IMPLEMENTATION.md §2.4）。
+  #
+  # 覆盖 CSM 的行内语法：行内代码（§1.5）、强调（§1.7）、增删（§1.8）、行内引用
+  # （§1.9）、进度与度量（§1.10）、公式（§1.11）、WikiLink（§2.1）、提及（§2.2）、
+  # 链接与图片（§2.3）、行首转义与行内转义（§3.11）、插值（§3.13），以及软换行
+  # 折叠与硬换行（§1.1）。
+  #
+  # 产出的是**未求值**的节点：`#{}` 只保存表达式原文，公式只保存 TeX 原文。
+  # 块级结构（围栏、块级公式、透明 Ruby……）不属于本类。
+  #
+  # === 扫描方式
+  #
+  # 扫描由 +StringScanner+（strscan，Ruby 自带）驱动：主循环用一条正则把**整段
+  # 普通字面**一次收下，只在遇到标记字符时才逐字符分派；查找类操作（找配对反引号、
+  # 找闭定界符、找 `]` ……）同样交给 +StringScanner+ 的正则搜索，而不是 Ruby 层的
+  # 逐字符 +while+ 循环。这样 +String#[]+ 与 +String#<<+ 的调用次数从「每字符一次」
+  # 降到「每段一次」。
   #
-  # This is a pragmatic subset of CommonMark inline syntax. Code spans and
-  # links/images are matched textually; emphasis/strong is resolved by finding
-  # the next matching delimiter and recursing into the enclosed text. Delimiter
-  # runs and exact flanking rules are intentionally simplified.
-  module InlineParser
-    ESCAPABLE = /[\x00`*_{}\[\]()#+\-.!>]/.freeze
-    SPECIAL = /[\\`!*_\[\n]/.freeze
+  # 注意 +StringScanner+ 的位置是**字节**偏移，所以本类内部一律按字节定位，需要
+  # 单个字符时用 +String#byteslice+ 取出（+char_before+ 负责向前跨过一个多字节字符）。
+  #
+  #   MDOM::InlineParser.parse("**粗** 与 *斜* 与 `code`")
+  class InlineParser
+    # 可以被 `\` 转义的字符（CommonMark 的 ASCII 标点，外加 CSM 用到的 `$`、`@`）。
+    ESCAPABLE = %w[` * _ { } [ ] ( ) # + - . ! " $ % & ' , / : ; < = > ? @ ^ | ~ \\].freeze
+
+    # 东亚（CJK）标点（CSM §1.1：`\n` 前是它们时不插入空格）。
+    CJK_PUNCTUATION = /
+      [\u3000-\u303F]   # CJK 符号和标点（、。〈〉《》「」【】…）
+      |[\uFF01-\uFF0F]  # 全角标点（！ ～ ／）
+      |[\uFF1A-\uFF20]  # 全角标点（： ～ ＠）
+      |[\uFF3B-\uFF40]  # 全角标点（［ ～ ｀）
+      |[\uFF5B-\uFF65]  # 全角标点（｛ ～ ･）
+      |[\u2013\u2014]   # – —
+      |[\u2018-\u201D]  # ‘ ’ “ ”
+      |[\u2026\u00B7\u30FB]
+    /x
+
+    # 提及的名字部分：前导 `@` 已由主循环消费，所以这里不再带 `@`（也不用 `\A`
+    # 锚定——+StringScanner#scan+ 就是从当前位置匹配）。
+    MENTION_SCAN_RE = /[A-Za-z0-9_][\w-]*(?::[A-Za-z0-9_][\w-]*)?/
+    AUTOLINK_RE = /\A(?:[A-Za-z][A-Za-z0-9+.-]*:[^\s<>]*|[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+)\z/
+    DESTINATION_RE = /\A(\S*?)(?:\s+"([^"]*)")?\z/
+    RATIO_RE = %r{\A(\S+?)/(\S+)\z}
+
+    # 行内代码最多 2 个反引号（CSM §1.5）。
+    MAX_CODE_TICKS = 2
+
+    # 链接 `[]` 内允许的单个样式标签（CSM §2.3）：开标记、闭标记、节点类。
+    # 长标记在前——`**` 要先于 `*` 试。
+    STYLE_MARKERS = [
+      ["**", "**", Node::Strong],
+      ["~~", "~~", Node::Del],
+      ["~+", "+~", Node::Ins],
+      ["*", "*", Node::Emphasis]
+    ].freeze
+
+    # -- 扫描用正则 ----------------------------------------------------------
+    #
+    # 主循环先用 +LITERAL_RUN+ 整段收下普通字面；匹配不上时当前字符必是标记
+    # （两者互补），于是交给 +handle+ 逐字符分派。
 
-    module_function
+    LITERAL_RUN = /[^\\`*~\[!<$#@\n]+/
+    ANY_CHAR = /./m
 
-    def parse(source)
-      Scanner.new(source.to_s).read_nodes
+    # 预筛的最低文本长度：更短的文本即使退化也只是常数级，不值得为它建索引
+    # （见 maybe_closes?）。
+    PREFILTER_MIN_BYTES = 4096
+
+    TICKS = /`+/
+    STARS = /\*+/
+    TILDES = /~~/
+    INS_CLOSE = /\+~/
+    DOLLAR = /\$/
+    WIKI_CLOSE = /\]\]/
+
+    # 查找类操作的「跳板」：只停在这些字符上，其余整段跳过。
+    EMPHASIS_JUMP = /[\\`\[!*]/
+    BRACKET_JUMP = /[\\`\[\]]/
+    PAREN_JUMP = /[\\()"']/
+    CLOSE_BRACKET = /\]/
+    CLOSE_ANGLE = />/
+    # 「转义对或目标字符」：找目标字符时用它一次跳过普通字符（见 last_unescaped）。
+    ESCAPE_OR_SQUARE = /\\|\]/
+    ESCAPE_OR_PAREN = /\\|\)/
+
+    # 分派要比较的 ASCII 码（扫描位置是字节偏移，用整数比较省掉一次字符串分配）。
+    BACKSLASH = "\\".ord
+    BACKTICK = "`".ord
+    STAR = "*".ord
+    OPEN_SQUARE = "[".ord
+    CLOSE_SQUARE = "]".ord
+    OPEN_PAREN = "(".ord
+    CLOSE_PAREN = ")".ord
+    EXCLAMATION = "!".ord
+    DQUOTE = '"'.ord
+    SQUOTE = "'".ord
+
+    # 解析行内文本，返回行内节点数组。
+    #
+    # * +styles:+ 为 +false+ 时不再识别样式标签（`*` `**` `~~` `~+`）——样式不得
+    #   嵌套（CSM §1.7）；
+    # * +literal:+ 为 +true+ 时只识别转义与 `#{}` 插值，其余一律按字面，用于
+    #   链接的 `[]` 内容（CSM §2.3）。
+    def self.parse(text, styles: true, literal: false)
+      new(styles: styles, literal: literal).parse(text)
     end
 
-    class Scanner
-      def initialize(text)
-        @text = text
-        @len = text.length
-        @pos = 0
-      end
+    def initialize(styles: true, literal: false)
+      @styles = styles
+      @literal = literal
+    end
 
-      def read_nodes
-        nodes = []
-        while @pos < @len
-          node = read_node
-          nodes << node if node
+    def parse(text)
+      @scan = StringScanner.new(text.to_s)
+      @nodes = []
+      buffer = +""
+      @has_close_square = nil
+      @has_close_paren = nil
+      @close_square_ready = false
+      @close_paren_ready = false
+      @link_closer_ready = false
+
+      until @scan.eos?
+        run = @scan.scan(LITERAL_RUN)
+        if run
+          buffer << run
+          next
         end
-        nodes
+
+        char = @scan.getch
+        buffer << char unless handle(char, buffer)
       end
 
-      private
+      flush(buffer)
+      @nodes
+    end
 
-      def read_node
-        case @text[@pos]
-        when "\\" then read_escape
-        when "`" then read_code_span
-        when "!" then read_link_or_image
-        when "[" then read_link_or_image
-        when "\n" then read_break
-        when "*" then read_emphasis
-        when "_" then read_emphasis
-        else read_plain_run
-        end
+    private
+
+    # 按当前模式分派一个字符（该字符**已经被消费**），返回是否已处理。
+    #
+    # 契约：处理函数返回 +false+ 时，扫描位置必须与进入时相同——调用方会把
+    # +char+ 按字面收下。失败路径统一走 +rewind+。
+    def handle(char, buffer)
+      return literal_char(char, buffer) if @literal
+
+      case char
+      when "\\" then escape(buffer)
+      when "`" then code_span(buffer)
+      when "*" then emphasis(buffer)
+      when "~" then tilde_mark(buffer)
+      when "[" then bracket(buffer)
+      when "!" then image(buffer)
+      when "<" then autolink(buffer)
+      when "$" then math(buffer)
+      when "#" then interpolation(buffer)
+      when "@" then mention(buffer)
+      when "\n" then line_break(buffer)
       end
+    end
 
-      def read_escape
-        nxt = @text[@pos + 1]
-        if nxt && ESCAPABLE.match?(nxt)
-          @pos += 2
-          Text.new(nxt)
-        else
-          @pos += 1
-          Text.new("\\")
-        end
+    # 字面模式：只认转义、插值与换行折叠。
+    def literal_char(char, buffer)
+      case char
+      when "\\" then escape(buffer)
+      when "#" then interpolation(buffer)
+      when "\n" then line_break(buffer)
       end
+    end
 
-      def read_code_span
-        count = 1
-        count += 1 while @text[@pos + count] == "`"
-        closer = "`" * count
-        @pos += count
-        closing = @text.index(closer, @pos)
-        if closing.nil?
-          @pos -= count
-          read_plain_run
-        else
-          content = @text[@pos...closing].gsub(/\A +| +\z/, "").gsub(/\n/, " ")
-          @pos = closing + count
-          Code.new(content)
-        end
+    # 行内文本里的 `\`：行尾是硬换行，否则按 Markdown 转义语义（CSM §3.11）。
+    def escape(buffer)
+      following = @scan.check(ANY_CHAR)
+      return false if following.nil?
+
+      if following == "\n"
+        @scan.skip(ANY_CHAR)
+        emit(buffer, Node::HardBreak.new)
+        return true
+      end
+
+      return false unless ESCAPABLE.include?(following)
+
+      @scan.skip(ANY_CHAR)
+      buffer << following
+      true
+    end
+
+    # 软换行折叠（CSM §1.1）：前一个字符是 CJK 标点则直接相连，否则折叠为一个空格。
+    def line_break(buffer)
+      buffer << " " unless cjk_punctuation?(char_before(@scan.pos, 1))
+      true
+    end
+
+    # `` `代码` `` / ``` ``代码`` ```（CSM §1.5）。内容按字面处理。
+    def code_span(buffer)
+      start = @scan.pos
+      ticks = 1 + @scan.skip(TICKS).to_i
+      return rewind(start) if ticks > MAX_CODE_TICKS
+
+      closing = find_run(TICKS, ticks)
+      return rewind(start) if closing.nil?
+
+      body_start = start + ticks - 1
+      code = @scan.string.byteslice(body_start, closing - body_start)
+      @scan.pos = closing + ticks
+      emit(buffer, Node::CodeSpan.new(code))
+      true
+    end
+
+    # `*斜体*` / `**加粗**`（CSM §1.7）。
+    #
+    # 三个条件同时满足才成立：定界符数量相同（`**` 只配 `**`）、开 `*` 的右边与
+    # 闭 `*` 的左边都是非空白、且强调不嵌套（内部不再识别 `*`）。任一不满足就把
+    # 整个定界符串按字面收下，不退化成更短的定界符。
+    def emphasis(buffer)
+      count = 1 + @scan.skip(STARS).to_i
+      # 查找会移动扫描位置，失败路径要回到这里，所以先把内容起点定住。
+      body_start = @scan.pos
+      return literal_emphasis(buffer, count, body_start) unless @styles && count <= 2
+      return literal_emphasis(buffer, count, body_start) if blank?(@scan.check(ANY_CHAR))
+
+      closing = find_emphasis_close(count, body_start)
+      return literal_emphasis(buffer, count, body_start) if closing.nil?
+
+      inner = @scan.string.byteslice(body_start, closing - body_start)
+      @scan.pos = closing + count
+      klass = count == 2 ? Node::Strong : Node::Emphasis
+      emit(buffer, klass.new(children: InlineParser.parse(inner, styles: false)))
+      true
+    end
+
+    # 定界符不成立，整串按字面收下（CSM §1.7 不作退化），扫描位置回到 +from+。
+    def literal_emphasis(buffer, count, from)
+      @scan.pos = from
+      buffer << ("*" * count)
+      true
+    end
+
+    # `~~删除~~`（`<del>`）与 `~+增加+~`（`<ins>`）（CSM §1.8）。
+    def tilde_mark(buffer)
+      return false unless @styles
+
+      start = @scan.pos
+      if @scan.check(/~/)
+        @scan.skip(/~/)
+        body_start = @scan.pos
+        closing = find_sequence(TILDES, body_start)
+        return rewind(start) if closing.nil?
+
+        inner = @scan.string.byteslice(body_start, closing - body_start)
+        @scan.pos = closing + 2
+        emit(buffer, Node::Del.new(children: InlineParser.parse(inner)))
+        true
+      elsif @scan.check(/\+/)
+        @scan.skip(/\+/)
+        body_start = @scan.pos
+        closing = find_sequence(INS_CLOSE, body_start)
+        return rewind(start) if closing.nil?
+
+        inner = @scan.string.byteslice(body_start, closing - body_start)
+        @scan.pos = closing + 2
+        emit(buffer, Node::Ins.new(children: InlineParser.parse(inner)))
+        true
+      else
+        false
+      end
+    end
+
+    # `[` 家族：WikiLink、进度条、度量、链接/行内引用。整族共用同一个失败回退点——
+    # 失败时只消费掉的那个 `[` 由调用方按字面收下。
+    def bracket(buffer)
+      start = @scan.pos
+      if @scan.check(/\[/)
+        @scan.skip(/\[/)
+        wiki_link(buffer, start)
+      elsif @scan.check(/->/)
+        @scan.skip(/->/)
+        bar(buffer, Node::Progress, start)
+      elsif @scan.check(/=/)
+        @scan.skip(/=/)
+        bar(buffer, Node::Meter, start)
+      else
+        link(buffer)
+      end
+    end
+
+    def wiki_link(buffer, start)
+      body_start = @scan.pos
+      closing = find_sequence(WIKI_CLOSE, body_start)
+      return rewind(start) if closing.nil?
+
+      inner = @scan.string.byteslice(body_start, closing - body_start)
+      @scan.pos = closing + 2
+      target, _, label = inner.partition("|")
+      label = nil if label.empty?
+      # label 的策略与一般链接的文本相同：最多一个紧邻的样式标签，其余按字面
+      # （CSM §2.1、§2.3）。
+      emit(buffer, Node::WikiLink.new(target, label: label, children: link_label_nodes(label || target)))
+      true
+    end
+
+    # `[=m/n]` → `<meter>`，`[->m/n]` → `<progress>`（CSM §1.10）。
+    def bar(buffer, klass, start)
+      found = @scan.scan_until(CLOSE_BRACKET)
+      return rewind(start) if found.nil?
+
+      ratio = found.byteslice(0, found.bytesize - 1)
+      match = RATIO_RE.match(ratio)
+      return rewind(start) if match.nil?
+
+      emit(buffer, klass.new(match[1], match[2], children: literal_nodes(ratio)))
+      true
+    end
+
+    # `[文本](uri "title")` → `<a>`；`[文本](@uri)` → `<q>`（CSM §1.9、§2.3）。
+    def link(buffer)
+      start = @scan.pos
+      return rewind(start) unless maybe_link?(start - 1)
+
+      closing = matching_bracket(start - 1)
+      return rewind(start) if closing.nil?
+      return rewind(start) unless @scan.string.getbyte(closing + 1) == OPEN_PAREN
+
+      paren = matching_paren(closing + 1)
+      return rewind(start) if paren.nil?
+
+      string = @scan.string
+      label = string.byteslice(start, closing - start)
+      destination = string.byteslice(closing + 2, paren - closing - 2)
+      @scan.pos = paren + 1
+      emit(buffer, build_link(destination, label))
+      true
+    end
+
+    # `![alt](uri "title")` → `<img>`（CSM §2.3）。
+    def image(buffer)
+      start = @scan.pos
+      return rewind(start) unless @scan.check(/\[/)
+
+      @scan.skip(/\[/)
+      open = @scan.pos - 1
+      return rewind(start) unless maybe_link?(open)
+
+      closing = matching_bracket(open)
+      return rewind(start) if closing.nil?
+      return rewind(start) unless @scan.string.getbyte(closing + 1) == OPEN_PAREN
+
+      paren = matching_paren(closing + 1)
+      return rewind(start) if paren.nil?
+
+      string = @scan.string
+      alt = string.byteslice(open + 1, closing - open - 1)
+      destination = string.byteslice(closing + 2, paren - closing - 2)
+      uri, title = split_destination(destination)
+      @scan.pos = paren + 1
+      emit(buffer, Node::Image.new(uri, alt: alt, title: title, children: literal_nodes(alt)))
+      true
+    end
+
+    # `<uri>` / `<mailto:a@b.c>` → `<a>`（CSM §2.3）。
+    def autolink(buffer)
+      start = @scan.pos
+      found = @scan.scan_until(CLOSE_ANGLE)
+      return rewind(start) if found.nil?
+
+      inner = found.byteslice(0, found.bytesize - 1)
+      return rewind(start) if inner.empty? || !AUTOLINK_RE.match?(inner)
+
+      emit(buffer, Node::Link.new(inner, children: literal_nodes(inner)))
+      true
+    end
+
+    # `$\TeX$` → 行内 `<span class="math">`（CSM §1.11）。`$$` 属于块级公式，这里按字面处理。
+    def math(buffer)
+      start = @scan.pos
+      return rewind(start) if @scan.check(DOLLAR)
+
+      closing = find_sequence(DOLLAR, start)
+      return rewind(start) if closing.nil?
+
+      tex = @scan.string.byteslice(start, closing - start)
+      return rewind(start) if tex.empty?
+
+      @scan.pos = closing + 1
+      emit(buffer, Node::Math.new(tex, children: literal_nodes(tex)))
+      true
+    end
+
+    # `#{expr}` → 插值节点（CSM §3.13）。只保存表达式原文，不求值。
+    #
+    # 边界交给 Prism 判定：把从 `#{` 起的剩余文本包进一个双引号字符串字面量，
+    # Prism 给出的插值节点 location 就是 `#{}` 的范围。嵌套 `{}`、字符串与注释
+    # 里的 `}` 由 Ruby 自己的词法处理，不需要自研扫描器（CSM §3.12）。
+    #
+    # 位置算式（`start` 是 `{` 的字节位置，`length` 是 `#{expr}` 的字节长度）：
+    # `#{expr}` 的起点是 `start - 1`，表达式是它去掉 `#{` 与 `}` 的中间段。
+    def interpolation(buffer)
+      start = @scan.pos
+      return rewind(start) unless @scan.check(/\{/)
+
+      length = interpolation_end(@scan.rest)
+      return rewind(start) if length.nil?
+
+      expr = @scan.string.byteslice(start + 1, length - 3)
+      @scan.pos = start + length - 1
+      emit(buffer, Node::Interpolation.new(expr))
+      true
+    end
+
+    # `@user` / `@project:x` / `@tag:kw`（CSM §2.2）。`:` 前是作用域，其后是名字。
+    #
+    # 前一个字符是词字符时不算提及（`a@b` 里的 `@` 只是文本）。
+    def mention(buffer)
+      return false if char_before(@scan.pos, 1)&.match?(/\w/)
+
+      matched = @scan.scan(MENTION_SCAN_RE)
+      return false if matched.nil?
+
+      scope, _, name = matched.partition(":")
+      emit(buffer, Node::Mention.new(name.empty? ? scope : name, kind: name.empty? ? nil : scope))
+      true
+    end
+
+    # 链接与行内引用的构造（CSM §1.9、§2.3）。
+    #
+    # `[]` 内容最多含**一个**样式标签，且必须紧邻方括号（`[*strong link*](url)`）；
+    # 其余按字面（`#{}` 插值始终解析）。链接本身处在样式标签内部时，`[]` 内容
+    # 一律按字面——样式与链接不得互相嵌套。
+    def build_link(destination, label)
+      uri, title = split_destination(destination)
+      children = link_label_nodes(label)
+
+      if uri&.start_with?("@")
+        Node::InlineQuote.new(uri[1..], children: children)
+      else
+        Node::Link.new(uri, title: title, children: children)
       end
+    end
+
+    def split_destination(destination)
+      match = DESTINATION_RE.match(destination.strip)
+      return [destination.strip, nil] if match.nil?
+
+      [match[1], match[2]]
+    end
+
+    # `[]` 内容的节点：至多一个紧邻方括号的样式标签，其余按字面。
+    def link_label_nodes(label)
+      wrapped = @styles ? wrapping_style(label) : nil
+      return literal_nodes(label) if wrapped.nil?
 
-      def read_link_or_image
-        image = @text[@pos] == "!"
-        @pos += 1 if image
-        return read_plain_run unless @text[@pos] == "["
+      klass, inner = wrapped
+      [klass.new(children: literal_nodes(inner))]
+    end
 
-        label_start = @pos + 1
-        closing = @text.index("]", label_start)
-        return read_plain_run unless closing
+    # 整个 +label+ 恰好被一个样式标签包裹时返回 +[节点类, 内文]+，否则 +nil+。
+    def wrapping_style(label)
+      STYLE_MARKERS.each do |opener, closer, klass|
+        next if label.length <= opener.length + closer.length
+        next unless label.start_with?(opener) && label.end_with?(closer)
 
-        label = @text[label_start...closing]
-        return read_plain_run unless @text[closing + 1] == "("
+        inner = label[opener.length, label.length - opener.length - closer.length]
+        next if blank?(inner[0]) || blank?(inner[-1])
+        # 内文不得再出现同族定界符（那会是第二个样式标签）
+        next if unescaped?(inner, opener[0])
 
-        dest_end = @text.index(")", closing + 1)
-        return read_plain_run unless dest_end
+        return [klass, inner]
+      end
+      nil
+    end
 
-        dest, title = split_destination(@text[(closing + 2)...dest_end])
-        @pos = dest_end + 1
-        if image
-          Image.new(dest, alt: label, title: title)
+    def literal_nodes(text)
+      InlineParser.parse(text, literal: true)
+    end
+
+    # +text+ 里是否存在未被 `\` 转义的 +char+。
+    def unescaped?(text, char)
+      cursor = 0
+      while cursor < text.length
+        if text[cursor] == "\\"
+          cursor += 2
+        elsif text[cursor] == char
+          return true
         else
-          Link.new(dest, title: title, children: InlineParser.parse(label))
+          cursor += 1
         end
       end
+      false
+    end
+
+    def flush(buffer)
+      return if buffer.empty?
 
-      def split_destination(raw)
-        raw = raw.strip
-        raw = raw[1..-2] if raw.start_with?("<") && raw.end_with?(">")
-        body = raw
-        title = nil
-        if (m = /\A(.+?)\s+(?:"([^"]*)"|'([^']*)'|\(([^)]*)\))\z/.match(raw))
-          body = m[1]
-          title = m[2] || m[3] || m[4]
+      @nodes << Node::Text.new(buffer.dup)
+      buffer.clear
+    end
+
+    def emit(buffer, node)
+      flush(buffer)
+      @nodes << node
+    end
+
+    # -- 扫描器辅助 ----------------------------------------------------------
+
+    # 让扫描位置回到 +position+ 并返回 +false+：处理函数的统一失败出口。
+    def rewind(position)
+      @scan.pos = position
+      false
+    end
+
+    # 把扫描位置向前推进到 +position+，越界时停在文末——`\` 正好是最后一个字符时，
+    # 「跳过转义对」的 +2 会多出一格（+StringScanner#pos=+ 对越界值直接抛
+    # +RangeError+）。
+    def advance_to(position)
+      size = @scan.string.bytesize
+      @scan.pos = position > size ? size : position
+    end
+
+    # 两级预筛的第一个问题：整段文本里到底有没有 `]`（C 层的 +include?+，一次，极廉）。
+    def any_close_square?
+      @has_close_square = @scan.string.include?("]") if @has_close_square.nil?
+      @has_close_square
+    end
+
+    # 同上，问的是 `)`。
+    def any_close_paren?
+      @has_close_paren = @scan.string.include?(")") if @has_close_paren.nil?
+      @has_close_paren
+    end
+
+    # +open+ 之后是否**可能**存在配对的闭定界符。
+    #
+    # 两级：先排除「整段根本没有该字符」；只有 +PREFILTER_MIN_BYTES+ 以上的文本才
+    # 进一步查「最后一个位置」——收集位置是 Ruby 层循环，短文本（绝大多数行内段）
+    # 哪怕退化也只是常数级，不值得付这个固定成本。
+    def maybe_closes?(has_any, last_position, open)
+      return false unless has_any
+      return true if @scan.string.bytesize < PREFILTER_MIN_BYTES
+
+      last = last_position
+      !last.nil? && last > open
+    end
+
+    # 链接/图片的乐观预筛：+open+（`[` 的位置）之后必须存在「未被转义、且后面紧跟
+    # `(`」的 `]`——否则既不可能是链接也不可能是图片。
+    #
+    # 少了这一步，`"[(" * 2000 + ")]" * 2000` 这类输入仍会退化：预筛只看「有没有 `]`」
+    # 是拦不住的（`]` 很多），而 `matching_bracket` 仍要一个个扫。
+    def maybe_link?(open)
+      return false unless any_close_square?
+      return true if @scan.string.bytesize < PREFILTER_MIN_BYTES
+
+      last = last_link_closer
+      !last.nil? && last > open
+    end
+
+    # 未被转义的、后面紧跟 `(` 的最后一个 `]` 的位置（没有则 +nil+）。
+    def last_link_closer
+      unless @link_closer_ready
+        @last_link_closer = last_unescaped(CLOSE_SQUARE, ESCAPE_OR_SQUARE) do |position|
+          @scan.string.getbyte(position + 1) == OPEN_PAREN
         end
-        [body, title]
-      end
-
-      # A newline preceded by two spaces is a hard break; otherwise soft break.
-      def read_break
-        # Two spaces immediately before the newline => hard break.
-        before = @text[0...@pos]
-        hard = before.end_with?("  ")
-        @pos += 1
-        hard ? Hardbreak.new : Softbreak.new
-      end
-
-      def read_emphasis
-        # Double marker -> strong, single -> emphasis.
-        if @text[@pos, 2] == "**" || @text[@pos, 2] == "__"
-          open = @text[@pos, 2]
-          idx = @pos + 2
-          closer = find_closer(idx, open[0], open.length)
-          if closer
-            inner = @text[idx...closer]
-            @pos = closer + open.length
-            Strong.new(children: InlineParser.parse(inner))
-          else
-            read_plain_run
-          end
+        @link_closer_ready = true
+      end
+      @last_link_closer
+    end
+
+    # 未被转义的最后一个 `]` 的字节位置（没有则 +nil+），供 +matching_bracket+ 预筛。
+    # 惰性算一次，之后每次预筛只是一次整数比较——不能让它拖慢常见的「配对成功」路径。
+    def last_close_square
+      unless @close_square_ready
+        @last_close_square = last_unescaped(CLOSE_SQUARE, ESCAPE_OR_SQUARE)
+        @close_square_ready = true
+      end
+      @last_close_square
+    end
+
+    # 未被转义的最后一个 `)` 的位置，供 +matching_paren+ 预筛。
+    def last_close_paren
+      unless @close_paren_ready
+        @last_close_paren = last_unescaped(CLOSE_PAREN, ESCAPE_OR_PAREN)
+        @close_paren_ready = true
+      end
+      @last_close_paren
+    end
+
+    # 按 +matching_*+ 的扫描规则找「未被转义」的最后一个 +byte+ 的位置。
+    #
+    # 只求**保守**：代码串、引号内的出现也一并记入（宁可说「有」）——预筛只用于排除
+    # 「剩余文本里根本不存在该字符」这种必然无解的情形。
+    def last_unescaped(byte, pattern)
+      string = @scan.string
+      return nil unless string.include?(byte.chr)
+
+      scanner = StringScanner.new(string)
+      last = nil
+      while (ahead = scanner.exist?(pattern))
+        at = scanner.pos + ahead - scanner.matched_size
+        if string.getbyte(at) == byte
+          last = at if !block_given? || yield(at)
+          scanner.pos = at + 1
+        elsif at + 2 <= string.bytesize
+          scanner.pos = at + 2 # 转义对：连下一个字符一起跳过
         else
-          open_ch = @text[@pos]
-          idx = @pos + 1
-          # A single marker must close on a lone delimiter, not part of "**".
-          closer = find_closer(idx, open_ch, 1, skip_double: true)
-          if closer
-            inner = @text[idx...closer]
-            @pos = closer + 1
-            Emphasis.new(children: InlineParser.parse(inner))
-          else
-            read_plain_run
-          end
+          scanner.pos = string.bytesize
+        end
+      end
+      last
+    end
+
+    # 从当前位置向后搜索 +pattern+：找到就返回匹配**起点**的字节位置，并把扫描位置
+    # 移到匹配之后；找不到返回 +nil+。
+    #
+    # 用 +exist?+ 而不是 +skip_until+——后者会把「跳过的整段」建成字符串返回，
+    # 而这里只要位置。
+    def seek(pattern)
+      ahead = @scan.exist?(pattern)
+      return nil if ahead.nil?
+
+      start = @scan.pos + ahead - @scan.matched_size
+      @scan.pos += ahead
+      start
+    end
+
+    # 从当前位置找长度恰好为 +count+ 的 +re+ 串，返回其起点；没有则 +nil+。
+    # （不等于 +count+ 的整串会被跳过，与原逐字符实现一致。）
+    def find_run(pattern, count)
+      cursor = @scan.pos
+      while seek(pattern)
+        return @scan.pos - @scan.matched_size if @scan.matched_size == count
+      end
+      @scan.pos = cursor
+      nil
+    end
+
+    # 从一个反引号串之后找**等长**的关闭串，返回其之后的位置；找不到 +nil+。
+    def skip_code_span_after(ticks)
+      while seek(TICKS)
+        return @scan.pos if @scan.matched_size == ticks
+      end
+      nil
+    end
+
+    # 找可以充当闭定界符的 `*`：长度必须与 +count+ 相同，且左侧是非空白
+    # （CSM §1.7）。跳过转义、行内代码与链接——它们的 `*` 不算定界符。
+    def find_emphasis_close(count, from)
+      @scan.pos = from
+      while (found = seek(EMPHASIS_JUMP))
+        case @scan.string.getbyte(found)
+        when BACKSLASH
+          advance_to(found + 2)
+        when BACKTICK
+          @scan.pos = found
+          @scan.pos = skip_code_span_after(@scan.skip(TICKS).to_i) || @scan.string.bytesize
+        when OPEN_SQUARE, EXCLAMATION
+          @scan.pos = link_extent(found) || found + 1
+        when STAR
+          @scan.pos = found
+          run = @scan.skip(STARS).to_i
+          return found if run == count && !blank?(char_before(found))
         end
       end
+      nil
+    end
+
+    # 找下一个未被转义的 +re+ 匹配，返回起点字节位置；找不到 +nil+。
+    # 失败时扫描位置落在文末，调用方负责 +rewind+。
+    def find_sequence(pattern, from)
+      @scan.pos = from
+      while (found = seek(pattern))
+        return found unless char_before(found) == "\\"
+      end
+      nil
+    end
+
+    # 从 `[` 的位置找配对的 `]`，跳过嵌套、转义与行内代码。
+    def matching_bracket(open)
+      # 乐观预筛：`[` 之后没有未被转义的 `]` 时必然找不到配对。少了这一步，
+      # 「大量未闭合 `[`」的输入会退化成 O(n²)——每个 `[` 都要扫到文末。
+      return nil unless maybe_closes?(any_close_square?, last_close_square, open)
 
-      # Find the index of a closing delimiter, scanning from +from+. With
-      # +skip_double+, a doubled delimiter is skipped (so "*a **b** c*" resolves
-      # the outer emphasis to the final lone '*', recursing into the strong).
-      def find_closer(from, ch, width, skip_double: false)
-        i = from
-        while i < @len
-          if @text[i] == ch
-            if width > 1
-              return i if @text[i, width] == ch * width
-            elsif @text[i, 2] == ch * 2
-              i += 2 # skip doubled marker entirely
-              next
-            elsif @text[i, width] == ch * width
-              return i
-            end
-          end
-          i += 1
+      depth = 0
+      @scan.pos = open
+      while (found = seek(BRACKET_JUMP))
+        case @scan.string.getbyte(found)
+        when BACKSLASH
+          advance_to(found + 2)
+        when BACKTICK
+          @scan.pos = found
+          @scan.pos = skip_code_span_after(@scan.skip(TICKS).to_i) || @scan.string.bytesize
+        when OPEN_SQUARE
+          depth += 1
+        when CLOSE_SQUARE
+          depth -= 1
+          return found if depth.zero?
         end
-        nil
       end
+      nil
+    end
+
+    def matching_paren(open)
+      return nil unless maybe_closes?(any_close_paren?, last_close_paren, open)
+
+      matching_pair(open, OPEN_PAREN, CLOSE_PAREN)
+    end
+
+    # 若 +pos+（`[` 或 `!` 的位置）处是一个链接/图片，返回它之后的位置；否则 +nil+。
+    def link_extent(pos)
+      open = @scan.string.getbyte(pos) == EXCLAMATION ? pos + 1 : pos
+      return nil unless @scan.string.getbyte(open) == OPEN_SQUARE
+      return nil unless maybe_link?(open)
+
+      closing = matching_bracket(open)
+      return nil if closing.nil? || @scan.string.getbyte(closing + 1) != OPEN_PAREN
 
-      def read_plain_run
-        start = @pos
-        while @pos < @len && !SPECIAL.match?(@text[@pos])
-          @pos += 1
+      paren = matching_paren(closing + 1)
+      paren && paren + 1
+    end
+
+    # 从 +open+（开括号的位置）找配对闭括号；跳过嵌套、反斜杠转义与引号内的括号。
+    # 定界符用 ASCII 码比较（扫描位置是字节偏移）。
+    def matching_pair(open, opener, closer)
+      depth = 0
+      quote = nil
+      @scan.pos = open
+      while (found = seek(PAREN_JUMP))
+        byte = @scan.string.getbyte(found)
+        if byte == BACKSLASH
+          advance_to(found + 2)
+          next
+        end
+        if quote
+          quote = nil if byte == quote
+          next
         end
-        # Guarantee forward progress so a special char that couldn't be parsed
-        # as its own construct is treated as literal text.
-        @pos += 1 if @pos == start
-        Text.new(@text[start...@pos])
+
+        case byte
+        when DQUOTE, SQUOTE then quote = byte
+        when opener then depth += 1
+        when closer
+          depth -= 1
+          return found if depth.zero?
+        end
+      end
+      nil
+    end
+
+    # +position+（默认当前位置）之前第 +offset+ 个字符（+0+ = 紧邻的上一个字符，
+    # 调用方传 +1+ 表示「跳过紧邻的那一个再看」）；越过文本开头时返回 +nil+。
+    # UTF-8 下最多回退 3 个字节，不做多余分配。
+    def char_before(position = @scan.pos, offset = 0)
+      string = @scan.string
+      index = position
+      (offset + 1).times do
+        return nil if index <= 0
+
+        index -= 1
+        index -= 1 while index.positive? && (string.getbyte(index) & 0xC0) == 0x80
+      end
+
+      finish = position
+      string.byteslice(index, finish - index)
+    end
+
+    def cjk_punctuation?(char)
+      !char.nil? && CJK_PUNCTUATION.match?(char)
+    end
+
+    # 空格或换行（含制表符）。强调定界符的内侧不能是它们（CSM §1.7）。
+    def blank?(char)
+      char.nil? || char.match?(/\s/)
+    end
+
+    # 用 Prism 找出从 +rest+（`#{` 之后的剩余文本）起的 `#{...}` 的**字节长度**；
+    # 不是插值则返回 nil。
+    #
+    # 构造出的字面量里，插值之后若出现裸 `"`，整段就不再是合法 Ruby——Prism
+    # 会报错，但错误恢复仍给出插值节点，边界照常可读。代价是每个插值解析一次
+    # 剩余文本（各次解析互不影响）。
+    def interpolation_end(rest)
+      source = +'"#'
+      source << rest
+      source << '"'
+      result = Prism.parse(source)
+      segment = first_embedded_statement(result.value)
+      return nil if segment.nil?
+
+      slice = segment.location.slice
+      # 未闭合的 `#{` 会一直吞到字符串结尾，此时的 slice 不以 `}` 收尾。
+      return nil unless slice.end_with?("}")
+
+      slice.bytesize
+    end
+
+    # 先序遍历，取第一个字符串插值节点。
+    def first_embedded_statement(node)
+      return nil unless node
+      return node if node.is_a?(Prism::EmbeddedStatementsNode)
+
+      node.compact_child_nodes.each do |child|
+        found = first_embedded_statement(child)
+        return found if found
       end
+      nil
     end
   end
 end