mdom 0.2.0 → 0.3.0

data/lib/mdom/node.rb

@@ -1,254 +1,732 @@
 # frozen_string_literal: true
 
+# Markdown DOM：把 Markdown 文本解析为语法树（AST）的顶层命名空间。
+require_relative "hooks"
+
 module MDOM
-  # Base class for every node in the Markdown tree.
+  # Markdown 语法树的节点定义。
   #
-  # A node carries a +type+ (a Symbol), an ordered list of +children+, and
-  # optional +attributes+ (a Hash). The +parent+ of a node is maintained
-  # automatically whenever a child is appended or removed.
-  class Node
-    attr_reader :type, :children, :attributes
-    attr_accessor :parent
-
-    # -- construction -------------------------------------------------------
-
-    def initialize(type, attributes: {}, children: [])
-      @type = type
-      @attributes = attributes
-      @children = []
-      @parent = nil
-      children.each { |child| append(child) }
-    end
+  # 本模块把节点能力按职责拆成若干 mixin——挂载（+Attaching+）、摘除
+  # （+Detaching+）、替换（+Replacing+）、重排（+Reordering+）、遍历
+  # （+Traversal+）、导航（+Navigation+）、判定（+Predicates+）、深度维护
+  # （+Depth+）——由 +BaseNode+ 统一混入；具体节点类型（段落、标题、列表……）
+  # 继承 +BaseNode+，只需声明自己的 +type+ 与语义。
+  #
+  # 命名遵循 Ruby 核心类（+Array+ / +Hash+）的惯例：消息名描述*接收者*做什么，
+  # 被操作的对象由参数表达，因此没有 +remove_child+ / +insert_child_at+ 这类
+  # 把宾语写进方法名的形式。
+  #
+  # 领域错误见 +Error+ 及其子类 +RootError+、+BoundaryError+、+CycleError+。
+  module Node
+    # 节点操作的错误基类。+MDOM::Node+ 里抛出的领域错误都继承它，调用方可以
+    # 只 rescue 一次（+MDOM::Node::Error+）覆盖全部。
+    class Error < StandardError; end
+
+    # 对根节点做了它没有意义的操作（根节点没有父节点，也就没有位置、兄弟）。
+    class RootError < Error; end
+
+    # 越过了兄弟边界：第一个子节点没有前一个兄弟，最后一个子节点没有后一个兄弟。
+    class BoundaryError < Error; end
+
+    # 试图把节点挂到自身或它的祖先之下，会形成环。
+    class CycleError < Error; end
+
+    # 挂载子节点：追加、前插、插入指定位置。
+    #
+    # 这些方法只负责"位置"这一半；"改换门庭"由被挂载的节点自己完成——调用
+    # +node.attach_to!+（参数是本节点）让 +node+ 自行脱离原父并认本节点为父，
+    # 本节点不去直接改写 +node+ 的状态。
+    module Attaching
+      # 把 +node+ 追加到子列表的末尾。
+      #
+      # 若 +node+ 原本挂在另一个父节点下，+node+ 会先脱离原来的父节点，从而
+      # 维持“一个子节点只属于一个父节点”的不变式。
+      #
+      # 参数：
+      # * +node+ —— 要追加的节点（+BaseNode+）。
+      #
+      # 返回值：+self+，便于链式调用。
+      #
+      # 抛出：
+      # * +ArgumentError+ —— +node+ 为 +nil+。
+      # * +CycleError+ —— +node+ 是 +self+ 自身或其祖先（挂接会形成环）。
+      def <<(node)
+        assert_attachable!(node)
+        node.attach_to!(self)
+        children << node
+        self
+      end
 
-    # -- children -----------------------------------------------------------
+      # 依次追加多个节点。
+      #
+      # 等价于对每个参数调用 #<<，并保留参数给出的顺序。
+      #
+      # 参数：
+      # * +nodes+ —— 零个或多个要追加的节点（+BaseNode+）。
+      #
+      # 返回值：+self+，便于链式调用。
+      #
+      # 抛出：
+      # * +ArgumentError+ —— 任一节点为 +nil+。
+      # * +CycleError+ —— 某个节点是 +self+ 自身或其祖先。
+      def append(*nodes)
+        nodes.each { |node| self << node }
+        self
+      end
 
-    # Append +child+ to the end of this node's children. Reparents +child+
-    # away from any previous parent. Returns +self+ so it can be chained.
-    def append(child)
-      return self if child.nil?
+      # 把 +node+ 插到子列表的最前面。
+      #
+      # 参数：
+      # * +node+ —— 要插入的节点（+BaseNode+）。
+      #
+      # 返回值：+self+，便于链式调用。
+      #
+      # 抛出：
+      # * +ArgumentError+ —— +node+ 为 +nil+。
+      # * +CycleError+ —— +node+ 是 +self+ 自身或其祖先。
+      def prepend(node)
+        assert_attachable!(node)
+        node.attach_to!(self)
+        children.unshift(node)
+        self
+      end
 
-      child.remove if child.parent
-      child.parent = self
-      @children << child
-      self
-    end
-    alias << append
+      # 在 +index+ 位置插入 +node+。
+      #
+      # 参数顺序与 Array#insert 一致（位置在前、元素在后），索引惯例也相同：
+      #
+      # * 非负值：直接作为插入位置，+0+ 表示插到最前面，+children.size+ 表示
+      #   追加到末尾；
+      # * 负值：从末尾往前计数，+-1+ 表示追加到末尾（等价于 #<<），+-2+ 表示
+      #   插到最后一个子节点之前。
+      #
+      # 合法取值为 +-children.size-1+ 到 +children.size+；超出该范围会抛出 +IndexError+，
+      # 而不是像 Array#insert 那样在右侧补 +nil+（+nil+ 不是合法的子节点）。
+      #
+      # 参数：
+      # * +index+ —— 插入位置（+Integer+，可为负），取值 +-children.size-1+
+      #   到 +children.size+。
+      # * +node+ —— 要插入的节点（+BaseNode+）。
+      #
+      # 返回值：+self+，便于链式调用。
+      #
+      # 抛出：
+      # * +TypeError+ —— +index+ 不是 +Integer+。
+      # * +IndexError+ —— +index+ 超出合法范围。
+      # * +ArgumentError+ —— +node+ 为 +nil+。
+      # * +CycleError+ —— +node+ 是 +self+ 自身或其祖先。
+      def insert(index, node)
+        raise TypeError, "index must be an Integer" unless index.is_a?(Integer)
+
+        assert_attachable!(node)
+        node.unlink! # 先让 node 脱离，尺寸与下标才有确定含义
+        check_index!(index)
+        node.attach_to!(self)
+        children.insert(index, node)
+        self
+      end
 
-    # Yield each child in order. Returns an Enumerator when no block is given.
-    def each_child(&block)
-      return enum_for(:each_child) unless block
+      # 把 +node+ 插到 +relative+（本节点的一个直接子节点）之前。
+      #
+      # +relative+ 必须已经是本节点的直接子节点，否则抛出 +ArgumentError+。
+      # 若 +node+ 本来就是本节点的子节点，会先让它脱离、再重新定位 +relative+，
+      # 因此不会因为下标左移而插错位置。
+      #
+      # 参数：
+      # * +node+ —— 要插入的节点（+BaseNode+）。
+      # * +relative+ —— 作为插入锚点的直接子节点（+BaseNode+），不能为 +nil+。
+      #
+      # 返回值：+self+，便于链式调用。
+      #
+      # 抛出：
+      # * +ArgumentError+ —— +relative+ 为 +nil+，或不是本节点的直接子节点。
+      # * +ArgumentError+ —— +node+ 与 +relative+ 是同一个节点。
+      # * +ArgumentError+ —— +node+ 为 +nil+。
+      # * +CycleError+ —— +node+ 是 +self+ 自身或其祖先。
+      def insert_before(node, relative)
+        raise ArgumentError, "relative cannot be nil" if relative.nil?
+        raise ArgumentError, "relative is not a child of this node" unless index(relative)
+        raise ArgumentError, "node and relative must be different nodes" if node.equal?(relative)
+
+        assert_attachable!(node)
+        node.unlink!
+        insert(index(relative), node)
+      end
 
-      @children.each(&block)
-      self
+      # 把 +node+ 插到 +relative+（本节点的一个直接子节点）之后。
+      #
+      # +relative+ 必须已经是本节点的直接子节点，否则抛出 +ArgumentError+。
+      # 若 +relative+ 是最后一个子节点，+node+ 会被追加到末尾。
+      #
+      # 参数：
+      # * +node+ —— 要插入的节点（+BaseNode+）。
+      # * +relative+ —— 作为插入锚点的直接子节点（+BaseNode+），不能为 +nil+。
+      #
+      # 返回值：+self+，便于链式调用。
+      #
+      # 抛出：
+      # * +ArgumentError+ —— +relative+ 为 +nil+，或不是本节点的直接子节点。
+      # * +ArgumentError+ —— +node+ 与 +relative+ 是同一个节点。
+      # * +ArgumentError+ —— +node+ 为 +nil+。
+      # * +CycleError+ —— +node+ 是 +self+ 自身或其祖先。
+      def insert_after(node, relative)
+        raise ArgumentError, "relative cannot be nil" if relative.nil?
+        raise ArgumentError, "relative is not a child of this node" unless index(relative)
+        raise ArgumentError, "node and relative must be different nodes" if node.equal?(relative)
+
+        assert_attachable!(node)
+        node.unlink!
+        insert(index(relative) + 1, node)
+      end
     end
-    alias each each_child
 
-    def children?
-      !@children.empty?
-    end
+    # 摘除子节点。
+    module Detaching
+      # 把直接子节点 +node+ 摘除。
+      #
+      # 当 +node+ 不是本节点的直接子节点（或为 +nil+）时不做任何事。摘除成功后，
+      # +node+ 的 +parent+ 被置为 +nil+，其子树的 +depth+ 也会重新计算。
+      #
+      # 参数：
+      # * +node+ —— 要摘除的子节点（+BaseNode+ 或 +nil+）。
+      #
+      # 返回值：+self+，便于链式调用。
+      def remove(node)
+        return self if node.nil?
+
+        node.unlink! if children.delete(node)
+        self
+      end
+
+      # 摘除并返回位于 +index+ 的子节点。
+      #
+      # +index+ 遵循 Array#delete_at 的索引惯例：非负值直接作为位置，负值
+      # 从末尾往前计数（+-1+ 表示最后一个子节点）。越界时返回 +nil+。
+      #
+      # 参数：
+      # * +index+ —— 子节点下标（+Integer+，可为负）。
+      #
+      # 返回值：被摘除的子节点；+index+ 越界时返回 +nil+。
+      #
+      # 抛出：+TypeError+，当 +index+ 不是 +Integer+ 时（例如传入 Range）。
+      #
+      # 注意：本方法只从 +children+ 中移除节点，不会重置它的 +parent+ 指针；
+      # 若需要该节点完整脱离（+parent+ 也置空、+depth+ 重算），请对返回值
+      # 再调用 #unlink!。
+      def extract_at(index)
+        raise TypeError, "index must be an Integer" unless index.is_a?(Integer)
+
+        children.delete_at(index)
+      end
 
-    # Remove this node from its current parent, if any. Returns +self+.
-    def remove
-      @parent&.children&.delete(self)
-      @parent = nil
-      self
+      # 把本节点从其父节点上完整摘除，并重置本子树的 +depth+。
+      #
+      # 摘除是双向的：既从父节点的 +children+ 中删除自己，也把自己的 +parent+
+      # 置为 +nil+。若本节点已是根（+parent+ 为 +nil+），则只重算 +depth+。
+      #
+      # 返回值：+self+，便于链式调用。
+      def unlink!
+        @parent&.children&.delete(self)
+        @parent = nil
+        sync_depth!
+        self
+      end
     end
 
-    # -- tree navigation ----------------------------------------------------
+    # 替换子节点，或替换、包装节点自身。
+    module Replacing
+      # 用 +replacement+ 顶替本节点的一个直接子节点 +child+。
+      #
+      # +child+ 与 +replacement+ 都会先从各自的原父节点脱离，然后由
+      # +replacement+ 占据 +child+ 原来的位置，从而保持兄弟节点的相对顺序。
+      #
+      # 参数：
+      # * +child+ —— 要被顶替的直接子节点（+BaseNode+）。
+      # * +replacement+ —— 替换用的新节点（+BaseNode+）。
+      #
+      # 返回值：+self+，便于链式调用。当 +child+ 不是本节点的直接子节点，
+      # 或 +replacement+ 就是 +child+ 本身时，不做任何改动并返回 +self+。
+      #
+      # 抛出：
+      # * +ArgumentError+ —— +replacement+ 为 +nil+。
+      # * +CycleError+ —— +replacement+ 是 +self+ 自身或其祖先。
+      def replace(child, replacement)
+        idx = index(child)
+        return self if idx.nil? || replacement.equal?(child)
+
+        assert_attachable!(replacement)
+        replacement.unlink!
+        idx = index(child)
+        return self unless idx
+
+        child.unlink!
+        replacement.attach_to!(self)
+        children.insert(idx, replacement)
+        self
+      end
+
+      # 在父节点中，把本节点替换为 +node+。
+      #
+      # 内部转发给父节点的 #replace。
+      #
+      # 参数：
+      # * +node+ —— 用于替换的新节点（+BaseNode+）。
+      #
+      # 返回值：+node+（注意：不是 +self+）。
+      #
+      # 抛出：
+      # * +RootError+ —— 本节点是根节点（没有父节点），无法被替换。
+      # * +ArgumentError+ —— +node+ 为 +nil+。
+      # * +CycleError+ —— +node+ 是本节点的祖先。
+      def replace_with(node)
+        raise RootError, "cannot replace the root node" unless @parent
+
+        @parent.replace(self, node)
+        node
+      end
 
-    # The topmost ancestor (a node whose parent is nil).
-    def root
-      node = self
-      node = node.parent while node.parent
-      node
+      # 用 +wrapper+ 把本节点包装起来。
+      #
+      # 包装后：+wrapper+ 占据本节点原来的位置，而本节点成为 +wrapper+ 的
+      # 子节点（唯一子节点）。
+      #
+      # 参数：
+      # * +wrapper+ —— 包装节点（+BaseNode+），不能为 +nil+。
+      #
+      # 返回值：+wrapper+（注意：不是 +self+）。
+      #
+      # 抛出：
+      # * +RootError+ —— 本节点是根节点，无法被包装。
+      # * +ArgumentError+ —— +wrapper+ 为 +nil+。
+      # * +CycleError+ —— +wrapper+ 是本节点自身或其祖先。
+      def wrap_with(wrapper)
+        raise RootError, "cannot wrap the root node" unless @parent
+        raise ArgumentError, "wrapper cannot be nil" if wrapper.nil?
+
+        @parent.replace(self, wrapper) # wrapper 顶替本节点原来的位置
+        wrapper << self
+        wrapper
+      end
     end
 
-    # Depth in the tree: 0 at the root, 1 for its direct children, etc.
-    def depth
-      return 0 if @parent.nil?
+    # 在同级子节点之间调换位置。
+    module Reordering
+      # 把本节点与它前一个兄弟节点交换位置。
+      #
+      # 返回值：+self+，便于链式调用。
+      #
+      # 抛出：
+      # * +RootError+ —— 本节点是根节点。
+      # * +BoundaryError+ —— 本节点已经是第一个子节点。
+      def slide_prev
+        raise RootError, "cannot slide the root node" unless @parent
+
+        idx = position
+        raise BoundaryError, "the first child cannot slide prev" if idx.zero?
+
+        @parent.swap_children(idx - 1, idx)
+        self
+      end
 
-      @parent.depth + 1
+      # 把本节点与它后一个兄弟节点交换位置。
+      #
+      # 返回值：+self+，便于链式调用。
+      #
+      # 抛出：
+      # * +RootError+ —— 本节点是根节点。
+      # * +BoundaryError+ —— 本节点已经是最后一个子节点。
+      def slide_next
+        raise RootError, "cannot slide the root node" unless @parent
+
+        idx = position
+        raise BoundaryError, "the last child cannot slide next" if idx == @parent.children.size - 1
+
+        @parent.swap_children(idx, idx + 1)
+        self
+      end
     end
 
-    # The chain of ancestors, closest first. Returns [] for a root node.
-    def ancestors
-      list = []
-      node = @parent
-      while node
-        list << node
-        node = node.parent
+    # 深度优先遍历。
+    module Traversal
+      # 深度优先（先序）遍历本节点及其全部后代。
+      #
+      # 遍历顺序：先产出节点自身，再依次遍历各子树。
+      #
+      # 由于 +BaseNode+ 混入了 +Enumerable+，而 +Enumerable+ 的 +map+ /
+      # +select+ / +count+ / +to_a+ 等方法都建立在 +each+ 之上，本方法产出的是
+      # 「整棵子树（含自身）」，这一点与“只遍历直接子节点”的数组直觉不同；
+      # 只想访问直接子节点时请直接使用 +children+。
+      #
+      # 参数：
+      # * 一个可选块 —— 接收每个被访问的节点。
+      #
+      # 返回值：给定块时返回 +self+；未给块时返回 +Enumerator+。
+      def each(&block)
+        return enum_for(:each) unless block
+
+        yield self
+        children.each { |child| child.each(&block) }
+        self
       end
-      list
     end
 
-    # -- traversal and query -------------------------------------------------
+    # 在树上导航与查询：祖先、父子、兄弟、下标。
+    module Navigation
+      # 本节点所在树的根节点。
+      #
+      # 根节点的特征是 +parent+ 为 +nil+。若本节点就是根，返回 +self+。
+      #
+      # 返回值：最顶层的祖先节点。
+      def root
+        node = self
+        node = node.parent while node.parent
+        node
+      end
 
-    # Depth-first (preorder) traversal that yields this node then its
-    # descendants, depth-first. Returns an Enumerator when no block is given.
-    def walk(&block)
-      return enum_for(:walk) unless block
+      # 本节点的祖先链，按由近到远排列。
+      #
+      # 返回值：祖先节点的 +Array+（第一个元素是直接父节点，最后一个元素是根节点）；
+      # 本节点是根节点时为 +[]+。
+      def ancestors
+        list = []
+        node = @parent
+        while node
+          list << node
+          node = node.parent
+        end
+        list
+      end
 
-      block.call(self)
-      @children.each { |child| child.walk(&block) }
-      self
-    end
+      # 本节点在「自己父节点」子列表中的位置。
+      #
+      # 返回值：下标（+Integer+）。
+      #
+      # 抛出：+RootError+，当本节点是根节点时（根节点没有父节点，给不出位置）。
+      def position
+        raise RootError, "the root node has no position" unless @parent
 
-    # Yield each descendant (including self) whose type matches +type+, or all
-    # nodes when no type is given. With a block given, also yields when the
-    # block returns truthy.
-    def find_all(type = nil)
-      results = []
-      walk do |node|
-        next unless type.nil? || node.type == type
-        next if block_given? && !yield(node)
+        parent_index!
+      end
 
-        results << node
+      # +node+ 在「本节点」子列表中的位置。
+      #
+      # 参数：
+      # * +node+ —— 要查询的子节点（+BaseNode+），不能为 +nil+。
+      #
+      # 返回值：下标（+Integer+）；+node+ 不是本节点的直接子节点时为 +nil+。
+      #
+      # 抛出：+ArgumentError+，当 +node+ 为 +nil+ 时。
+      def index(node)
+        raise ArgumentError, "node cannot be nil" if node.nil?
+
+        children.index(node)
       end
-      results
-    end
 
-    # The first matching descendant (or self); +type+ may be a Symbol or a
-    # callable, or a block may be supplied.
-    def find(type = nil, &block)
-      predicate =
-        if block
-          block
-        elsif type.is_a?(Symbol)
-          ->(n) { n.type == type }
-        elsif type.respond_to?(:call)
-          type
-        else
-          nil
-        end
-      walk { |node| return node if predicate && predicate.call(node) }
-      nil
-    end
+      # 第一个子节点。
+      #
+      # 返回值：+BaseNode+；没有子节点时为 +nil+。
+      def first_child
+        children.first
+      end
 
-    # Query by one or more types (Symbol or array of Symbols). Returns an array
-    # of matching nodes (including self if it matches) in document order.
-    def [](*types)
-      types = types.flatten
-      find_all.select { |n| types.include?(n.type) }
-    end
+      # 最后一个子节点。
+      #
+      # 返回值：+BaseNode+；没有子节点时为 +nil+。
+      def last_child
+        children.last
+      end
 
-    # -- mutation -----------------------------------------------------------
+      # 本节点的所有兄弟节点（即父节点的全部子节点，「含自身」）。
+      #
+      # 返回值：节点 +Array+。注意返回的是「副本」，改动它不会影响树；要增删兄弟
+      # 关系请使用本类提供的变更方法。
+      #
+      # 抛出：+RootError+，当本节点是根节点时（根节点没有兄弟）。
+      def siblings
+        raise RootError, "the root node has no siblings" unless @parent
 
-    # Insert +node+ as the sibling immediately before this node.
-    def insert_before(node)
-      parent = @parent
-      raise "cannot insert before a root node" if parent.nil?
+        @parent.children.dup
+      end
 
-      node.remove if node.parent
-      idx = parent.children.index(self)
-      parent.children.insert(idx, node)
-      node.parent = parent
-      self
-    end
+      # 前一个兄弟节点。
+      #
+      # 返回值：前一个兄弟节点（+BaseNode+）。
+      #
+      # 抛出：
+      # * +RootError+ —— 本节点是根节点（没有兄弟）。
+      # * +BoundaryError+ —— 本节点已经是第一个子节点（没有前一个兄弟）。
+      def previous_sibling
+        raise RootError, "the root node has no siblings" unless @parent
 
-    # Insert +node+ as the sibling immediately after this node.
-    def insert_after(node)
-      parent = @parent
-      raise "cannot insert after a root node" if parent.nil?
+        idx = position
+        return @parent.children[idx - 1] if idx.positive?
 
-      node.remove if node.parent
-      idx = parent.children.index(self)
-      parent.children.insert(idx + 1, node)
-      node.parent = parent
-      self
-    end
+        raise BoundaryError, "the first child has no previous sibling"
+      end
 
-    # Replace this node in its parent with +node+. Returns +node+.
-    def replace(node)
-      parent = @parent
-      raise "cannot replace a root node" if parent.nil?
-
-      node.remove if node.parent
-      idx = parent.children.index(self)
-      parent.children[idx] = node
-      node.parent = parent
-      @parent = nil
-      node
-    end
+      # 后一个兄弟节点。
+      #
+      # 返回值：后一个兄弟节点（+BaseNode+）。
+      #
+      # 抛出：
+      # * +RootError+ —— 本节点是根节点（没有兄弟）。
+      # * +BoundaryError+ —— 本节点已经是最后一个子节点（没有后一个兄弟）。
+      def next_sibling
+        raise RootError, "the root node has no siblings" unless @parent
 
-    # -- misc ---------------------------------------------------------------
+        idx = position
+        return @parent.children[idx + 1] if idx < @parent.children.size - 1
 
-    def text?
-      @type == :text
+        raise BoundaryError, "the last child has no next sibling"
+      end
     end
 
-    # Concatenate the literal string content of this subtree. Leaves that carry
-    # text expose it via +to_s+ (Text, Code); container nodes recurse.
-    def plain_text
-      return "\n" if @type == :softbreak || @type == :hardbreak
-      return to_s.to_s if @children.empty?
+    # 节点状态判定。
+    module Predicates
+      # 本节点是否是根节点（即没有父节点）。
+      #
+      # 返回值：+true+ / +false+。
+      def root?
+        @parent.nil?
+      end
 
-      @children.map(&:plain_text).join
-    end
+      # 本节点是否是叶子节点（即没有任何子节点）。
+      #
+      # 返回值：+true+ / +false+，与 #children? 正好相反。
+      def leaf?
+        children.empty?
+      end
 
-    # Serialize this node (and its subtree) back to Markdown.
-    def to_markdown
-      MDOM::Serializer.serialize(self)
-    end
-    alias markdown to_markdown
+      # 本节点是否至少拥有一个子节点。
+      #
+      # 返回值：+true+ / +false+，与 #leaf? 正好相反。
+      def children?
+        !children.empty?
+      end
 
-    def empty?
-      @children.empty?
+      # 本节点是否是 +other+ 的祖先（即 +other+ 位于本节点的子树之中）。
+      #
+      # 参数：
+      # * +other+ —— 另一个节点（+BaseNode+），不能为 +nil+。
+      #
+      # 返回值：+true+ / +false+。本节点自身不算自己的祖先（+false+）。
+      #
+      # 抛出：+ArgumentError+，当 +other+ 为 +nil+ 时。
+      def ancestor_of?(other)
+        raise ArgumentError, "other cannot be nil" if other.nil?
+
+        other.ancestors.include?(self)
+      end
     end
 
-    # A compact, single-line summary of this node (its own type/attributes only,
-    # without recursing into children).
-    def to_s
-      "#<#{short_class}#{detail}>"
+    # 维护 +depth+ 缓存。
+    module Depth
+      # 重新计算本节点及其整棵子树的 +depth+。
+      #
+      # 本节点的 +depth+ 取自父节点（父节点为 +nil+ 时为 +0+），随后递归更新
+      # 全部后代。当 +parent+ 与 +children+ 的关系被人为改动、导致 +depth+ 不再
+      # 可信时，可用本方法纠正。
+      #
+      # 返回值：+self+，便于链式调用。
+      def sync_depth!
+        @depth = @parent ? @parent.depth + 1 : 0
+        children.each(&:sync_depth!)
+        self
+      end
     end
 
-    # A human-readable tree rendering of this node and its descendants.
-    def inspect
-      pretty_print
-    end
+    # 同类实例之间协作的内部协议（混入后为 protected）。
+    #
+    # 这里的方法要么只读地检查自己的状态，要么由*接收者自己*完成状态改写；
+    # 没有"父节点伸手去改子节点 +parent+ / +depth+"的做法。外部调用方请使用
+    # 上面的公共方法。
+    module Internals
+      protected
+
+      # 断言 +node+ 可以作为子节点挂接到本节点下：不为 +nil+，且挂接不会形成环。
+      #
+      # 只做检查、不改动任何状态；建立关系由 +node.attach_to!+ 完成。
+      #
+      # 参数：
+      # * +node+ —— 待挂接的节点。
+      #
+      # 抛出：
+      # * +ArgumentError+ —— +node+ 为 +nil+。
+      # * +CycleError+ —— +node+ 是 +self+ 自身或它的祖先。
+      def assert_attachable!(node)
+        raise ArgumentError, "node cannot be nil" if node.nil?
+
+        cyclic = node.equal?(self) || node.ancestor_of?(self)
+        raise CycleError, "cannot attach a node to itself or an ancestor" if cyclic
+      end
 
-    # Render this node plus its subtree as an indented, printable tree.
-    def pretty_print(level = 0)
-      indent = "  " * level
-      children = @children.empty? ? "" : "\n" + @children.map { |c| c.pretty_print(level + 1) }.join("\n")
-      "#{indent}#<#{short_class}#{detail}>#{children}"
-    end
+      # 本节点自己认 +new_parent+ 为父节点：先校验不会形成环，再从原父脱离，
+      # 最后接管父子关系并重算本子树的 +depth+。
+      #
+      # 由 +new_parent+ 的挂载方法调用（+node.attach_to!+），状态改写全部
+      # 发生在 +node+ 自己身上。
+      #
+      # 参数：
+      # * +new_parent+ —— 新的父节点（+BaseNode+）。
+      #
+      # 返回值：+self+。
+      #
+      # 抛出：+CycleError+ —— +new_parent+ 是本节点自身或本节点的后代。
+      def attach_to!(new_parent)
+        cyclic = equal?(new_parent) || ancestor_of?(new_parent)
+        raise CycleError, "cannot attach a node to itself or an ancestor" if cyclic
+
+        unlink!
+        @parent = new_parent
+        sync_depth!
+        self
+      end
+
+      # 本节点在父节点子列表中的位置，并断言父节点确实持有本节点。
+      #
+      # 返回值：下标（+Integer+）。
+      #
+      # 抛出：+Error+，当父节点的 +children+ 中找不到本节点时（说明 +parent+
+      # 与 +children+ 已经不一致）。
+      def parent_index!
+        idx = @parent.children.index(self)
+        raise Error, "the node is not a child of its parent" unless idx
+
+        idx
+      end
 
-    private
+      # 校验 +index+ 是否落在 +-children.size-1+ 到 +children.size+ 之内，
+      # 即 Array#insert 允许的负索引范围。
+      #
+      # 参数：
+      # * +index+ —— 待校验的下标（+Integer+）。
+      #
+      # 抛出：+IndexError+，当 +index+ 超出该范围时。
+      def check_index!(index)
+        min = -children.size - 1
+        return if index.between?(min, children.size)
+
+        raise IndexError, "index #{index.inspect} outside of #{min}..#{children.size}"
+      end
 
-    # The short class name (e.g. "MDOM::Paragraph" -> "Paragraph"), falling back
-    # to the type symbol for plain nodes.
-    def short_class
-      name = self.class.name
-      name ? name.split("::").last : type.inspect
+      # 交换本节点子列表中的两个位置（由子节点在自己的父节点上调用，
+      # 即 +swap_children+）。
+      #
+      # 参数：
+      # * +left+ —— 其中一个位置的下标（+Integer+）。
+      # * +right+ —— 另一个位置的下标（+Integer+）。
+      def swap_children(left, right)
+        children[left], children[right] = children[right], children[left]
+      end
     end
 
-    # A short description of this node's own salient data, e.g. ' level=2' for a
-    # heading, ' "text"' for a text node.
-    def detail
-      case type
-      when Types::TEXT, Types::CODE
-        " #{value.inspect}"
-      when Types::CODE_BLOCK
-        lang = attributes[:lang] ? "lang=#{attributes[:lang].inspect} " : ""
-        " #{lang}literal=#{literal.inspect}"
-      when Types::HEADING
-        " level=#{level}"
-      when Types::LIST
-        ordered = attributes[:ordered] ? "ordered" : "unordered"
-        start = attributes[:start] ? ", start=#{attributes[:start]}" : ""
-        " #{ordered}#{start}"
-      when Types::LIST_ITEM
-        task = attributes[:task] ? ", task" : ""
-        checked = attributes[:checked] ? "=checked" : ""
-        task.empty? ? "" : " (#{task.sub(', ', '')}#{checked})"
-      when Types::LINK
-        title = attributes[:title] ? " title=#{attributes[:title].inspect}" : ""
-        " #{attributes[:destination].inspect}#{title}"
-      when Types::IMAGE
-        title = attributes[:title] ? " title=#{attributes[:title].inspect}" : ""
-        " #{attributes[:destination].inspect} alt=#{attributes[:alt].inspect}#{title}"
-      else
-        attributes.empty? ? "" : " #{attributes.inspect}"
+    # 语法树中所有节点的基类。
+    #
+    # 一个节点由三部分状态构成：
+    #
+    # * +type+ —— 节点类型标识（+Symbol+，如 +:paragraph+、+:heading+）。
+    # * +children+ —— 有序的直接子节点列表（+Array+）。
+    # * +attributes+ —— 节点属性表（+Hash+，如标题层级、代码块语言等）。
+    #
+    # 另外两项状态由树结构派生而来：
+    #
+    # * +parent+ —— 父节点；根节点的 +parent+ 为 +nil+。
+    # * +depth+ —— 节点在树中的深度；根节点为 +0+，逐层加一。
+    #
+    # === 能力划分
+    #
+    # 本类的行为来自若干 mixin（见 +MDOM::Node+ 的说明），自身只保留状态、初始化
+    # 与 +Enumerable+ 契约。若要扩展节点能力，优先新增模块再混入，而不是把
+    # 方法继续堆进这个类。
+    #
+    # === 结构不变式
+    #
+    # 下面所有变更方法共同维护以下不变式：
+    #
+    # * 一个子节点在同一时刻只属于一个父节点；
+    # * +parent+ 与 +children+ 双向一致（互为引用，不会出现单边挂接）；
+    # * 子树的 +depth+ 始终与它在整棵树中的实际位置一致。
+    #
+    # === 返回值约定
+    #
+    # 除以下两种情形外，所有变更方法都返回 +self+，以便链式调用：
+    #
+    # * #extract_at 返回被摘除的子节点（越界时为 +nil+）；
+    # * #replace_with 与 #wrap_with 返回替换或包装后的新节点。
+    #
+    # === 底层写入器提示
+    #
+    # #parent= 是低层写入器：直接赋值既不会同步父节点的 +children+，也不会
+    # 更新 +depth+。除非你确切知道自己在做什么，否则请使用上面的变更方法，
+    # 而不是直接给它赋值。
+    class BaseNode
+      include Enumerable
+      include Attaching
+      include Detaching
+      include Replacing
+      include Reordering
+      include Traversal
+      include Navigation
+      include Predicates
+      include Depth
+      include Internals
+
+      # 父节点；根节点为 +nil+。作为底层写入器使用，详见类说明。
+      attr_accessor :parent
+
+      # 节点属性表（+Hash+）。
+      attr_accessor :attributes
+
+      # 节点类型标识（+Symbol+）。
+      attr_reader :type
+
+      # 节点在树中的深度，根节点为 +0+。
+      attr_reader :depth
+
+      # 该节点是否含有内容（+true+ / +false+），具体含义由子类决定。
+      attr_reader :has_content
+
+      # 直接子节点列表（+Array+）。如需变更，请使用本类提供的变更方法。
+      attr_reader :children
+
+      # 在 CSM §5.3 的 +point+ 上注册一个钩子（委托 +MDOM::Hooks+）。类级——对所有
+      # 文档生效；只想影响一次调用时用 +MDOM.compile(source, hooks: ...)+。
+      #
+      #   MDOM::Node::Document.register_hook :before_compile do |doc|
+      #     doc.meta[:generated_at] = Time.now.iso8601
+      #   end
+      def self.register_hook(point, &block)
+        MDOM::Hooks.register(point, &block)
+      end
+
+      # 取消本类注册过的一个钩子。
+      def self.unregister_hook(point, block)
+        MDOM::Hooks.unregister(point, block)
+      end
+
+      # 创建一个新节点。
+      #
+      # +children+ 中的每个元素都会经 #<< 逐个挂接，因此从初始化起就享有
+      # 变更方法的全部不变量保障（先脱离原父节点、校验、同步 +depth+）。
+      #
+      # 参数：
+      # * +type+ —— 节点类型标识（+Symbol+）。
+      # * +attributes+ —— 节点属性表（+Hash+），默认为空。
+      # * +children+ —— 初始子节点（+Array+），默认为空。
+      #
+      # 返回值：新建的节点（+self+）。
+      #
+      # 抛出：
+      # * +ArgumentError+ —— 某个初始子节点为 +nil+。
+      # * +CycleError+ —— 某个初始子节点就是本节点自身或其祖先。
+      def initialize(type, attributes: {}, children: [])
+        @type = type
+        @attributes = attributes
+        @children = []
+        @parent = nil
+        @depth = 0
+        @has_content = false
+        children.each { |child| self << child }
       end
     end
   end