Go token.FileSet.PositionFor 怎样忽略 //line 注释带来的位置调整

在 Go 的 AST、代码生成器或源码诊断工具里，同一个 token.Pos 可能需要两种解释：一种是文件真实字节位置，另一种是经过 //line 位置指令映射后的文件名、行号和列号。需要忽略这种调整时，直接调用 FileSet.PositionFor(pos, false)；不要调用默认的 FileSet.Position(pos)，因为后者等价于传入 true。

先分清 FileSet、File、Pos 和 PositionFor 的职责

FileSet 管理一组源文件，File 描述其中一个文件的偏移范围，Pos 是文件集合里的紧凑位置标识，而 PositionFor 才负责把这个标识解释成包含文件名、行号和列号的 token.Position。因此，问题不在于重新计算偏移，而在于选择解释位置时是否应用替代位置表。

可以把参数含义先记成一张速查表：

用 adjusted=false 忽略 //line 调整

如果工具要报告“这个 AST 节点在磁盘上的哪一行”，应该显式传入 false。下面的示例用 AddLineInfo 模拟解析器为某个偏移登记的替代位置；实际项目通常由 Go 解析流程建立这类信息。

package main

import (
    "fmt"
    "go/token"
)

func main() {
    fset := token.NewFileSet()
    file := fset.AddFile("generated_input.go", -1, 80)

    // 模拟 //line 指令：从文件偏移 20 开始，映射到另一个文件的第 200 行。
    file.AddLineInfo(20, "generated_view.go", 200)
    pos := file.Pos(24)

    // false 忽略替代位置表，适合定位磁盘上的原始源码。
    physical := fset.PositionFor(pos, false)
    fmt.Printf("physical: %s:%d:%d\n", physical.Filename, physical.Line, physical.Column)
}

这里的关键不是 AddLineInfo 本身，而是调用方把“物理坐标”作为明确契约。若后续要把这段位置传给源码索引、补丁定位或原始文件读取逻辑，就应继续使用 false，否则同一个偏移可能被解释成另一个文件名和行号。

为什么 FileSet.Position 默认会应用调整

标准库把 FileSet.Position(pos) 定义为 FileSet.PositionFor(pos, true) 的快捷调用。也就是说，下面两行的语义相同：

// Position 默认遵循 //line 的替代位置。
shown := fset.Position(pos)

// 显式写 true，表达同一个选择。
shownAgain := fset.PositionFor(pos, true)

这正是排查“行号和文件名看起来不对”的第一处检查点：如果调用链里使用了 Position，它不是返回原始文件位置，而是可能应用位置改变型 //line 注释。编译器视角、用户错误信息或生成代码中的映射通常需要这种行为；原始源码诊断则不应依赖默认值。

把位置策略封装在调用边界

同一个工具可能同时需要两种位置：日志里给用户看的位置，以及给磁盘读取器使用的物理位置。不要让调用方到处散落布尔值，可以用两个命名函数把意图写出来：

package sourcepos

import "go/token"

// PhysicalPosition 返回原始文件坐标，不接受 //line 的位置替代。
func PhysicalPosition(fset *token.FileSet, pos token.Pos) token.Position {
    return fset.PositionFor(pos, false)
}

// MappedPosition 返回遵循 //line 映射的坐标，适合用户可见诊断。
func MappedPosition(fset *token.FileSet, pos token.Pos) token.Position {
    return fset.PositionFor(pos, true)
}

这样做的价值是让参数选择变成函数名的一部分。调用方不必记住 false 到底代表哪一种位置，代码审查时也能直接看出它是在读原始源码，还是在生成经过映射的诊断。

边界输入要怎么处理

PositionFor 要求 pos 属于这个 FileSet，或者是表示无位置的 token.NoPos。对同一文件来说，超出文件范围的位置会按文件偏移边界调整；这不等于调用方可以把任意整数强转成 token.Pos 后直接查询。

• 先确认位置来自同一个 FileSet，不要混用不同集合中的 Pos。
• 对 token.NoPos 先检查 IsValid()，不要把零值当成文件第一行。
• 需要原始字节定位时保存 File.Pos 对应的偏移，展示给用户时再选择 false 或 true。
• false 只是不应用替代位置，不会清空 File 中已有的行偏移信息。

相关问题

FileSet.Position 和 File.PositionFor 有什么区别？

两者都能把位置转换成 token.Position；前者是集合级快捷调用，默认应用调整，后者允许显式传入 adjusted。需要忽略 //line 时优先使用后者。

传 false 会不会改变 token.Pos？

不会。token.Pos 仍然表示同一个文件集合中的位置，变化的是返回的文件名、行号和列号解释。

什么时候应该传 true？

当结果要和编译器、生成器或源码中的位置映射保持一致，或者要把用户带到 //line 指向的位置时，可以传 true；原始文件排查则传 false。

记住一句话即可：物理源码坐标用 PositionFor(pos, false)，映射后的用户坐标用 PositionFor(pos, true)，而不确定默认行为时不要使用无参数的 Position 猜测。