缩进列表转 ASCII 目录树实战指南:七组开关决定你的 README 像一棵树还是一堵墙

缩进列表转 ASCII 目录树实战指南配图

一份粘进来的项目符号大纲。这就是你要 ASCII 树工具处理的东西。可每位项目负责人都干过同一件事:从 Notion 或 Slack 线程里复制一段,点一下 Generate,拿到一棵勉强能用的树——这里一条对不齐的纵线,那里一个让 Discord 渲染崩掉的 Unicode 符号,某个叶节点没带上你想要的方括号。风格、缩进单位、整根纵线、叶节点方括号、行尾空格裁剪,再加上两个你总会忘的(剥前缀、输出形态),一共七组开关,决定了最后那块东西是一张真正的目录图,还是一堵符号墙。这篇实战指南逐个过一遍开关、开关底下的格式决策,以及只有你真的粘进 200 行大纲才会冒出来的失败模式。

一份缩进列表实际携带的信息

一份朴素的缩进列表,是把六样东西叠进同一股流里。第一是深度:每一层加上同一个单位(两个空格、四个空格或者一个制表符),这个单位在输入里处处重复。第二是项目符号前缀:-、*、+,或者 1. 这样的编号;前缀是每层都有、只在第一层有、还是完全没有,这是工具首先要回答的问题。第三是枝干符号的选择:你要画一个读者会当成项目符号的连字符,还是要回头输出 Unicode 的 ├── / └──?第四是叶节点的语义:没有子节点的一行算目录(输出成 foo/)还是文件(裸着输出),或者你想让 foo 和 foo/ 的区别只取决于用户自己敲的那个斜杠?第五是行尾空白:多数编辑器会剪掉,从终端复制却通常留着,用带行尾空格的列表画出来的树,会比源文件预期的宽度多出一列。第六是注释行:# ... 或 // ... 这类在大纲里只是备注的行,除非显式跳过,否则会变成树里的子节点。

把列表当成一股流,回来的还是一股流;把它当成一棵树,才能拿到你敲进去的那个深度。第一次转换是唯一要紧的一次,选择发生在剥前缀那一步,比深度计数器开始跑还早。

风格选择:Unicode 制表符还是经典 ASCII

两种输出风格面向两类不同的读者。Unicode 制表符(├──、└──、│)在 GitHub、GitLab、Discord、Slack、Notion 和任何现代终端里都能干净渲染。它成为默认选项有它的道理:三字符宽的枝干符号让树在每一层都有可读的对齐,拐角符号(└──)只出现在父节点的最后一个子节点上,结构因此毫不含糊。麻烦在于:把这棵树粘进老式邮件客户端、Windows-1252 控制台,或者一个没声明 UTF-8 的 CMS 代码块,每个制表符都会变成 ├──。树读不了了,更糟的是字节数也错了,看上去 4 个字符,其实变成 9 个,粘进表格里会把列宽撑坏。

每棵树背后的七组开关

经典 ASCII(|--、--、|)能挺过任何一次编码往返,因为每个字节都在 128 以下。它更丑:拐角符号要占四个字符(--)而不是三个(└──),枝干和拐角在对齐上只差一个字符,深度一大,树就开始显得挤。什么时候用它:要粘进的聊天客户端会悄悄转义 Unicode;输出还要被别的工具解析(文档生成器、wiki 渲染器);接收方是在没设 LANG=en_US.UTF-8 的终端里看 diff 的代码审查者。

这个决定通常与项目无关,与下一位读者有关。

缩进单位:混合输入为什么该用自动探测

两个空格缩进的列表和四个空格缩进的列表,解析结果不一样。多数编辑器默认两个空格,多数代码格式化工具默认四个,Makefile 和 Go 源码里制表符很常见。自动探测开关会扫过前十个非空行,选出一个能把所有观测到的缩进整除的单位。一个列表里两个空格和四个空格混在同一个块里,自动探测就取最大公约数,四空格那一侧会多出一层深度。这是特性不算缺陷:四空格的行在原文里本来就更深,树把这个信息留住了。

失败的情形是制表符和空格混用。一行用制表符缩进,旁边一行用两个空格,两者没有公共单位(制表符算 1 个字符,视觉上却更宽),自动探测会报错,不会去猜。碰上这种情况,把缩进单位强制设成 tab 或 2,让工具去压另一侧。你得到的树跟编辑器里看到的不一致,但至少自洽。

整根纵线与四字符宽的心算模型

整根纵线开关是个四字符的问题,答案只有一个字符。关掉时,树只在叶节点的父级画枝干符号(├──)。打开时,每个叶节点的每个祖先都往下画一条纵线(│),深度 5 的叶节点前面就有 4 个纵线字符,你能顺着视线把路径一路追回根节点。

同一份列表,两种输出风格

心算模型是这样:算一个深度 N 节点的宽度。深度 N 处,前缀是 N-1 个纵线字符(每个一字宽)加一个枝干字符(Unicode 3 字符宽,ASCII 4 字符宽),所以叶节点内容从第 4 * (N-1) + 4 列开始。在意终端宽度的话,这一列要控制在 80 以内。打开整根纵线不改变对齐,也不加字符,只是让每个祖先都显形,不让拐角在兄弟节点之间消失。

叶节点方括号:docs/[api.md] 什么时候有意义

叶节点方括号开关把类文件节点裹进 [...],读者扫一眼树就能数出文件和目录各有多少。默认关闭,因为多数人不想在 README 里看到方括号。文档索引、项目上手文档、静态站点生成器的侧边栏,凡是读者需要一眼看出哪些节点可点的地方,就该打开。

坑在于工具不会自动识别扩展名。api.md、api.md/、api/、api 都是叶节点,除非你在目录那种情况下自己敲了结尾斜杠。加括号的 [api.md] 纯粹是外观,既不改变树深度,也不改变点击目标。

行尾空格裁剪,和那份「看着对」的输出

行尾空格裁剪是那个你忘了、直到从终端复制时才想起来打的开关。从 tree 输出或 ls -R 里粘过来的列表带行尾空格,因为源命令补过。不裁剪的话,画出来的树里每个叶节点都比内容显示的宽一列,到最深处对齐全乱。打开(默认就是开)之后,工具在画之前把行尾空格丢掉,树的各列就对上了。

边角情况:你希望树能往返还原。源列表里的行尾空格如果承担语义标记(罕见,但生成的配置文件里会出现),裁剪就会把它们去掉,树不再是忠实副本。给 README、文档、Slack 消息用,裁剪是你想要的;给配置文件预览用,关掉它。

串起来:拿一份真实大纲跑完整流程

拿这份列表,一个项目骨架,两种风格各跑一遍,整根纵线打开,叶节点方括号关闭,裁剪打开,自动探测:

要留意的三种失败模式

输入

src
  index.ts
  tools
    json-formatter.ts
    qr-code-generator.ts
  package.json
docs
  api.md
  guides
    quickstart.md

Unicode 制表符,整根纵线打开

.
├── src
│   ├── index.ts
│   └── tools
│       ├── json-formatter.ts
│       └── qr-code-generator.ts
└── package.json

经典 ASCII,整根纵线关闭

.
|-- src
|   |-- index.ts
|   -- tools
|       |-- json-formatter.ts
|       -- qr-code-generator.ts
-- package.json

同一份列表,两位读者:一位拿到 GitHub 能渲染的树,另一位拿到哪儿都能粘的树。七组开关合起来决定你交出去的是哪一种。

树画歪了该查什么

  • 坏掉的输出里反复出现三种模式。第一,所有叶节点都停在同一个深度。树画出了结构,深度却丢了。原因几乎总是制表符与空格混用的缩进:自动探测看到一行制表符和一堆四空格行,选了 tab,把四空格的行也当成深度 0。强制指定缩进单位再跑一遍即可。
  • 第二,没有其他子节点的父级上出现了枝干符号。只有一个子节点的父级该画 └──,画成 ├── 就是子节点数错了,通常是因为某行注释或空行被当成了兄弟。粘之前把注释剥掉。
  • 第三,最深那层叶节点少了最后一列。树里最深的叶节点比次深的那行短一两个字符。源里的行尾空格在作怪,打开裁剪重跑。

想边试边看,或者把选项列表并排比对,直接用 缩进列表转 ASCII 目录树 工具。粘进你的大纲,切一下风格,在同一面板里比对两份输出,这是弄清哪个开关控制哪种视觉差异最快的办法。输入是真实项目的时候(tree 的输出、docs 目录清单、配置层级),同样的七组开关决定结果读起来像一张目录图,还是一堵符号墙。

更多 ASCII 与树形渲染工具见 Elysia Tools。

1 Comment

Leave a Reply

Your email address will not be published. Required fields are marked *