Go token.File 怎样把偏移换成行列位置

在 AST 解析器、词法扫描器或静态检查器里，手里通常只有一个相对文件开头的字节偏移。要把它显示成“main.go:3:5”，不要自己循环统计换行，直接交给 go/token 的 token.File：先用 FileSet.AddFile 注册文件，再用 File.Pos(offset) 和 File.PositionFor(pos, adjusted) 完成转换。

一、先建立 token.File 的字节偏移表

token.File 不是文件内容本身，而是一个带文件名、大小和行偏移表的位置句柄。创建它时，size 必须与待解析内容的字节长度一致；文件内容是 UTF-8 时，应传 len(src)，不能传 utf8.RuneCount。

如果内容已经在内存中，最稳妥的方式是让标准库从换行符建立行表：

src := []byte("package main\n\nfunc 启动() {}\n")
fset := token.NewFileSet()
// size 必须是字节长度，FileSet 负责给文件分配 Pos 区间。
file := fset.AddFile("main.go", -1, len(src))
// 根据内容建立行首偏移；它不会应用 //line 替代位置。
file.SetLinesForContent(src)

// 手动登记一行时，offset 必须递增且小于 file.Size()。
// file.AddLine(1) // 这里会被忽略，因为第一个换行后的行首并非 1。

需要增量构建行表时再调用 AddLine。它只接受比上一行更大的 offset，并且 offset 必须小于文件大小；重复、倒序或等于文件末尾的值都会被忽略。行首表描述的是每行第一个字节的位置，例如 "ab\nc\n" 的行偏移是 0、3。

二、用 Pos 和 PositionFor 完成偏移转换

转换分成两步，职责很清楚：Pos 把文件内 offset 编码进当前文件的 Pos 区间，PositionFor 再根据行表还原为可展示的位置。

func positionAt(src []byte, offset int) token.Position {
	// 注册的 size 与 src 保持一致，避免 Pos 区间和内容脱节。
	fset := token.NewFileSet()
	file := fset.AddFile("main.go", -1, len(src))
	file.SetLinesForContent(src)

	// Pos 接受文件内的字节偏移，PositionFor 返回行列和文件名。
	p := file.Pos(offset)
	return file.PositionFor(p, false)
}

// 解析器拿到 node.Pos() 后，也可以直接交给 fset.PositionFor。
// false 表示保留源文件的绝对位置，不应用 //line 调整。

返回的 token.Position 包含 Filename、Offset、Line 和 Column。其中 Offset 从 0 开始，行号从 1 开始，列号也是从 1 开始的字节计数。中文或其他多字节字符会让“列号”和人眼看到的字符序号不同，这是设计行为，不应再用字符串的 rune 下标覆盖它。

如果位置已经是 AST 节点上的 token.Pos，可使用同一 FileSet：

pos := file.Pos(12)
// adjusted=false 读取源码的物理位置，适合定位原始字节。
physical := fset.PositionFor(pos, false)
// adjusted=true 允许 //line 声明改变文件名、行号或列号。
reported := fset.PositionFor(pos, true)

三、按场景选择是否应用 //line 调整

AddLineInfo 或 AddLineColumnInfo 可以为某个 offset 登记替代的文件名、行号和列号，常用于处理 //line filename:line 一类声明。它们不会移动原始字节，也不会改变 file.Offset；只有 PositionFor 在 adjusted=true 时才可能返回替代位置。

一个实用原则是：内部数据结构保留物理位置，面向用户的错误信息再按需求使用调整位置。否则同一个 token 可能在日志、索引和诊断输出中出现不同文件名，排查时很难复原。

四、处理 UTF-8 与越界输入

边界处理要先记住两个事实：file.Pos(offset) 对负数会返回文件起点，对超过大小的 offset 会返回文件末尾；file.Offset(p) 对文件外或 NoPos 会分别收敛到 0 或文件大小。这样可以形成稳定的不变量：

func clampOffset(file *token.File, offset int) int {
	// 先转 Pos 再反解，统一处理负数和过大的 offset。
	return file.Offset(file.Pos(offset))
}

func hasPosition(p token.Pos) bool {
	// NoPos 没有关联文件和行列信息，不能当作 offset 0 使用。
	return p.IsValid()
}

不要把 token.NoPos 直接当成文件第一列；它是无效位置。对外输出前可以检查 Position.IsValid()，对内部范围计算则用 file.Offset 取得已钳制的字节偏移。若要截取源码片段，再以这个 offset 操作 []byte，不要混用 rune 索引。

相关问题

为什么 token.Position 的 Column 不是中文字符序号？

因为 token.Position.Column 按字节计数，Go 源文件的位置模型与 lexer 的字节 offset 保持一致。需要展示字符序号时，应在展示层另行计算，不能改写标准库返回值。

什么时候用 file.Position 而不是 PositionFor？

file.Position(p) 等价于 file.PositionFor(p, true)。需要明确忽略 //line 调整时，直接写出 PositionFor(p, false) 更不容易误读。

AddLine 为什么没有改变行号？

常见原因是传入的 offset 不递增、等于或超过文件大小，或者传入的是字符位置而非字节偏移。按内容的字节下标重新计算并检查行表即可。