15极致 Pull 模式:扁平事件流,像 pulldown

// PullParser 是一个可复用的单线程解析器:构建一次,解析多篇。
type PullParser struct {
  cfg *Config
}

// Render 把 src 的 HTML 直接流式写入 w——不构造整篇文档大小的中间字符串。
// w 被包一层 bufio.Writer(既满足内部 Writer 约束的 WriteString/WriteByte,又批量落盘/落网)。
func (p *PullParser) Render(w io.Writer, src string) error {
  bw := bufio.NewWriter(w)
  p.renderTo(bw, src)
  return bw.Flush()
}

// Inline 是行内层的一个【扁平事件/令牌】——与 pulldown-cmark 的 Start/End 事件、
// markdown-it 的 _open/_close token 同款,不再是拥有 Children 的树。
//
//   - 成对节点(Emph / Strong / Link / Custom)由两枚令牌表达:Close=false 的开、
//     Close=true 的闭,二者之间的内容就是流里紧随其后的那些令牌;
//   - 叶子令牌(Text / CodeSpan)Close 恒为 false,自带内容。
//
// 这样行内也彻底 pull 化:线性产出、线性渲染,零树、零 Children 切片分配——
// 与块级的事件流一脉相承(见 PARSER-NOTES.md「为什么是 pull 而非 AST 全量树」)。
type Inline struct {
  Kind  NodeKind
  Close bool   // 成对节点:false=开令牌,true=闭令牌;叶子令牌恒 false
  Text  string // KindText / KindCodeSpan 的字面内容
  Dest  string // KindLink 开令牌的目标 URL
  Tag   string // KindCustom 开令牌的类型标识:渲染器据此查找对应渲染函数
}

// processEmphasis 第二遍:把待定分隔符配对成 Emph/Strong。
func processEmphasis(items []inlineItem) []inlineItem {
  for {
    matched := false
    for ci := 0; ci < len(items); ci++ {
      closer := items[ci].delim
      if !closer.isDelim || !closer.canClose || closer.length == 0 {
        continue
      }
      oi := -1
      for k := ci - 1; k >= 0; k-- {
        opener := items[k].delim
        if opener.isDelim && opener.canOpen && opener.length > 0 && opener.char == closer.char {
          oi = k
          break
        }
      }
      if oi < 0 {
        continue
      }

      use := 1
      kind := KindEmph
      if items[oi].delim.length >= 2 && items[ci].delim.length >= 2 {
        use = 2
        kind = KindStrong
      }
      items[oi].delim.length -= use
      items[ci].delim.length -= use

      // 扁平化:不再把中间内容收进 Children,而是在其两侧【括入】一枚开令牌、一枚闭令牌。
      // 中间 items[oi+1:ci] 原样保留(它们已是扁平令牌 / 更内层配对的结果)。
      rebuilt := make([]inlineItem, 0, len(items)+2)
      rebuilt = append(rebuilt, items[:oi]...)
      if items[oi].delim.length > 0 { // 剩余分隔符留待后续配对或最终物化
        rebuilt = append(rebuilt, items[oi])
      }
      rebuilt = append(rebuilt, inlineItem{tok: Inline{Kind: kind}}) // 开令牌
      rebuilt = append(rebuilt, items[oi+1:ci]...)
      rebuilt = append(rebuilt, inlineItem{tok: Inline{Kind: kind, Close: true}}) // 闭令牌
      if items[ci].delim.length > 0 {
        rebuilt = append(rebuilt, items[ci])
      }
      rebuilt = append(rebuilt, items[ci+1:]...)
      items = rebuilt
      matched = true
      break
    }
// … 省略 5 行；完整声明 L331–383，点击上方「浏览完整文件」

// RenderInlines 把行内 AST 写入 w,优先走覆盖表 / 自定义表,再落到内建渲染。
// RenderInlines 线性走过扁平令牌流:成对节点在开/闭令牌处分别写开/闭标签,无递归、无 Children。
// 覆盖表 / 自定义表按令牌回调,回调自行根据 tok.Close 决定写开标签还是闭标签(对齐 markdown-it 的
// renderer.rules 逐 token 语义)。
func (h *HTMLRenderer) RenderInlines(w Writer, toks []Inline) {
  for _, t := range toks {
    if fn, ok := h.overrides[t.Kind]; ok {
      fn(w, t, h)
      continue
    }
    switch t.Kind {
    case KindText:
      writeEscaped(w, t.Text)
    case KindCodeSpan:
      w.WriteString("<code>")
      writeEscaped(w, t.Text)
      w.WriteString("</code>")
    case KindEmph:
      w.WriteString(openClose(t.Close, "<em>", "</em>"))
    case KindStrong:
      w.WriteString(openClose(t.Close, "<strong>", "</strong>"))
    case KindLink:
      if t.Close {
        w.WriteString("</a>")
      } else {
        w.WriteString(`<a href="`)
        writeEscaped(w, t.Dest)
        w.WriteString(`">`)
      }
    case KindCustom:
      if fn, ok := h.custom[t.Tag]; ok {
        fn(w, t, h)
      } // 未注册:开/闭令牌不写标签,其间的内容令牌照常渲染
    }
  }
}

// PullEvent 是统一拉取事件流的一枚事件。块级与行内被摊平进同一条线性流:
// 容器/叶子/强调/链接都表现为 PullEnter … PullLeave 的配对,文本/行内代码是叶子事件。
// 这就是 pulldown-cmark 的模型——消费方线性驱动、零文档树、可随时 break。
type PullEvent struct {
  Kind    PullEventKind
  Node    NodeKind // Enter/Leave 时:哪种节点
  Text    string   // PullText / PullCode 的内容;CodeBlock 的字面内容
  Dest    string   // KindLink 的目标
  Tag     string   // KindCustom 的标识
  Info    string   // KindCodeBlock 的 info string
  Level   int      // KindHeading 层级
  Ordered bool     // KindList 是否有序
  Start   int      // KindList 起始编号
  Tight   bool     // 紧凑列表项内的段落
}

// Events 返回统一拉取事件流:块级 + 行内交织成一条线性 Enter/Leave/Text/Code 流。
// 叶子在此被展开为行内事件——真正的「端到端 pull」。调用方 `for ev := range p.Events(src)`
// 驱动,可随时 break,全程零文档树。
func (p *PullParser) Events(src string) iter.Seq[PullEvent] {
  return func(yield func(PullEvent) bool) {
    bp := newBlockState(p.cfg)
    emit := func(events []BlockEvent) bool {
      for i := range events {
        ev := events[i]
        switch ev.Kind {
        case EvOpen:
          if !yield(PullEvent{Kind: PullEnter, Node: ev.Container, Ordered: ev.Ordered, Start: ev.Start}) {
            return false
          }
        case EvClose:
          if !yield(PullEvent{Kind: PullLeave, Node: ev.Container, Ordered: ev.Ordered, Start: ev.Start}) {
            return false
          }
        default: // EvLeaf
          if !p.emitLeaf(ev.Leaf, yield) {
            return false
          }
        }
      }
      return true
    }
    rest := src
    for {
      i := strings.IndexByte(rest, '\n')
      if i < 0 {
        break
      }
      if !emit(bp.feedLine(strings.TrimSuffix(rest[:i], "\r"))) {
        return
      }
      rest = rest[i+1:]
    }
    if rest != "" {
      if !emit(bp.feedLine(strings.TrimSuffix(rest, "\r"))) {
        return
      }
    }
    emit(bp.closeAll())
  }
}

// InlineParser 是行内解析器:触发字符 → 规则,外加全局后处理链。无状态、可并发共享。
// statePool 复用 InlineState(含 items 暂存数组):一篇文档几十上百个叶子块共享少数几个
// scratch buffer,而不是每块新分配一份。sync.Pool 天然并发安全,fan-out 模式下多 worker 并发调用也无碍。
// triggers 是「哪些字节可能开启一个行内构造」的位图,用于无标记快速路径。
type InlineParser struct {
  rules     map[byte][]InlineRule
  post      []inlinePost
  triggers  [256]bool
  statePool sync.Pool
}