Pandoc MediaWiki 表格解析深入:colspan 表头单元格与原生 AST 输出实战

原创2026-09-21 21:55:461,868 阅读
文章标签:文档CLI开发工具模板引擎插件系统富文本WebAssembly

Pandoc MediaWiki 表格解析深入:colspan 表头单元格与原生 AST 输出实战

本指南以 Pandoc 仓库中回归测试用例 test/command/6992.md 为核心,完整讲解 MediaWiki 表格语法({| ... |})中 colspan 属性的解析行为,以及如何通过 -f mediawiki -t native 将 MediaWiki 表格转换为 Pandoc 原生 AST 表示。读完本文,你将掌握 MediaWiki 表格的块级语法规则、表头(!)与单元格(|)属性语法(!colspan=4 | ...)、以及原生 AST 中 Table/TableHead/Cell/ColSpan 等构造子的精确结构,并了解 MediaWiki 读取器 中对应的底层实现。

测试用例 6992:MediaWiki 表格解析的回归验证

在 Pandoc 的测试体系中,test/command/ 目录下的 *.md 文件是一种"命令式回归测试"(command test):文件内嵌一段 shell 命令与期望输出,测试框架执行命令并逐字比对结果。用例 test/command/6992.md 对应 GitHub issue #6992——changelog 中明确记录该修复为 "Fix parsing of col/rowspan (#6992)"(见 changelog.md),属于 MediaWiki reader 的修复项。

该用例的完整命令为:

pandoc -f mediawiki -t native

输入是一段 MediaWiki 表格源码,期望输出为 Pandoc 原生 AST(-t native 的打印格式)。

MediaWiki 表格语法:从 {| 到 |}

MediaWiki 表格以 {| 起始、|} 结束,表头行单元格以 ! 开头,普通单元格以 | 开头,行分隔符为 |-。用例输入如下:

{| class="wikitable"
!colspan=4 | template request
|-
| mode || No || String || MUST be "template" or omitted
|}

逐行拆解:

  • {| class="wikitable":开启表格并携带表格级属性 class="wikitable"。该属性在解析后被写入表格自身的属性字段(输出 AST 中表格属性为 ("", [], []),说明 class 等属性仅参与渲染,原生 AST 的表属性为空);
  • !colspan=4 | template request:表头单元格。! 声明这是表头,colspan=4 是该单元格的属性,| 之后是单元格内容 template request。注意这里的 | 是属性与内容之间的分隔符;
  • |-:行分隔符;
  • | mode || No || String || MUST be "template" or omitted:普通单元格行,|| 是 MediaWiki 表格内联单元格分隔符;
  • |}:表格结束。

这正是 MediaWiki 表格"表头单元格(!)+属性(colspan)"的典型写法,也是 issue #6992 关注的核心:表头单元格上带属性时的解析。

原生 AST 输出逐字段解读

运行用例命令,期望输出如下(为便于阅读拆分为带注释片段):

[ Table
    ( "" , [] , [] )
    (Caption Nothing [])
    [ ( AlignDefault , ColWidthDefault )  -- 重复 4 次,对应 colspan=4
    , ...
    ]
    (TableHead
       ( "" , [] , [] )
       [ Row
           ( "" , [] , [] )
           [ Cell
               ( "" , [] , [] )
               AlignDefault
               (RowSpan 1)
               (ColSpan 4)
               [ Plain [ Str "template" , Space , Str "request" ] ]
           ]
       ])
    [ TableBody
        ( "" , [] , [] )
        (RowHeadColumns 0)
        []
        [ Row
            ( "" , [] , [] )
            [ Cell ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) [ Plain [ Str "mode" ] ]
            , Cell ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) [ Plain [ Str "No" ] ]
            , Cell ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) [ Plain [ Str "String" ] ]
            , Cell ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1)
                [ Plain [ Str "MUST" , Space , Str "be" , Space , Str "\"template\"" , Space , Str "or" , Space , Str "omitted" ] ]
            ]
        ]
    ]
    (TableFoot ( "" , [] , [] ) [])
]

关键信息:

  1. 表头单元格跨 4 列:Cell 中 (ColSpan 4) 精确还原了 colspan=4 属性;同时单元格前的列规格数组(ColWidthDefault)被重复 4 次,与 ColSpan 4 保持一致;
  2. 表体 4 个单列单元格:每一格均为 (ColSpan 1)、AlignDefault,内容由 Plain 包裹的 Str/Space 序列构成;
  3. 表头行与表体行分别对应 TableHead 与 TableBody,TableFoot 为空;
  4. 表格首行没有普通属性,因此 Table 的属性为 ("", [], [])(id 为空、class 为空、键值对为空)。

源码级印证:tableCell 中的 colspan 处理

MediaWiki 读取器 的 tableCell 函数是解析单个单元格的核心,其实现与上述 AST 完全对应:

let align = case lookup "align" attribs of
                Just "left"   -> AlignLeft
                Just "right"  -> AlignRight
                Just "center" -> AlignCenter
                _             -> AlignDefault
let rowspan = RowSpan . fromMaybe 1 $
              safeRead =<< lookup "rowspan" attribs
let colspan = ColSpan . fromMaybe 1 $
              safeRead =<< lookup "colspan" attribs
let ColSpan rawcolspan = colspan
let handledAttribs = ["align", "colspan", "rowspan"]
    attribs' = [ (k, v) | (k, v) <- attribs
                        , k `notElem` handledAttribs ]
let widths = case lookup "width" attribs of
                Just xs -> maybe (replicate rawcolspan 0.0)
                             (\w -> replicate rawcolspan
                                (w / fromIntegral rawcolspan))
                             (parseWidth xs)
                Nothing -> replicate rawcolspan 0.0
return (widths, B.cellWith (toAttr attribs') align rowspan colspan bs)

从中可以读出的实现事实:

  • colspan 缺省为 1,存在时通过 safeRead 解析为整数并包装成 ColSpan n;rowspan 同理;
  • align 属性映射到 AlignLeft/AlignRight/AlignCenter,未指定时回退 AlignDefault;
  • colspan、rowspan、align 被标记为"已处理属性"(handledAttribs),不会重复进入单元格的键值对属性;
  • 列宽度(width)按 rawcolspan 均分,若没有 width 属性则宽度为 0(表示默认宽度);
  • 计算列对齐时,calculateAlignments 使用 replicate colspan align 按跨列数展开对齐信息(见 MediaWiki.hs 中 cellAligns 的实现,注释明确写着 "multiple widths because cell might have colspan")。

这正是 #6992 修复后行为:表头单元格上的 colspan 属性被正确识别,AST 中 ColSpan 与列规格数量同步。

属性分隔符 | 的解析规则

用例中 !colspan=4 | template request 里的 | 是"属性列表与内容之间的分隔符"。该逻辑位于 cellsep 解析器:

cellsep = try $ do
  col <- sourceColumn <$> getPosition
  skipMany spaceChar
  c <- oneOf "|!"
  when (col > 1) $ void $ char c
  notFollowedBy (oneOf "-}")
  attribs <- option [] (parseAttrs <* skipMany spaceChar <* char '|')
  skipMany spaceChar
  pure attribs

parseAttrs/parseAttr(MediaWiki.hs)负责解析 key=value 形式的属性:属性名由字母起始、可含字母数字及 _-:.,值可带双引号(如 class="wikitable")或是不含空格与 | 的裸值(如 colspan=4)。只有存在属性列表时,解析器才要求跟随一个 | 分隔符,随后才是单元格正文。

同类用例对照:MediaWiki 表格的 colspan 组合

除 6992 外,仓库还有若干 MediaWiki 表格回归用例可作为对照,例如:

  • test/command/2649.md:同样使用 colspan=2 | '''uitslagen Flohrgambiet''' 语法,期望输出为 HTML5 中的 <td colspan="2"><strong>...</strong></td>,展示了 colspan 在表体单元格中的解析(HTML 输出端);
  • test/command/10490.md:!colspan=4 style=""|Hash size,表头单元格同时携带 colspan 与 style 属性,期望输出 <th colspan="4" style="">Hash size</th>;
  • test/command/10149.md:HTML 读取器视角的 rowspan/colspan 组合用例,可用于对比不同读取器对跨行跨列表格的处理。

这些用例共同覆盖了 colspan/rowspan 在表头与表体、单属性与多属性组合场景下的解析路径。

写入端对照:MediaWiki 表格的 colspan 输出

了解读取之后,可对照 MediaWiki 写入器 中的 cellToMW:

let rowspan' = case rowspan of
                RowSpan 1 -> mempty
                RowSpan n -> [("rowspan", T.pack(show n))]
let colspan' = case colspan of
                ColSpan 1 -> mempty
                ColSpan n -> [("colspan", T.pack(show n))]

即:只有跨列/跨行数大于 1 时才显式输出 colspan/rowspan 属性,默认值 1 被省略——这与读取端"缺省为 1"的语义对称,保证 MediaWiki 表格在 Pandoc 中往返(round-trip)时行为一致。

实战验证:在本地复现测试用例

若本地已构建 Pandoc,可直接复现:

# 方式一:直接运行命令式测试(输入来自 stdin,以 Ctrl-D 结束)
pandoc -f mediawiki -t native <<'EOF'
{| class="wikitable"
!colspan=4 | template request
|-
| mode || No || String || MUST be "template" or omitted
|}
EOF

# 方式二:通过测试框架执行(在仓库根目录)
make test TEST="command/6992.md"

若已具备 Haskell 构建环境,也可在 INSTALL.md 指导下从源码构建 pandoc 后验证。将用例中的 colspan=4 改为其他值(如 colspan=2),观察 AST 中 ColSpan 与列规格数组数量的同步变化,即可直观感受读取器对跨列单元格的处理逻辑。

小结

通过用例 test/command/6992.md,本文完整梳理了 Pandoc 对 MediaWiki 表格中 colspan 表头单元格的解析链路:从 {| ... |} 块级语法、!colspan=4 | 内容 的属性分隔符规则,到原生 AST 中 Table/TableHead/TableBody/Cell/ColSpan 的精确结构,再到读取器 MediaWiki.hs 中 tableCell、cellsep 的源码实现与写入端的对称处理。理解这一用例,既有助于排查 MediaWiki 表格转换中的跨列问题,也是阅读 Pandoc 读取器表格解析代码的良好切入点。

登录后查看全文
pandoc