Pandoc MediaWiki 表格解析深入:colspan 表头单元格与原生 AST 输出实战
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 ( "" , [] , [] ) [])
]
关键信息:
- 表头单元格跨 4 列:
Cell中(ColSpan 4)精确还原了colspan=4属性;同时单元格前的列规格数组(ColWidthDefault)被重复 4 次,与ColSpan 4保持一致; - 表体 4 个单列单元格:每一格均为
(ColSpan 1)、AlignDefault,内容由Plain包裹的Str/Space序列构成; - 表头行与表体行分别对应
TableHead与TableBody,TableFoot为空; - 表格首行没有普通属性,因此
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 读取器表格解析代码的良好切入点。