Quarkdown 有序列表解析深度剖析从测试用例到源码实现【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown导读在 Quarkdown 文档处理器中有序列表Ordered List是 Markdown 排版的基础能力之一其解析正确性直接决定文档、论文、演示文稿中步骤说明与编号内容的质量。本文以仓库中的解析测试用例 orderedlist.md 为骨架逐段拆解有序列表的分隔符规则、嵌套缩进、宽松/紧凑判定、任务列表以及列表终止边界并结合 BlockTokenParser.kt 与 BaseMarkdownBlockTokenRegexPatterns.kt 中的底层实现帮助读者从词法到语法层面完整掌握 Quarkdown 的有序列表解析行为并能够据此规避写作中常见的列表断裂问题。一、测试用例全景76 行覆盖 8 类边界场景orderedlist.md是 Quarkdown 核心模块的解析回归测试素材由 BlockParserTest.kt 中的orderedList()测试方法驱动Test fun orderedList() { listOrderedList(readSource(/parsing/orderedlist.md)) }listT()会遍历解析器输出的全部节点并断言每个节点类型均为OrderedList——也就是说文件中每一段示例都必须被成功解析为有序列表节点任何一段被误判为段落、引用或代码块都会导致测试失败。因此该文件可以视为 Quarkdown 官方对什么写法算作有序列表的行为规范共覆盖 8 类场景行号段覆盖场景1–8基本编号与混合分隔符.与)11–35嵌套列表与项内块级内容段落、引用、代码块、任务项39–51lazy continuation 续行、标题与段落作为列表内容53–54多位数起始编号9、1056–62引用与代码围栏作为列表项内容63–68前导零编号003、004与多行代码70–73任务列表复选框[x]/[X]/[ ]74–76缩进量不足导致的嵌套失效二、AST 与解析入口OrderedList 节点的三要素在 Quarkdown 的 AST 中有序列表对应 List.kt 中的OrderedList类class OrderedList( val startIndex: Int, override val isLoose: Boolean, Diverge override val children: ListNode, ) : ListBlock三个字段构成有序列表的完整语义startIndex首个条目的起始编号。例如9. A开头的列表startIndex 9。渲染时决定ol start9之类的输出行为isLoose是否宽松列表loose list。若任一条目内部含有空行分隔的块级内容源码中以子节点中是否存在Newline判断列表会被标记为宽松渲染时条目前后间距加大children条目集合每个条目是ListItem节点可通过ListBlock.items属性过滤获取。词法层面OrderedListToken定义于 BlockTokens.kt负责识别以1. First/2. Second形式出现的列表块语法层面BlockTokenParser.kt 的visit(OrderedListToken)完成节点装配override fun visit(token: OrderedListToken): Node { val children extractListItems(token) val groups token.data.groups.iterator(consumeAmount 3) // e.g. 1. val marker groups.next().trim() return OrderedList( startIndex marker.dropLast(1).toIntOrNull() ?: 1, isLoose children.any { it is Newline }, children, ).also(::updateListItemsOwnership) }关键细节有两个一是startIndex直接取第一个 marker 去掉末尾分隔符后的整数值无法解析时回退为 1——这解释了测试文件中9. A / 10. B与003. A之所以能成立二是extractListItems复用 flavor 提供的列表专用词法器newListLexer见 LexerFactory.kt逐条切分条目updateListItemsOwnership则把每个ListItem的owner指向所属列表供渲染阶段区分宽松/紧凑列表使用。三、分隔符规则.与)的严格一致性测试文件前两段第 1–3 行与第 6–8 行构成了一组对比实验1. A 2. B 3. C 1. A 2. B 3) C第一段三个条目全部使用.分隔符是一个完整列表。第二段第三个条目混用)它不会被并入前两个条目所在的列表。这一行为的根源在词法模式 BaseMarkdownBlockTokenRegexPatterns.ktval orderedList by lazy { TokenRegexPattern( name OrderedList, wrap ::OrderedListToken, regex listPattern( bulletInitialization \\d{1,9}(?orderedbull[\\.)]), bulletContinuation \\d{1,9}\\korderedbull, ), ) }要点有三编号长度限制\d{1,9}表示列表项编号最多 9 位数字超出即不作为有序列表 marker双分隔符支持[\\.)]同时接受.与)两种分隔符3) C本身是合法的列表项起始分隔符严格一致bulletContinuation使用命名捕获组的反向引用\korderedbull要求列表内部所有条目沿用与首个条目相同的分隔符。因此1. / 2. / 3)中3)无法延续.分隔的列表Quarkdown 将其视为新列表块的起点。写作时如需拆分列表可善用此规则反之若希望编号连续则必须保持分隔符统一。四、嵌套列表与块级内容缩进决定层级第三段第 11–35 行是最复杂的用例验证了嵌套列表与条目内多种块级元素的组合1. A Some paragraph 2. B 1. Nested 1 1. Nested A Some paragraph 2. Nested B 3. C Some quote 4. D Some paragraph 1. E Some code 5. 1. E从中可以归纳出四项规则条目内段落条目内容以 3 个空格缩进内部可容纳段落Some paragraph段落与 marker 之间空一行多级嵌套1. Nested 1以 4 个空格缩进作为2. B的子列表其下的1. Nested A再以 7 个空格缩进形成第三级第三级条目内部同样允许段落引用块 Some quote缩进 3 空格后可作为3. C的内容代码块条目4. D内部既有段落又有子条目1. E且子条目内还可再放 5 空格缩进的围栏代码块——前导 5 个空格位于1. E的 4 空格缩进内容区内。嵌套层级判断的底层依据来自listPattern的 continuation 正则BaseMarkdownBlockTokenRegexPatterns.kt^(( {0,3}$bulletInitialization) \t{2}) (.(\n|$)| \n\s*^( {2,}| {0,3}$bulletContinuation[ \t]))列表项 marker 前允许0–3 个空格{0,3}超过 3 空格则不再被识别为列表项continuation 分支支持lazy续行任意行直接延续与至少 2 空格缩进的显式续行两种写法列表中任意条目与条目之间不允许出现两个连续空行否则列表终结(?!^(\s*\n){2})负向前瞻。五、列表终止边界什么会切断有序列表第 39–68 行集中验证了列表的多种终止/延续情形1. Another list with lazy line 2. B Some paragraph with lazy line 3. # Heading 4. C 5. # Heading Some paragraph # End of list 9. A 10. B --- 1. A End of list 1. Quote 2. AEnd of listASome multiline code End of list逐一解读 - **lazy 续行**with lazy line 没有缩进仅凭紧跟上一行就被并入 1. Another list 的段落条目 2 内段落的下行同理。这对应 continuation 正则中的 (.(\n|$)) 分支 - **标题作为条目内容**3. # Heading 证明 ATX 标题可以作为列表项内容第 45 行 Some paragraph 未缩进却仍属于条目 5又是 lazy 续行而第 51 行无 marker 的 # End of list 位于列表之后是列表外的标题 - **大编号起始**9. A / 10. B 说明起始编号不限于 1startIndex 会被解析为 9源码中 marker.dropLast(1).toIntOrNull() 直接读取该值 - **水平线终结**--- 紧跟列表后若直接出现在条目 marker 之后可能被识别为 setext 标题下划线或分隔线Quarkdown 以水平线 HorizontalRule 终结前面的列表块 - **引用作为列表后内容** End of list 不带缩进不属于列表而是列表后的块引用与之对照1. Quote 中的引用缩进 2 空格作为 1. 的条目内容——缩进位置决定了引用归属 - **代码围栏收尾**第 60–62 行的 围栏块位于列表之外前面无 marker是文档级的代码块同时标志着上一列表结束 - **前导零编号**003. A、004. 均为合法 marker\d{1,9} 允许前导零004. 条目内可容纳多行代码块 - **Setext 标题终结**第 68 行 ## End of list 是列表外的二级标题。 从词法模式看这些行为都由 continuation 正则与负向前瞻共同保证一旦某行既不满足 bullet continuation、也不满足缩进/lazy 续行要求OrderedListToken 的匹配即告终止后续内容交由段落、引用、标题等其它 block token 处理。 ## 六、任务列表复选框是内联节点 第 70–73 行验证了任务列表语法CheckedCheckedUncheckedEnd of list- [x] 与 [X] 均表示已勾选[ ] 表示未勾选 - 复选框在 AST 中对应 [CheckBox.kt](https://link.gitcode.com/i/216b9ce738c9b6cbefbaf14b57da7a80) 中的 CheckBox 内联节点仅含一个 isChecked: Boolean 字段属于列表项条目内部的 inline 内容而非块级结构 - 任务列表与普通有序列表共享同一套缩进与嵌套规则因此支持在任意层级混用。 ## 七、缩进的边界条件3 空格与 4 空格的差异 最后一段第 74–76 行用注释直接点明了缩进临界规则AB (not enough indentation to nest)C (nested in C)- 1. A3 空格是合法的列表项{0,3} 上限恰好为 3 - 2. B4 空格超过 marker 的 3 空格上限不足以嵌套为 1. A 的子条目因此被解析为**另一个独立列表**的首项而非 1. A 的下一级——注释not enough indentation to nest即指此 - 1. [x] C7 空格缩进则满足 2. B 的嵌套要求成为 2. B 的子条目内部再带一个已勾选任务项。 写作时若遇到子列表意外消失首要排查点就是子条目缩进是否至少比父条目 marker 多 4 个空格即子列表 marker 前缩进 ≥ 父 marker 前缩进 4。 ## 八、从测试到实现的完整调用链 将上述行为串成一条完整的解析链路便于读者在仓库中按图索骥 1. 词法BaseMarkdownBlockTokenRegexPatterns.orderedList 依据 listPattern 正则匹配整个列表块产出 OrderedListToken 2. 条目切分BlockTokenParser.extractListItems 调用 LexerFactory.newListLexerQuarkdown 下委托给 Base 实现见 [QuarkdownLexerFactory.kt](https://link.gitcode.com/i/31157695a8291eebe8dd82a7f872153f)用 listItem newline 两种 token 模式逐条切出 ListItemToken 3. 语法装配visit(OrderedListToken) 提取 startIndex、计算 isLoose并调用 updateListItemsOwnership 绑定条目归属 4. 树重写OrderedList / UnorderedList / ListItem 在 [NodeNewChildrenVisitor.kt](https://link.gitcode.com/i/f74f4d0f8b010fd36a2a7fd117e4c86b) 中支持子节点重建供后续渲染管线HTML、PDF、幻灯片等消费。 此外OrderedList 还承担着两类衍生职责一是函数调用返回值渲染为列表时由 [NodeOutputValueVisitor.kt](https://link.gitcode.com/i/1fe4d36933a95a38b690e99b6cad2fa9) 构造 startIndex 1 的列表二是目录TOC生成时由 [TableOfContentsUtils.kt](https://link.gitcode.com/i/8781ed8517c728aa3156f1dd76863cff) 以有序列表承载标题层级。开发者在 DSL 中也可通过 [BlockAstBuilder.orderedList](https://link.gitcode.com/i/6be163b848d603d553e2b2674c6fb743) 显式指定 startIndex 与 loose 构造列表节点。 ## 结语 一份 76 行的测试素材映射出 Quarkdown 有序列表解析的全部关键规则分隔符严格一致、编号最多 9 位且允许前导零、marker 前最多 3 空格、子条目缩进决定嵌套、条目内可容纳段落/引用/代码块/标题/lazy 续行、任务复选框作为内联节点存在。理解了 orderedList 正则模式与 OrderedListToken 的装配逻辑无论是排查写作中的列表断裂还是为 Quarkdown 贡献新的解析用例都能做到有据可依。【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考