treemd tql查询语言进阶技巧:层级运算符、管道过滤与6种输出格式完全指南
treemd tql查询语言进阶技巧:层级运算符、管道过滤与6种输出格式完全指南
treemd 是一款终端里的 Markdown 导航工具,内置了类似 jq 的 tql(treemd query language,查询语言),让你用一行命令就能提取标题、代码块、链接等结构化内容。本文面向已会用基础选择器的用户,深入讲解 层级运算符(> 与 >>)、管道过滤(select()) 以及 6 种输出格式 的进阶技巧,帮你把 treemd 变成高效的 Markdown 分析与脚本处理利器 🚀。
1 分钟认识 tql:像 jq 一样查询 Markdown
tql 的语法借鉴了 jq:点号选择元素、| 管道串联操作、[...] 做索引与切片。基本用法:
treemd -q '.h2' doc.md # 所有 h2 标题
treemd -q '.h2 | text' doc.md # 去掉 ##,只要纯文本
treemd -q '.code[rust]' doc.md # 所有 Rust 代码块
不确定语法时,随时运行 treemd --query-help 查看内置完整参考,等价于仓库中的 query-language.md。
层级运算符:用 > 和 >> 精确锁定文档结构
这是 tql 最有价值的特性之一——直接描述元素间的父子层级关系,语法类似 CSS 组合器:
treemd -q '.h1 > .h2' doc.md # h1 的“直接子级” h2
treemd -q '.h1 >> .code' doc.md # h1 下方任意深度的代码块
treemd -q '.h1[Features] > .h2' doc.md # 只取 Features 章节的直接子标题
| 运算符 | 含义 | 典型场景 |
|---|---|---|
> |
直接子元素 | 只统计某章节的一级小节 |
>> |
任意深度后代 | 收集某章节下所有代码/链接 |
实战:找出 “Examples” 章节下超过 20 行的代码块:
treemd -q '.h1[Examples] >> .code | select(.text | lines > 20)' doc.md
💡 提示:
parent、children等导航函数目前尚未实现,直接用>和>>即可完成绝大多数导航需求(详见设计说明 QUERY_LANGUAGE.md)。
管道过滤:select() + 组合条件,把结果收窄到最小
管道 | 把上一步的输出传给下一步,配合 select() 可以层层过滤:
# 文本匹配
treemd -q '.h | select(contains("API"))' doc.md # 包含 API 的标题
treemd -q '.h | select(startswith("Chapter"))' doc.md # 前缀匹配
# 属性比较
treemd -q '.code | select(.lang == "rust")' doc.md # 按语言筛选
treemd -q '.link | select(.type == "external")' doc.md # 只要外部链接
# 组合条件(and / or / not)
treemd -q '.h | select(.level >= 2 and contains("API"))' doc.md
treemd -q '.code | select(.lang == "rust" or .lang == "python")' doc.md
集合函数让过滤后的结果立刻可用:
treemd -q '.h | count' doc.md # 标题总数
treemd -q '.h | text | upper' doc.md # 转大写
treemd -q '.code | lang | unique' doc.md # 去重:本文用了哪些语言
treemd -q '.link | group_by(.type)' doc.md # 按类型分组统计链接
完整的函数清单(集合、字符串、内容、聚合四大类)可在 QUERY_LANGUAGE.md 的 “Built-in Functions” 一节查到。
6 种输出格式:--query-output 参数详解
查询结果默认是纯文本,加上 --query-output 可切换 6 种格式:plain、json、json-pretty、jsonl、md、tree(实现见 output.rs)。
treemd -q '.h2' doc.md # plain(默认)
treemd -q '.h2' --query-output json doc.md # 紧凑 JSON
treemd -q '.h2' --query-output json-pretty doc.md # 缩进美化的 JSON
treemd -q '.h2 | text' --query-output jsonl doc.md # 每行一个 JSON 对象
treemd -q '.h1[Install] | md' doc.md # 原始 Markdown 片段
treemd -q '.h' --query-output tree doc.md # 树形结构
各格式适用场景:
| 格式 | 适用场景 |
|---|---|
plain |
肉眼查看,默认 |
json |
传给 jq 等工具做二次处理 |
json-pretty |
调试、贴文档 |
jsonl |
日志流、逐行处理 |
md |
提取整段 Markdown 内容再加工 |
tree |
快速浏览标题层级 |
⚠️ 常见坑:
-q模式下-o参数会被静默忽略(-o只作用于--list/--tree),一定要用--query-output,否则你会得到纯文本并以为查询失败了。
管道组合示例——统计文档代码块数量并交给 jq 读取:
treemd -q 'stats' --query-output json doc.md | jq '.code_blocks'
三个实用进阶场景
1️⃣ 自动生成目录(按标题层级缩进):
treemd -q '.h[] | " " * (.level - 1) + "- " + .text' doc.md
2️⃣ 提取某个章节的完整内容:
treemd -q '.h1[Installation] | content' doc.md # 纯文本
treemd -q '.h1[Installation] | md' doc.md # 保留 Markdown 语法
3️⃣ 生成站点地图 JSON(一次输出结构化数据):
treemd -q '[.h[] | {level: .level, text: .text, slug: (.text | slugify)}]' \
--query-output json-pretty doc.md
此外 tql 支持 stdin,cat doc.md | treemd -q '.h2' 一样有效,方便嵌入 Shell 工作流。
写在最后
掌握 >/>> 层级运算符、select() 管道过滤 和 --query-output 六种输出格式,treemd 的 tql 查询语言就足以覆盖绝大多数 Markdown 结构化分析需求:从生成目录、统计代码块到批量抽取章节,全部一条命令搞定 ✅
更多细节参考:
- 语言设计规范与完整语法:docs/QUERY_LANGUAGE.md
- 精简速查表:skills/treemd/references/query-language.md
- 输出格式实现:src/query/output.rs
- 集成测试用例(可当示例学习):tests/query_integration.rs
