1 // Copyright 2013 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 // Package serial defines the guru's schema for -json output. 6 // 7 // The output of a guru query is a stream of one or more JSON objects. 8 // This table shows the types of objects in the result stream for each 9 // query type. 10 // 11 // Query Result stream 12 // ----- ------------- 13 // callees Callees 14 // callers Caller ... 15 // callstack CallStack 16 // definition Definition 17 // describe Describe 18 // freevars FreeVar ... 19 // implements Implements 20 // peers Peers 21 // pointsto PointsTo ... 22 // referrers ReferrersInitial ReferrersPackage ... 23 // what What 24 // whicherrs WhichErrs 25 // 26 // All 'pos' strings in the output are of the form "file:line:col", 27 // where line is the 1-based line number and col is the 1-based byte index. 28 package serial 29 30 // A Peers is the result of a 'peers' query. 31 // If Allocs is empty, the selected channel can't point to anything. 32 type Peers struct { 33 Pos string `json:"pos"` // location of the selected channel op (<-) 34 Type string `json:"type"` // type of the selected channel 35 Allocs []string `json:"allocs,omitempty"` // locations of aliased make(chan) ops 36 Sends []string `json:"sends,omitempty"` // locations of aliased ch<-x ops 37 Receives []string `json:"receives,omitempty"` // locations of aliased <-ch ops 38 Closes []string `json:"closes,omitempty"` // locations of aliased close(ch) ops 39 } 40 41 // A "referrers" query emits a ReferrersInitial object followed by zero or 42 // more ReferrersPackage objects, one per package that contains a reference. 43 type ( 44 ReferrersInitial struct { 45 ObjPos string `json:"objpos,omitempty"` // location of the definition 46 Desc string `json:"desc"` // description of the denoted object 47 } 48 ReferrersPackage struct { 49 Package string `json:"package"` 50 Refs []Ref `json:"refs"` // non-empty list of references within this package 51 } 52 Ref struct { 53 Pos string `json:"pos"` // location of all references 54 Text string `json:"text"` // text of the referring line 55 } 56 ) 57 58 // A Definition is the result of a 'definition' query. 59 type Definition struct { 60 ObjPos string `json:"objpos,omitempty"` // location of the definition 61 Desc string `json:"desc"` // description of the denoted object 62 } 63 64 // A Callees is the result of a 'callees' query. 65 // 66 // Callees is nonempty unless the call was a dynamic call on a 67 // provably nil func or interface value. 68 type ( 69 Callees struct { 70 Pos string `json:"pos"` // location of selected call site 71 Desc string `json:"desc"` // description of call site 72 Callees []*Callee `json:"callees"` 73 } 74 Callee struct { 75 Name string `json:"name"` // full name of called function 76 Pos string `json:"pos"` // location of called function 77 } 78 ) 79 80 // A Caller is one element of the slice returned by a 'callers' query. 81 // (Callstack also contains a similar slice.) 82 // 83 // The root of the callgraph has an unspecified "Caller" string. 84 type Caller struct { 85 Pos string `json:"pos,omitempty"` // location of the calling function 86 Desc string `json:"desc"` // description of call site 87 Caller string `json:"caller"` // full name of calling function 88 } 89 90 // A CallStack is the result of a 'callstack' query. 91 // It indicates an arbitrary path from the root of the callgraph to 92 // the query function. 93 // 94 // If the Callers slice is empty, the function was unreachable in this 95 // analysis scope. 96 type CallStack struct { 97 Pos string `json:"pos"` // location of the selected function 98 Target string `json:"target"` // the selected function 99 Callers []Caller `json:"callers"` // enclosing calls, innermost first. 100 } 101 102 // A FreeVar is one element of the slice returned by a 'freevars' 103 // query. Each one identifies an expression referencing a local 104 // identifier defined outside the selected region. 105 type FreeVar struct { 106 Pos string `json:"pos"` // location of the identifier's definition 107 Kind string `json:"kind"` // one of {var,func,type,const,label} 108 Ref string `json:"ref"` // referring expression (e.g. "x" or "x.y.z") 109 Type string `json:"type"` // type of the expression 110 } 111 112 // An Implements contains the result of an 'implements' query. 113 // It describes the queried type, the set of named non-empty interface 114 // types to which it is assignable, and the set of named/*named types 115 // (concrete or non-empty interface) which may be assigned to it. 116 type Implements struct { 117 T ImplementsType `json:"type,omitempty"` // the queried type 118 AssignableTo []ImplementsType `json:"to,omitempty"` // types assignable to T 119 AssignableFrom []ImplementsType `json:"from,omitempty"` // interface types assignable from T 120 AssignableFromPtr []ImplementsType `json:"fromptr,omitempty"` // interface types assignable only from *T 121 122 // The following fields are set only if the query was a method. 123 // Assignable{To,From,FromPtr}Method[i] is the corresponding 124 // method of type Assignable{To,From,FromPtr}[i], or blank 125 // {"",""} if that type lacks the method. 126 Method *DescribeMethod `json:"method,omitempty"` // the queried method 127 AssignableToMethod []DescribeMethod `json:"to_method,omitempty"` 128 AssignableFromMethod []DescribeMethod `json:"from_method,omitempty"` 129 AssignableFromPtrMethod []DescribeMethod `json:"fromptr_method,omitempty"` 130 } 131 132 // An ImplementsType describes a single type as part of an 'implements' query. 133 type ImplementsType struct { 134 Name string `json:"name"` // full name of the type 135 Pos string `json:"pos"` // location of its definition 136 Kind string `json:"kind"` // "basic", "array", etc 137 } 138 139 // A SyntaxNode is one element of a stack of enclosing syntax nodes in 140 // a "what" query. 141 type SyntaxNode struct { 142 Description string `json:"desc"` // description of syntax tree 143 Start int `json:"start"` // start byte offset, 0-based 144 End int `json:"end"` // end byte offset 145 } 146 147 // A What is the result of the "what" query, which quickly identifies 148 // the selection, parsing only a single file. It is intended for use 149 // in low-latency GUIs. 150 type What struct { 151 Enclosing []SyntaxNode `json:"enclosing"` // enclosing nodes of syntax tree 152 Modes []string `json:"modes"` // query modes enabled for this selection. 153 SrcDir string `json:"srcdir,omitempty"` // $GOROOT src directory containing queried package 154 ImportPath string `json:"importpath,omitempty"` // import path of queried package 155 Object string `json:"object,omitempty"` // name of identified object, if any 156 SameIDs []string `json:"sameids,omitempty"` // locations of references to same object 157 } 158 159 // A PointsToLabel describes a pointer analysis label. 160 // 161 // A "label" is an object that may be pointed to by a pointer, map, 162 // channel, 'func', slice or interface. Labels include: 163 // - functions 164 // - globals 165 // - arrays created by literals (e.g. []byte("foo")) and conversions ([]byte(s)) 166 // - stack- and heap-allocated variables (including composite literals) 167 // - arrays allocated by append() 168 // - channels, maps and arrays created by make() 169 // - and their subelements, e.g. "alloc.y[*].z" 170 type PointsToLabel struct { 171 Pos string `json:"pos"` // location of syntax that allocated the object 172 Desc string `json:"desc"` // description of the label 173 } 174 175 // A PointsTo is one element of the result of a 'pointsto' query on an 176 // expression. It describes a single pointer: its type and the set of 177 // "labels" it points to. 178 // 179 // If the pointer is of interface type, it will have one PTS entry 180 // describing each concrete type that it may contain. For each 181 // concrete type that is a pointer, the PTS entry describes the labels 182 // it may point to. The same is true for reflect.Values, except the 183 // dynamic types needn't be concrete. 184 type PointsTo struct { 185 Type string `json:"type"` // (concrete) type of the pointer 186 NamePos string `json:"namepos,omitempty"` // location of type defn, if Named 187 Labels []PointsToLabel `json:"labels,omitempty"` // pointed-to objects 188 } 189 190 // A DescribeValue is the additional result of a 'describe' query 191 // if the selection indicates a value or expression. 192 type DescribeValue struct { 193 Type string `json:"type"` // type of the expression 194 Value string `json:"value,omitempty"` // value of the expression, if constant 195 ObjPos string `json:"objpos,omitempty"` // location of the definition, if an Ident 196 TypesPos []Definition `json:"typespos,omitempty"` // location of the named types, that type consist of 197 } 198 199 type DescribeMethod struct { 200 Name string `json:"name"` // method name, as defined by types.Selection.String() 201 Pos string `json:"pos"` // location of the method's definition 202 } 203 204 // A DescribeType is the additional result of a 'describe' query 205 // if the selection indicates a type. 206 type DescribeType struct { 207 Type string `json:"type"` // the string form of the type 208 NamePos string `json:"namepos,omitempty"` // location of definition of type, if named 209 NameDef string `json:"namedef,omitempty"` // underlying definition of type, if named 210 Methods []DescribeMethod `json:"methods,omitempty"` // methods of the type 211 } 212 213 type DescribeMember struct { 214 Name string `json:"name"` // name of member 215 Type string `json:"type,omitempty"` // type of member (underlying, if 'type') 216 Value string `json:"value,omitempty"` // value of member (if 'const') 217 Pos string `json:"pos"` // location of definition of member 218 Kind string `json:"kind"` // one of {var,const,func,type} 219 Methods []DescribeMethod `json:"methods,omitempty"` // methods (if member is a type) 220 } 221 222 // A DescribePackage is the additional result of a 'describe' if 223 // the selection indicates a package. 224 type DescribePackage struct { 225 Path string `json:"path"` // import path of the package 226 Members []*DescribeMember `json:"members,omitempty"` // accessible members of the package 227 } 228 229 // A Describe is the result of a 'describe' query. 230 // It may contain an element describing the selected semantic entity 231 // in detail. 232 type Describe struct { 233 Desc string `json:"desc"` // description of the selected syntax node 234 Pos string `json:"pos"` // location of the selected syntax node 235 Detail string `json:"detail,omitempty"` // one of {package, type, value}, or "". 236 237 // At most one of the following fields is populated: 238 // the one specified by 'detail'. 239 Package *DescribePackage `json:"package,omitempty"` 240 Type *DescribeType `json:"type,omitempty"` 241 Value *DescribeValue `json:"value,omitempty"` 242 } 243 244 // A WhichErrs is the result of a 'whicherrs' query. 245 // It contains the position of the queried error and the possible globals, 246 // constants, and types it may point to. 247 type WhichErrs struct { 248 ErrPos string `json:"errpos,omitempty"` // location of queried error 249 Globals []string `json:"globals,omitempty"` // locations of globals 250 Constants []string `json:"constants,omitempty"` // locations of constants 251 Types []WhichErrsType `json:"types,omitempty"` // Types 252 } 253 254 type WhichErrsType struct { 255 Type string `json:"type,omitempty"` 256 Position string `json:"position,omitempty"` 257 } 258