# package scanner `import "text/scanner"` scanner包提供对utf-8文本的token扫描服务。它会从一个io.Reader获取utf-8文本，通过对Scan方法的重复调用获取一个个token。为了兼容已有的工具，NUL字符不被接受。如果第一个字符是表示utf-8编码格式的BOM标记，会自动忽略该标记。 一般Scanner会跳过空白和Go注释，并会识别所有go语言规格的字面量。它可以定制为只识别这些字面量的一个子集，也可以识别不同的空白字符。 基本使用模式： ``` var s scanner.Scanner s.Init(src) tok := s.Scan() for tok != scanner.EOF { // do something with tok tok = s.Scan() } ``` ## Index * [Constants](#pkg-constants) * [func TokenString(tok rune) string](#TokenString) * [type Position](#Position) * [func (pos \*Position) IsValid() bool](#Position.IsValid) * [func (pos Position) String() string](#Position.String) * [type Scanner](#Scanner) * [func (s \*Scanner) Init(src io.Reader) \*Scanner](#Scanner.Init) * [func (s \*Scanner) Pos() (pos Position)](#Scanner.Pos) * [func (s \*Scanner) Peek() rune](#Scanner.Peek) * [func (s \*Scanner) Next() rune](#Scanner.Next) * [func (s \*Scanner) Scan() rune](#Scanner.Scan) * [func (s \*Scanner) TokenText() string](#Scanner.TokenText) ## Constants ``` const ( ScanIdents = 1 << -Ident ScanInts = 1 << -Int ScanFloats = 1 << -Float // 包括整数 ScanChars = 1 << -Char ScanStrings = 1 << -String ScanRawStrings = 1 << -RawString ScanComments = 1 << -Comment SkipComments = 1 << -skipComment // 如设置了ScanComments就视注释为空白 GoTokens = ScanIdents | ScanFloats | ScanChars | ScanStrings | ScanRawStrings | ScanComments | SkipComments ) ``` 预定义的状态位，用于控制token的识别。例如，如要设置Scanner只识别标识符、整数、跳过注释，可以将Scanner的状态字段设为： ``` ScanIdents | ScanInts | SkipComments ``` ``` const ( EOF = -(iota + 1) Ident Int Float Char String RawString Comment ) ``` 扫描的结果是上面的一个token或者一个Unicode字符。 ``` const GoWhitespace = 1<<'\t' | 1<<'\n' | 1<<'\r' | 1<<' ' ``` GoWhitespace是一个Scanner的Whitespace字段的默认值，该值确定go的空白字符。 ## func [TokenString](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L108 "View Source") ``` func TokenString(tok rune) string ``` TokenString返回一个token或unicode码值的可打印的字符串表示。 ## type [Position](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L41 "View Source") ``` type Position struct { Filename string // 文件名（如果存在） Offset int // 偏移量，从0开始 Line int // 行号，从1开始 Column int // 列号，从1开始（每行第几个字符） } ``` 代表资源里的一个位置。 ### func (\*Position) [IsValid](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L49 "View Source") ``` func (pos *Position) IsValid() bool ``` IsValid返回所处的位置是否合法。 ### func (Position) [String](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L51 "View Source") ``` func (pos Position) String() string ``` ## type [Scanner](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L122 "View Source") ``` type Scanner struct { // 每一次出现错误时都会调用该函数；如果Error为nil，则会将错误报告到os.Stderr。 Error func(s *Scanner, msg string) // 每一次出现错误时，ErrorCount++ ErrorCount int // 控制那些token被识别。如要识别整数，就将Mode的ScanInts位设为1。随时都可以修改Mode。 Mode uint // 控制那些字符识别为空白。如果要将一个码值小于32的字符视为空白，只需将码值对应的位设为1； // 空格码值是32，大于32的位设为1的行为未定义。随时都可以修改Whitespace。 Whitespace uint64 // 最近一次扫描到的token的开始位置，由Scan方法设定 // 调用Init或Next方法会使位置无效（Line==0），Scanner不会操作Position.Filename字段 // 如果发生错误且Position不合法，此时扫描位置不在token内，应调用Pos获取错误发生的位置 Position // 内含隐藏或非导出字段 } ``` Scanner类型实现了token和unicode字符（从io.Reader中）的读取。 ### func (\*Scanner) [Init](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L179 "View Source") ``` func (s *Scanner) Init(src io.Reader) *Scanner ``` Init使用src创建一个Scanner，并将Error设为nil，ErrorCount设为0，Mode设为GoTokens，Whitespace 设为GoWhitespace。 ### func (\*Scanner) [Pos](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L631 "View Source") ``` func (s *Scanner) Pos() (pos Position) ``` Pos方法返回上一次调用Next或Scan方法后读取结束时的位置。 ### func (\*Scanner) [Peek](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L313 "View Source") ``` func (s *Scanner) Peek() rune ``` Peek方法返回资源的下一个unicode字符而不移动扫描位置。如果扫描位置在资源的结尾会返回EOF。 ### func (\*Scanner) [Next](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L302 "View Source") ``` func (s *Scanner) Next() rune ``` Next读取并返回下一个unicode字符。到达资源结尾时会返回EOF。如果s.Error非nil，本方法会调用该字段汇报错误；否则将错误信息发送到os.Stderr。Next不会更新Scanner的Position字段，请使用Pos方法获取当前位置。 ### func (\*Scanner) [Scan](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L531 "View Source") ``` func (s *Scanner) Scan() rune ``` Scan方法从资源读取下一个token或者unicode字符并返回它。本方法只会识别Mode字段指定的token种类。如果到达资源结尾会返回EOF。如果s.Error非nil，本方法会调用该字段汇报错误；否则将错误信息发送到os.Stderr。 ### func (\*Scanner) [TokenText](https://github.com/golang/go/blob/master/src/text/scanner/scanner.go#L653 "View Source") ``` func (s *Scanner) TokenText() string ``` TokenText方法返回最近一次扫描的token对应的字符串。应该在Scan方法后调用。