version: 1.10

package scanner

import "text/scanner"

Overview

Package scanner provides a scanner and tokenizer for UTF-8-encoded text. It
takes an io.Reader providing the source, which then can be tokenized through
repeated calls to the Scan function. For compatibility with existing tools, the
NUL character is not allowed. If the first character in the source is a UTF-8
encoded byte order mark (BOM), it is discarded.

By default, a Scanner skips white space and Go comments and recognizes all
literals as defined by the Go language specification. It may be customized to
recognize only a subset of those literals and to recognize different identifier
and white space characters.


Example:

  1. const src = `
  2. // This is scanned code.
  3. if a > 10 {
  4.     someParsable = text
  5. }`
  6. var s scanner.Scanner
  7. s.Init(strings.NewReader(src))
  8. s.Filename = "example"
  9. for tok := s.Scan(); tok != scanner.EOF; tok = s.Scan() {
  10.     fmt.Printf("%s: %s\n", s.Position, s.TokenText())
  11. }
  13. // Output:
  14. // example:3:1: if
  15. // example:3:4: a
  16. // example:3:6: >
  17. // example:3:8: 10
  18. // example:3:11: {
  19. // example:4:2: someParsable
  20. // example:4:15: =
  21. // example:4:17: text
  22. // example:5:1: }

Index

Examples

Package files

scanner.go

Constants

  1. const (
  2.     ScanIdents     = 1 << -Ident
  3.     ScanInts       = 1 << -Int
  4.     ScanFloats     = 1 << -Float // includes Ints
  5.     ScanChars      = 1 << -Char
  6.     ScanStrings    = 1 << -String
  7.     ScanRawStrings = 1 << -RawString
  8.     ScanComments   = 1 << -Comment
  9.     SkipComments   = 1 << -skipComment // if set with ScanComments, comments become white space
  10.     GoTokens       = ScanIdents | ScanFloats | ScanChars | ScanStrings | ScanRawStrings | ScanComments | SkipComments
  11. )

Predefined mode bits to control recognition of tokens. For instance, to
configure a Scanner such that it only recognizes (Go) identifiers, integers, and
skips comments, set the Scanner’s Mode field to:

  1. ScanIdents | ScanInts | SkipComments

With the exceptions of comments, which are skipped if SkipComments is set,
unrecognized tokens are not ignored. Instead, the scanner simply returns the
respective individual characters (or possibly sub-tokens). For instance, if the
mode is ScanIdents (not ScanStrings), the string “foo” is scanned as the token
sequence ‘“‘ Ident ‘“‘.

  1. const (
  2.     EOF = -(iota + 1)
  3.     Ident
  4.     Int
  5.     Float
  6.     Char
  7.     String
  8.     RawString
  9.     Comment
  10. )

The result of Scan is one of these tokens or a Unicode character.

  1. const GoWhitespace = 1<<'\t' | 1<<'\n' | 1<<'\r' | 1<<' '

GoWhitespace is the default value for the Scanner’s Whitespace field. Its value
selects Go’s white space characters.

func TokenString

  1. func TokenString(tok rune) string

TokenString returns a printable string for a token or Unicode character.

type Position

  1. type Position struct {
  2.     Filename string // filename, if any
  3.     Offset   int    // byte offset, starting at 0
  4.     Line     int    // line number, starting at 1
  5.     Column   int    // column number, starting at 1 (character count per line)
  6. }

A source position is represented by a Position value. A position is valid if
Line > 0.

func (*Position) IsValid

  1. func (pos *Position) IsValid() bool

IsValid reports whether the position is valid.

func (Position) String

  1. func (pos Position) String() string

type Scanner

  1. type Scanner struct {
  2.  
  3.     // Error is called for each error encountered. If no Error
  4.     // function is set, the error is reported to os.Stderr.
  5.     Error func(s *Scanner, msg string)
  6.  
  7.     // ErrorCount is incremented by one for each error encountered.
  8.     ErrorCount int
  9.  
  10.     // The Mode field controls which tokens are recognized. For instance,
  11.     // to recognize Ints, set the ScanInts bit in Mode. The field may be
  12.     // changed at any time.
  13.     Mode uint
  14.  
  15.     // The Whitespace field controls which characters are recognized
  16.     // as white space. To recognize a character ch <= ' ' as white space,
  17.     // set the ch'th bit in Whitespace (the Scanner's behavior is undefined
  18.     // for values ch > ' '). The field may be changed at any time.
  19.     Whitespace uint64
  20.  
  21.     // IsIdentRune is a predicate controlling the characters accepted
  22.     // as the ith rune in an identifier. The set of valid characters
  23.     // must not intersect with the set of white space characters.
  24.     // If no IsIdentRune function is set, regular Go identifiers are
  25.     // accepted instead. The field may be changed at any time.
  26.     IsIdentRune func(ch rune, i int) bool
  27.  
  28.     // Start position of most recently scanned token; set by Scan.
  29.     // Calling Init or Next invalidates the position (Line == 0).
  30.     // The Filename field is always left untouched by the Scanner.
  31.     // If an error is reported (via Error) and Position is invalid,
  32.     // the scanner is not inside a token. Call Pos to obtain an error
  33.     // position in that case, or to obtain the position immediately
  34.     // after the most recently scanned token.
  35.     Position
  36.     // contains filtered or unexported fields
  37. }

A Scanner implements reading of Unicode characters and tokens from an io.Reader.

func (*Scanner) Init

  1. func (s *Scanner) Init(src io.Reader) *Scanner

Init initializes a Scanner with a new source and returns s. Error is set to nil,
ErrorCount is set to 0, Mode is set to GoTokens, and Whitespace is set to
GoWhitespace.

func (*Scanner) Next

  1. func (s *Scanner) Next() rune

Next reads and returns the next Unicode character. It returns EOF at the end of
the source. It reports a read error by calling s.Error, if not nil; otherwise it
prints an error message to os.Stderr. Next does not update the Scanner’s
Position field; use Pos() to get the current position.

func (*Scanner) Peek

  1. func (s *Scanner) Peek() rune

Peek returns the next Unicode character in the source without advancing the
scanner. It returns EOF if the scanner’s position is at the last character of
the source.

func (*Scanner) Pos

  1. func (s *Scanner) Pos() (pos Position)

Pos returns the position of the character immediately after the character or
token returned by the last call to Next or Scan. Use the Scanner’s Position
field for the start position of the most recently scanned token.

func (*Scanner) Scan

  1. func (s *Scanner) Scan() rune

Scan reads the next token or Unicode character from source and returns it. It
only recognizes tokens t for which the respective Mode bit (1<<-t) is set. It
returns EOF at the end of the source. It reports scanner errors (read and token
errors) by calling s.Error, if not nil; otherwise it prints an error message to
os.Stderr.

func (*Scanner) TokenText

  1. func (s *Scanner) TokenText() string

TokenText returns the string corresponding to the most recently scanned token.
Valid after calling Scan().