gopkg.in/alecthomas/gometalinter.v3@v3.0.0/_linters/src/golang.org/x/tools/go/expect/expect.go (about) 1 // Copyright 2018 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Package expect provides support for interpreting structured comments in Go 7 source code as test expectations. 8 9 This is primarily intended for writing tests of things that process Go source 10 files, although it does not directly depend on the testing package. 11 12 Collect notes with the Extract or Parse functions, and use the 13 MatchBefore function to find matches within the lines the comments were on. 14 15 The interpretation of the notes depends on the application. 16 For example, the test suite for a static checking tool might 17 use a @diag note to indicate an expected diagnostic: 18 19 fmt.Printf("%s", 1) //@ diag("%s wants a string, got int") 20 21 By contrast, the test suite for a source code navigation tool 22 might use notes to indicate the positions of features of 23 interest, the actions to be performed by the test, 24 and their expected outcomes: 25 26 var x = 1 //@ x_decl 27 ... 28 print(x) //@ definition("x", x_decl) 29 print(x) //@ typeof("x", "int") 30 31 32 Note comment syntax 33 34 Note comments always start with the special marker @, which must be the 35 very first character after the comment opening pair, so //@ or /*@ with no 36 spaces. 37 38 This is followed by a comma separated list of notes. 39 40 A note always starts with an identifier, which is optionally followed by an 41 argument list. The argument list is surrounded with parentheses and contains a 42 comma-separated list of arguments. 43 The empty parameter list and the missing parameter list are distinguishable if 44 needed; they result in a nil or an empty list in the Args parameter respectively. 45 46 Arguments are either identifiers or literals. 47 The literals supported are the basic value literals, of string, float, integer 48 true, false or nil. All the literals match the standard go conventions, with 49 all bases of integers, and both quote and backtick strings. 50 There is one extra literal type, which is a string literal preceded by the 51 identifier "re" which is compiled to a regular expression. 52 */ 53 package expect 54 55 import ( 56 "bytes" 57 "fmt" 58 "go/token" 59 "regexp" 60 ) 61 62 // Note is a parsed note from an expect comment. 63 // It knows the position of the start of the comment, and the name and 64 // arguments that make up the note. 65 type Note struct { 66 Pos token.Pos // The position at which the note identifier appears 67 Name string // the name associated with the note 68 Args []interface{} // the arguments for the note 69 } 70 71 // ReadFile is the type of a function that can provide file contents for a 72 // given filename. 73 // This is used in MatchBefore to look up the content of the file in order to 74 // find the line to match the pattern against. 75 type ReadFile func(filename string) ([]byte, error) 76 77 // MatchBefore attempts to match a pattern in the line before the supplied pos. 78 // It uses the FileSet and the ReadFile to work out the contents of the line 79 // that end is part of, and then matches the pattern against the content of the 80 // start of that line up to the supplied position. 81 // The pattern may be either a simple string, []byte or a *regexp.Regexp. 82 // MatchBefore returns the range of the line that matched the pattern, and 83 // invalid positions if there was no match, or an error if the line could not be 84 // found. 85 func MatchBefore(fset *token.FileSet, readFile ReadFile, end token.Pos, pattern interface{}) (token.Pos, token.Pos, error) { 86 f := fset.File(end) 87 content, err := readFile(f.Name()) 88 if err != nil { 89 return token.NoPos, token.NoPos, fmt.Errorf("invalid file: %v", err) 90 } 91 position := f.Position(end) 92 startOffset := f.Offset(lineStart(f, position.Line)) 93 endOffset := f.Offset(end) 94 line := content[startOffset:endOffset] 95 matchStart, matchEnd := -1, -1 96 switch pattern := pattern.(type) { 97 case string: 98 bytePattern := []byte(pattern) 99 matchStart = bytes.Index(line, bytePattern) 100 if matchStart >= 0 { 101 matchEnd = matchStart + len(bytePattern) 102 } 103 case []byte: 104 matchStart = bytes.Index(line, pattern) 105 if matchStart >= 0 { 106 matchEnd = matchStart + len(pattern) 107 } 108 case *regexp.Regexp: 109 match := pattern.FindIndex(line) 110 if len(match) > 0 { 111 matchStart = match[0] 112 matchEnd = match[1] 113 } 114 } 115 if matchStart < 0 { 116 return token.NoPos, token.NoPos, nil 117 } 118 return f.Pos(startOffset + matchStart), f.Pos(startOffset + matchEnd), nil 119 } 120 121 // this functionality was borrowed from the analysisutil package 122 func lineStart(f *token.File, line int) token.Pos { 123 // Use binary search to find the start offset of this line. 124 // 125 // TODO(adonovan): eventually replace this function with the 126 // simpler and more efficient (*go/token.File).LineStart, added 127 // in go1.12. 128 129 min := 0 // inclusive 130 max := f.Size() // exclusive 131 for { 132 offset := (min + max) / 2 133 pos := f.Pos(offset) 134 posn := f.Position(pos) 135 if posn.Line == line { 136 return pos - (token.Pos(posn.Column) - 1) 137 } 138 139 if min+1 >= max { 140 return token.NoPos 141 } 142 143 if posn.Line < line { 144 min = offset 145 } else { 146 max = offset 147 } 148 } 149 }