Universal Ctags 的 reStructuredText 解析器：target、章节与边界输入的处理机制

• 开发工具
• CLI

本文以 Universal Ctags 仓库中 reStructuredText（reST）解析器的测试输入 target-restructuredtext.d/input.rst 为切入点，系统讲解该解析器如何把.rst文档中的标题、章节、超链接目标（hyperlink target）、引用（citation）与替换定义（substitution definition）转换为 tags，并结合 parsers/rst.c 源码剖析其实现原理、层级调整算法与异常输入的容错行为。读完本文，你将掌握 reST 解析器的完整 kind/字段体系、target 提取规则，以及如何用ctags命令和 Units 测试设施验证解析结果。

reST 解析器概览：从 geany 移植而来的实现

reStructuredText 解析器在仓库中位于 parsers/rst.c，文件头注释明确说明该模块"was ported from geany"（移植自 geany 编辑器），版权归 Nick Treleaven 所有。其行为参考 docutils 的 reST 规范（文件头注释引用了 docutils 官方 reST 文档作为参考文献）。

解析器的注册入口是RstParser()（parsers/rst.c）：

• 解析器名称：ReStructuredText
• 文件扩展名：rest、reST、rst
• 别名：rst（与 Emacs 的 rst-mode 命名保持一致）
• 解析入口函数：findRstTags
• 使用 cork 队列（def->useCork = CORK_QUEUE），借助 cork 索引在解析完成后统一处理 scope 关系

这意味着任意以.rst、.rest或.reST结尾的文件都会被该解析器接管。标签生成的主循环位于findRstTags()（parsers/rst.c），它逐行读取输入，按"标记行（markup line）→ 标题候选 → 下划线确认"的顺序推进状态机。

九种标签 kind：标题层级与标记型条目的完整划分

解析器通过RstKinds数组（parsers/rst.c）声明了 9 种 kind，覆盖 reST 文档的两种主要结构：章节型（由标题构成）与标记型（由..指令构成）：

在 target 测试的 expected.tags 中可以看到，ANOTHER TITLE、TITLE被标记为c（chapter），section0、section1被标记为s（section），而title-target、section target0、INCLUDING \: in name被标记为T（target）——这正是上述 kind 体系在真实解析结果中的体现。

解析器专用字段：sectionMarker 与 overline

除通用字段外，reST 解析器还注册了两个语言专用字段（parsers/rst.c）：

• sectionMarker：声明章节所用的标点字符（如=、-、*、~），默认关闭（enabled = false）；
• overline：布尔字段，标记该章节是否同时使用了上划线（overline）与下划线（underline）两种装饰线声明，默认关闭。

这两个字段需要通过--fields=+{...}或--fields-all=+{...}显式开启。例如 simple-restructuredtext.d/args.ctags 中就同时启用了{sectionMarker}与{end}字段：

--fields-all=+{sectionMarker} --fields=+{end}

开启后，simple-restructuredtext.d/expected.tags 中每一条章节 tag 都会附带标记字符：Section 1.1的sectionMarker:-、Subsection 1.1.1的sectionMarker:*、Subsubsection 1.1.1.1的sectionMarker:~，同时end:字段记录了该章节的作用域结束行号。overline字段则可见于 title.d/expected.tags：TITLE、Subtitle、SubSubsection等使用上划线+下划线双重装饰的标题都带有overline:标记。

逐行拆解 target 测试：hyperlink target 的提取与容错

关联文档 input.rst 是一个高度浓缩的边界测试用例，几乎每一行都对应一种 target 形态或异常输入。以下结合 expected.tags 与源码逐条分析。

基本 target：.. _title-target:

.. _title-target:

findRstTags对每行先做去前导空白处理，然后用is_markup_line_with_char()（parsers/rst.c）判断是否为.. _开头的标记行，随即交给capture_markup()（parsers/rst.c）提取名称。由于title-target紧跟TITLE章节之后，生成的 target tag 带有 scope：

title-target input.rst /^.. _title-target:$/;" T chapter:TITLE

scope 的来源在makeTargetRstTag()（parsers/rst.c）：它直接读取当前 nesting level 栈顶的 cork 索引作为scopeIndex，因此 target 的归属章节由它出现时"正在打开的章节"决定。值得注意的是 target 本身不会push 新的嵌套层级——只有章节标题才 push（见makeSectionRstTag末尾的nestingLevelsPush）。

反引号包裹的 target：.. _section target0:

.. _`section target0`:

reST 规范允许用反引号包裹含空格的引用名。capture_markup检测到名字部分以`开头时，将终止符切换为`，持续收集直到下一个反引号。因此section target0被完整保留，且因为出现在section0内部，其 scope 指向了该节：

section target0 input.rst /^.. _`section target0`:$/;" T section:section0

转义字符：.. _INCLUDING \: in name:

.. _INCLUDING \: in name:

capture_markup对普通 target 使用:作为默认终止符，但它实现了反斜杠转义逻辑：遇到\时，把\与紧随其后的字符一并写入名称（代码中通过escaped标志位实现），从而让\:不会被误判为终止符。最终生成的 tag 名为INCLUDING \: in name（tags 输出中转义为INCLUDING \\: in name）：

INCLUDING \\: in name input.rst /^.. _INCLUDING \\: in name:$/;" T section:section1

这条 target 的 scope 是section:section1，因为它在section1之后、且此时section1仍处于打开状态。

非法 target 的静默丢弃

input.rst的亮点在于末尾三行"损坏"的 target，它们全部不出现在 expected.tags 中，各有各的被拒原因：

.. _ `b r o k e n 2` : .. _broken1: .. _

• .. _ ``b r o k e n 2`` :：名字部分以多个空格开头。capture_markup对名字首字符做检查：既不是反引号、也不是非空白字符时，直接goto out丢弃。反引号前混入空白正是 docutils 规范所不允许的（源码注释引用了 docutils 对"simple reference names"的定义：单个单词、仅含字母数字及孤立的连字符/下划线/句点/冒号/加号）。因此尽管这一行同样以.. _开头，也无法生成 tag。
• .. _broken1:：..与_之间夹杂了制表符/空格。is_markup_line_with_char要求line[2] == ' '且line[3] == reftype（此处 reftype 为_），而这行的第 4 个字符是空白而非_，标记行匹配失败，整行被当作普通文本处理。
• .. _：孤立的.. _没有名字部分。capture_markup在名字为空（vStringLength == 0）时同样goto out丢弃。

这种"合法结构被提取、非法结构被静默忽略"的行为，正是该测试用例存在的意义：它锁定了解析器对 reST 超链接目标的接受边界，防止后续改动破坏容错性。

章节层级判定与自动降级：从 title 到 chapter 的 shiftKinds

reST 的章节级别不是由标记字符的"优先级"预先决定的，而是由标记字符首次出现顺序决定的。get_kind()（parsers/rst.c）维护一个sectionTracker[6]数组：某个装饰字符（如=、-、*）第一次作为下划线出现时，被绑定到当前空闲的最低层级；此后相同字符（且 overline 属性一致）都归属该层级，并在count中累计出现次数。

target测试输入展示了层级不足时的自动调整逻辑：文件开头的ANOTHER TITLE与TITLE都使用=上划线+下划线装饰，且均位于文件最顶层。此时section_tracker[K_TITLE].count > 1，adjustSectionKinds()（parsers/rst.c）触发shiftKinds(2, K_TITLE)（parsers/rst.c）：把 cork 队列中所有[K_TITLE, SECTION_COUNT)区间的 kind 索引整体加 2，于是 title（0）→ chapter（2）、subtitle（1）→ section（3），其余层级依次顺延。

这解释了 expected.tags 中的现象：

• ANOTHER TITLE、TITLE输出为c（chapter）而非H（title）——文档没有唯一的顶层标题，两个同级标题被降级为章节；
• section0、section1输出为s（section）——原本应属 subtitle 层级的-装饰线被顺延为 section；
• 所有 tag 的 scope 都指向chapter:TITLE而非ANOTHER TITLE，因为TITLE是解析到 target 时栈顶仍打开的章节（ANOTHER TITLE早已在TITLE出现时被弹出）。

shiftKinds还会把"超出层级范围"的条目标记为 placeholder，并通过getFosterEntry()把其 scope 重映射到合适的父级，避免产生悬空的父子关系。类似地，若文档只有一个 title 但有多个 subtitle（K_TITLE.count == 1 && K_SUBTITLE.count > 1），则执行shiftKinds(1, K_SUBTITLE)，只把 subtitle 及以下层级顺延一位。

嵌套 scope 与章节结束行

makeSectionRstTag()（parsers/rst.c）负责生成章节 tag：标题文本行号被回退一行（指向标题行而非下划线行），父级取自getNestingLevel()（parsers/rst.c）弹出的嵌套层级；只有父级 kind 严格小于当前 kind 时才挂载scopeIndex。在 simple-restructuredtext.d/expected.tags 中可以看到完整的链式作用域：

Chapter 1 c sectionMarker:= Section 1.1 s chapter:Chapter 1 sectionMarker:- Subsection 1.1.1 S section:Section 1.1 sectionMarker:* Subsubsection 1.1.1.1 t subsection:Subsection 1.1.1 sectionMarker:~

end:字段（如end:25、end:20）来自getNestingLevel在弹出层级时调用的setTagEndLine，标记该章节在后续更高层级标题出现前的最后一行。

title.d用例还覆盖了 overline（上划线）样式的标题、缩进标题（input-1.rst中xC0带前导空格）、以及"第六层及以下标题不被提取"的边界——SubSubSubsection与SubSubSubsection使用.、,、@等第 7 个及以后的装饰字符，因超出 6 个章节层级而不会生成 tag（见 title.d/expected.tags 中缺失对应条目）。

其他标记型条目：citation 与 substdef

findRstTags的标记行分支还处理另外两类 reST 结构：

• 引用（citation）：.. [name]，对应 kindC。由is_markup_line_with_char(line, '[')识别、capture_markup以]为终止符提取。在 citation.d/input.rst 与 citation.d/expected.tags 中，.. [atomic-ops]等引用名被提取为Ckind，且继承了当前章节的 scope（chapter:References）。
• 替换定义（substitution definition）：.. |name| replace:: ...，对应 kindd。由is_markup_line_with_char(line, '|')识别、以|为终止符提取。Linux 内核文档风格的 substdef.d/input.rst 中，.. |struct cpuidle_state| replace:: ...被提取为struct cpuidle_state（dkind），.. |cpufreq| replace::被提取为cpufreq。

有意思的是，markup-line-with-spaces.d/input.rst 展示了引用的另一种容错场景：.. [OVERVIEW] ...这类带前导缩进的标记行同样能被识别——因为findRstTags在判断标记行之前先对每行做了line_trimmed去空白处理，只要.. [本身规范，缩进不构成障碍。

code-block 与 guest 解析：让文档里的代码也生成 tags

reST 文档中的.. code-block:: <lang>指令会触发 guest 解析（需要在--extras=+{guest}或--extras=+g开启 guest extra 的前提下）。相关实现位于 parsers/rst.c 的codeblockTracker结构体与 parsers/rst.c 的识别逻辑：解析器记录代码块的缩进深度、语言与起止行，代码块结束后通过makePromise把该区间交给对应语言的 guest 解析器处理。

code-blocks.d/input.rst 与 code-blocks.d/expected.tags 验证了这一机制：reST 标题C Language Example（Hkind）、Test 1（ckind）正常输出，而代码块内的test1_0、test1_1等 C 函数则由 guest 解析器生成，带有language:C、extras:guest标记，并正确识别了函数原型（typeref:typename:int）。input-2.rst中甚至验证了 C 预处理宏#define DEF的 guest 提取（extras:fileScope,guest）。

编码处理：UTF-8 与 ISO-8859-1 文档

reST 解析器在计算下划线长度时调用utf8_strlen计算标题的显示宽度（而非字节数），并处理非 UTF-8 输入的回退（当utf8_strlen返回负值时按单字节字符集处理），相关逻辑见 parsers/rst.c。

utf8-restructuredtext.d/input.rst 与 utf8-restructuredtext.d/expected.tags 验证了多字节标题（如Titlə、Șůƀťițƚe、Chàptěr 1、Šéçtiön 1.1、@Ѐ–𐀀）以及它们的嵌套 scope 都能被正确提取，证明显示宽度计算与层级追踪对多字节字符有效；iso8859-1-restructuredtext.d则覆盖 Latin-1 编码输入的兼容性。

用 Units 测试设施验证解析行为

target-restructuredtext.d目录是 Universal Ctags Units 测试体系的一个标准用例，其构成（约定见 docs/testing-parser.rst）：

• input.rst：必需的输入文件（basename 必须为input）；
• expected.tags：期望输出，测试设施运行 ctags 后与实测输出逐行比对；
• args.ctags：附加命令行参数，内容为--sort=no，一行一个选项。

运行该用例即可复现本文讨论的全部解析行为：

make units LANGUAGES=ReStructuredText # 或单独运行某个用例 misc/units run target-restructuredtext.d

测试通过后，misc/units工具会在Units/parser-restructuredtext.r/下生成实际的executed.tags供人工复核。整个Units/parser-restructuredtext.r/目录下的title.d、citation.d、substdef.d、code-blocks.d、markup-line-with-spaces.d、utf8-restructuredtext.d、iso8859-1-restructuredtext.d等用例，共同构成 reST 解析器的回归测试矩阵，覆盖了层级调整、标记提取、guest 解析、编码兼容等各个维度。

实践：从命令行生成 reST 文档的 tags

日常使用中，只需把.rst文件交给 ctags 即可（解析器默认启用）：

ctags -o - --sort=yes docs/guide.rst

常用增强选项：

• --fields=+K：在 tags 中显示 kind 字母与名称（如c、s、T）；
• --fields=+{sectionMarker}：显示每个章节使用的装饰字符；
• --fields=+{overline}：标记使用了上划线+下划线双重装饰的标题；
• --fields=+{end}：显示章节结束行号；
• --extras=+{guest}：让.. code-block::内的代码由对应语言解析器生成 guest tags；
• --output-format=json：以 JSON 形式输出（字段结构更清晰，便于程序消费）。

例如复现 target 测试的输出：

ctags --sort=no -o - \ --fields=+K \ Units/parser-restructuredtext.r/target-restructuredtext.d/input.rst

会得到与 expected.tags 一致的 7 条 tag：2 个 chapter（ANOTHER TITLE、TITLE）、2 个 section（section0、section1）、3 个 target（title-target、section target0、INCLUDING \: in name），而三个损坏的标记行被正确忽略——这正是 reST 解析器"严格识别合法结构、静默容忍非法输入"设计哲学的直观体现。

• 开发工具
• CLI