1 // Copyright 2010 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.
5 // Package stdmethods defines an Analyzer that checks for misspellings
6 // in the signatures of methods similar to well-known interfaces.
14 "golang.org/x/tools/go/analysis"
15 "golang.org/x/tools/go/analysis/passes/inspect"
16 "golang.org/x/tools/go/ast/inspector"
19 const Doc = `check signature of methods of well-known interfaces
21 Sometimes a type may be intended to satisfy an interface but may fail to
22 do so because of a mistake in its method signature.
23 For example, the result of this WriteTo method should be (int64, error),
24 not error, to satisfy io.WriterTo:
26 type myWriterTo struct{...}
27 func (myWriterTo) WriteTo(w io.Writer) error { ... }
29 This check ensures that each method whose name matches one of several
30 well-known interface methods from the standard library has the correct
31 signature for that interface.
33 Checked method names include:
34 Format GobEncode GobDecode MarshalJSON MarshalXML
35 Peek ReadByte ReadFrom ReadRune Scan Seek
36 UnmarshalJSON UnreadByte UnreadRune WriteByte
40 var Analyzer = &analysis.Analyzer{
43 Requires: []*analysis.Analyzer{inspect.Analyzer},
47 // canonicalMethods lists the input and output types for Go methods
48 // that are checked using dynamic interface checks. Because the
49 // checks are dynamic, such methods would not cause a compile error
50 // if they have the wrong signature: instead the dynamic check would
51 // fail, sometimes mysteriously. If a method is found with a name listed
52 // here but not the input/output types listed here, vet complains.
54 // A few of the canonical methods have very common names.
55 // For example, a type might implement a Scan method that
56 // has nothing to do with fmt.Scanner, but we still want to check
57 // the methods that are intended to implement fmt.Scanner.
58 // To do that, the arguments that have a = prefix are treated as
59 // signals that the canonical meaning is intended: if a Scan
60 // method doesn't have a fmt.ScanState as its first argument,
61 // we let it go. But if it does have a fmt.ScanState, then the
63 var canonicalMethods = map[string]struct{ args, results []string }{
64 // "Flush": {{}, {"error"}}, // http.Flusher and jpeg.writer conflict
65 "Format": {[]string{"=fmt.State", "rune"}, []string{}}, // fmt.Formatter
66 "GobDecode": {[]string{"[]byte"}, []string{"error"}}, // gob.GobDecoder
67 "GobEncode": {[]string{}, []string{"[]byte", "error"}}, // gob.GobEncoder
68 "MarshalJSON": {[]string{}, []string{"[]byte", "error"}}, // json.Marshaler
69 "MarshalXML": {[]string{"*xml.Encoder", "xml.StartElement"}, []string{"error"}}, // xml.Marshaler
70 "ReadByte": {[]string{}, []string{"byte", "error"}}, // io.ByteReader
71 "ReadFrom": {[]string{"=io.Reader"}, []string{"int64", "error"}}, // io.ReaderFrom
72 "ReadRune": {[]string{}, []string{"rune", "int", "error"}}, // io.RuneReader
73 "Scan": {[]string{"=fmt.ScanState", "rune"}, []string{"error"}}, // fmt.Scanner
74 "Seek": {[]string{"=int64", "int"}, []string{"int64", "error"}}, // io.Seeker
75 "UnmarshalJSON": {[]string{"[]byte"}, []string{"error"}}, // json.Unmarshaler
76 "UnmarshalXML": {[]string{"*xml.Decoder", "xml.StartElement"}, []string{"error"}}, // xml.Unmarshaler
77 "UnreadByte": {[]string{}, []string{"error"}},
78 "UnreadRune": {[]string{}, []string{"error"}},
79 "WriteByte": {[]string{"byte"}, []string{"error"}}, // jpeg.writer (matching bufio.Writer)
80 "WriteTo": {[]string{"=io.Writer"}, []string{"int64", "error"}}, // io.WriterTo
83 func run(pass *analysis.Pass) (interface{}, error) {
84 inspect := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
86 nodeFilter := []ast.Node{
88 (*ast.InterfaceType)(nil),
90 inspect.Preorder(nodeFilter, func(n ast.Node) {
91 switch n := n.(type) {
94 canonicalMethod(pass, n.Name)
96 case *ast.InterfaceType:
97 for _, field := range n.Methods.List {
98 for _, id := range field.Names {
99 canonicalMethod(pass, id)
107 func canonicalMethod(pass *analysis.Pass, id *ast.Ident) {
108 // Expected input/output.
109 expect, ok := canonicalMethods[id.Name]
114 // Actual input/output
115 sign := pass.TypesInfo.Defs[id].Type().(*types.Signature)
116 args := sign.Params()
117 results := sign.Results()
119 // Special case: WriteTo with more than one argument,
120 // not trying at all to implement io.WriterTo,
121 // comes up often enough to skip.
122 if id.Name == "WriteTo" && args.Len() > 1 {
126 // Do the =s (if any) all match?
127 if !matchParams(pass, expect.args, args, "=") || !matchParams(pass, expect.results, results, "=") {
131 // Everything must match.
132 if !matchParams(pass, expect.args, args, "") || !matchParams(pass, expect.results, results, "") {
133 expectFmt := id.Name + "(" + argjoin(expect.args) + ")"
134 if len(expect.results) == 1 {
135 expectFmt += " " + argjoin(expect.results)
136 } else if len(expect.results) > 1 {
137 expectFmt += " (" + argjoin(expect.results) + ")"
140 actual := typeString(sign)
141 actual = strings.TrimPrefix(actual, "func")
142 actual = id.Name + actual
144 pass.ReportRangef(id, "method %s should have signature %s", actual, expectFmt)
148 func typeString(typ types.Type) string {
149 return types.TypeString(typ, (*types.Package).Name)
152 func argjoin(x []string) string {
153 y := make([]string, len(x))
154 for i, s := range x {
160 return strings.Join(y, ", ")
163 // Does each type in expect with the given prefix match the corresponding type in actual?
164 func matchParams(pass *analysis.Pass, expect []string, actual *types.Tuple, prefix string) bool {
165 for i, x := range expect {
166 if !strings.HasPrefix(x, prefix) {
169 if i >= actual.Len() {
172 if !matchParamType(x, actual.At(i).Type()) {
176 if prefix == "" && actual.Len() > len(expect) {
182 // Does this one type match?
183 func matchParamType(expect string, actual types.Type) bool {
184 expect = strings.TrimPrefix(expect, "=")
185 // Overkill but easy.
186 return typeString(actual) == expect