Go text/scanner.Scanner 怎样逐个读取源码词元

我在给配置片段做轻量预处理时，最容易犯的错是把“读到字符”和“读到词元”混成一件事。Go 的 text/scanner.Scanner 已经替我们处理了 UTF-8 字符、标识符、数字、字符串和注释的边界，调用方只需要决定扫描模式，再按顺序消费结果。

官方地址：https://go.dev/pkg/text/scanner/

要逐个读取源码样式的词元，先用 Init(io.Reader) 初始化，再循环调用 Scan()；当前词元的原文从 TokenText() 取得，起点看 Position，不要把 Pos() 当成词元起点。

先把输入、词元和位置对上

我通常先把输入限制在一段可追踪的文本，而不是一上来就接完整编译流程。Init 接收 io.Reader，初始化后默认使用 Go 的词元模式和空白规则；每次 Scan 成功后，TokenText 返回最近词元的文本，Position 则描述这个词元从哪里开始。

package main

import (
    "fmt"
    "strings"
    "text/scanner"
)

func main() {
    const source = `package demo
// 配置中的端口和值
port = 8080`

    var s scanner.Scanner
    // Init 接管 Reader，并恢复默认的 GoTokens 与 GoWhitespace。
    s.Init(strings.NewReader(source))
    s.Filename = "config.demo"
    // 把词法错误交给调用方，避免默认直接输出到标准错误。
    s.Error = func(sc *scanner.Scanner, msg string) {
        fmt.Printf("scan error at %s: %s\\n", sc.Position, msg)
    }

    for tok := s.Scan(); tok != scanner.EOF; tok = s.Scan() {
        // Position 是最近词元的起点，TokenText 是该词元的原文。
        fmt.Printf("%s token=%s text=%q\\n", s.Position, scanner.TokenString(tok), s.TokenText())
    }
}

这里的循环只负责“拿到下一个词元”。如果输入含有注释，默认模式会识别并跳过注释；如果要把注释交给后续工具处理，再显式调整 Mode。这也是它适合配置片段、模板表达式和小型 DSL 预处理的原因：词元化和业务语义可以分开。

Position 与 Pos 记录的是两个不同时刻

排查定位偏差时，我会把“词元起点”和“扫描器当前位置”分成两个字段。s.Position 是最近一次 Scan 返回的词元起点；s.Pos() 返回最近一次 Scan 或 Next 之后的位置，通常更接近下一个字符的起点。它们相差一个词元的长度并不奇怪。

func scanWithPositions(input string) {
    var s scanner.Scanner
    // 用 Reader 输入文本，保留文件名让错误位置更容易追踪。
    s.Init(strings.NewReader(input))
    s.Filename = "snippet.go"

    for tok := s.Scan(); tok != scanner.EOF; tok = s.Scan() {
        start := s.Position
        end := s.Pos()
        // start 用于标记当前词元，end 用于记录扫描器已经走到哪里。
        fmt.Printf("%s -> %s, %q -> %s\\n", start, scanner.TokenString(tok), s.TokenText(), end)
    }
}

如果要给诊断信息加下划线或高亮，使用 Position.Offset 与输入字节切片时要记住：Offset 是字节偏移，而 Column 按字符计数。中文或其他多字节字符存在时，不能用列号直接当作字节索引。

Mode 和 Whitespace 要跟任务一起改

默认设置适合“像 Go 源码一样读”。如果只是读取标识符、整数和字符串，可以缩小模式，降低业务层收到的无关词元数量。注释是否跳过也要成对配置：设置 ScanComments 才会识别注释，再配合 SkipComments 把注释当空白跳过。

func scanIdentifiersAndStrings(input string) {
    var s scanner.Scanner
    // 只保留标识符、整数、字符串和注释识别，避免误把浮点数当成目标输入。
    s.Init(strings.NewReader(input))
    s.Mode = scanner.ScanIdents | scanner.ScanInts |
        scanner.ScanStrings | scanner.ScanComments | scanner.SkipComments
    // 不跳过换行时，把换行从 Whitespace 位图中移除，便于做行级诊断。
    s.Whitespace = 1

Whitespace 是按 rune 位设置的位图，不是字符串列表。把换行移出后，换行会以普通字符返回；如果把回车、制表和空格也移出，输入中的格式字符就会进入后续判断。修改前先写清楚 DSL 需要哪些空白，否则很容易把“换行代表一条记录”的语义吞掉。

异常出现时先区分 EOF、词元错误和读取错误

一次扫描结束不等于一定成功。scanner.EOF 只表示没有更多输入；扫描器遇到非法词元或底层 Reader 读取失败时，会通过 Error 回调报告。生产代码里建议把回调转换为带文件名和位置的诊断对象，循环结束后再根据业务决定是否中止。

如果需求是完整 Go 源码解析，应该转向 go/scanner 与 go/token，再接 AST；text/scanner 只负责通用 UTF-8 词元化。这个回退判断很重要：继续堆 Mode 不能替代语法树，也不能自动理解括号嵌套、声明作用域或类型信息。

最后的排查清单

• 词元文本为空或位置错位：确认是在 Scan 之后读取 TokenText 和 Position。
• 换行没有进入业务逻辑：检查 Whitespace 是否把换行保留为非空白字符。
• 注释处理不符合预期：确认 ScanComments 与 SkipComments 的组合。
• 中文定位错一列：区分字节 Offset 与按字符计数的 Column。
• 需求已经涉及语法结构：停止扩展扫描模式，改用 go/scanner 和 AST 工具链。

相关问题

text/scanner.Scanner 能直接解析完整 Go 文件吗？

不能。它能识别词元，但不构建 Go AST；完整源码分析应使用 go/parser、go/ast 等工具。

为什么 Position.Offset 和 Column 不一样？

Offset 从输入开头按字节计数，Column 在当前行按字符计数，多字节 UTF-8 字符会让两者自然不同。