| 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 |
Members