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.
5 // Package serial defines the guru's schema for -json output.
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
11 // Query Result stream
12 // ----- -------------
15 // callstack CallStack
16 // definition Definition
18 // freevars FreeVar ...
19 // implements Implements
21 // pointsto PointsTo ...
22 // referrers ReferrersInitial ReferrersPackage ...
24 // whicherrs WhichErrs
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.
30 // A Peers is the result of a 'peers' query.
31 // If Allocs is empty, the selected channel can't point to anything.
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
41 // A "referrers" query emits a ReferrersInitial object followed by zero or
42 // more ReferrersPackage objects, one per package that contains a reference.
44 ReferrersInitial struct {
45 ObjPos string `json:"objpos,omitempty"` // location of the definition
46 Desc string `json:"desc"` // description of the denoted object
48 ReferrersPackage struct {
49 Package string `json:"package"`
50 Refs []Ref `json:"refs"` // non-empty list of references within this package
53 Pos string `json:"pos"` // location of all references
54 Text string `json:"text"` // text of the referring line
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
64 // A Callees is the result of a 'callees' query.
66 // Callees is nonempty unless the call was a dynamic call on a
67 // provably nil func or interface value.
70 Pos string `json:"pos"` // location of selected call site
71 Desc string `json:"desc"` // description of call site
72 Callees []*Callee `json:"callees"`
75 Name string `json:"name"` // full name of called function
76 Pos string `json:"pos"` // location of called function
80 // A Caller is one element of the slice returned by a 'callers' query.
81 // (Callstack also contains a similar slice.)
83 // The root of the callgraph has an unspecified "Caller" string.
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
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.
94 // If the Callers slice is empty, the function was unreachable in this
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.
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
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.
117 type Implements struct {
118 T ImplementsType `json:"type,omitempty"` // the queried type
119 AssignableTo []ImplementsType `json:"to,omitempty"` // types assignable to T
120 AssignableFrom []ImplementsType `json:"from,omitempty"` // interface types assignable from T
121 AssignableFromPtr []ImplementsType `json:"fromptr,omitempty"` // interface types assignable only from *T
123 // The following fields are set only if the query was a method.
124 // Assignable{To,From,FromPtr}Method[i] is the corresponding
125 // method of type Assignable{To,From,FromPtr}[i], or blank
126 // {"",""} if that type lacks the method.
127 Method *DescribeMethod `json:"method,omitempty"` // the queried method
128 AssignableToMethod []DescribeMethod `json:"to_method,omitempty"`
129 AssignableFromMethod []DescribeMethod `json:"from_method,omitempty"`
130 AssignableFromPtrMethod []DescribeMethod `json:"fromptr_method,omitempty"`
133 // An ImplementsType describes a single type as part of an 'implements' query.
134 type ImplementsType struct {
135 Name string `json:"name"` // full name of the type
136 Pos string `json:"pos"` // location of its definition
137 Kind string `json:"kind"` // "basic", "array", etc
140 // A SyntaxNode is one element of a stack of enclosing syntax nodes in
142 type SyntaxNode struct {
143 Description string `json:"desc"` // description of syntax tree
144 Start int `json:"start"` // start byte offset, 0-based
145 End int `json:"end"` // end byte offset
148 // A What is the result of the "what" query, which quickly identifies
149 // the selection, parsing only a single file. It is intended for use
150 // in low-latency GUIs.
152 Enclosing []SyntaxNode `json:"enclosing"` // enclosing nodes of syntax tree
153 Modes []string `json:"modes"` // query modes enabled for this selection.
154 SrcDir string `json:"srcdir,omitempty"` // $GOROOT src directory containing queried package
155 ImportPath string `json:"importpath,omitempty"` // import path of queried package
156 Object string `json:"object,omitempty"` // name of identified object, if any
157 SameIDs []string `json:"sameids,omitempty"` // locations of references to same object
160 // A PointsToLabel describes a pointer analysis label.
162 // A "label" is an object that may be pointed to by a pointer, map,
163 // channel, 'func', slice or interface. Labels include:
166 // - arrays created by literals (e.g. []byte("foo")) and conversions ([]byte(s))
167 // - stack- and heap-allocated variables (including composite literals)
168 // - arrays allocated by append()
169 // - channels, maps and arrays created by make()
170 // - and their subelements, e.g. "alloc.y[*].z"
172 type PointsToLabel struct {
173 Pos string `json:"pos"` // location of syntax that allocated the object
174 Desc string `json:"desc"` // description of the label
177 // A PointsTo is one element of the result of a 'pointsto' query on an
178 // expression. It describes a single pointer: its type and the set of
179 // "labels" it points to.
181 // If the pointer is of interface type, it will have one PTS entry
182 // describing each concrete type that it may contain. For each
183 // concrete type that is a pointer, the PTS entry describes the labels
184 // it may point to. The same is true for reflect.Values, except the
185 // dynamic types needn't be concrete.
187 type PointsTo struct {
188 Type string `json:"type"` // (concrete) type of the pointer
189 NamePos string `json:"namepos,omitempty"` // location of type defn, if Named
190 Labels []PointsToLabel `json:"labels,omitempty"` // pointed-to objects
193 // A DescribeValue is the additional result of a 'describe' query
194 // if the selection indicates a value or expression.
195 type DescribeValue struct {
196 Type string `json:"type"` // type of the expression
197 Value string `json:"value,omitempty"` // value of the expression, if constant
198 ObjPos string `json:"objpos,omitempty"` // location of the definition, if an Ident
199 TypesPos []Definition `json:"typespos,omitempty"` // location of the named types, that type consist of
202 type DescribeMethod struct {
203 Name string `json:"name"` // method name, as defined by types.Selection.String()
204 Pos string `json:"pos"` // location of the method's definition
207 // A DescribeType is the additional result of a 'describe' query
208 // if the selection indicates a type.
209 type DescribeType struct {
210 Type string `json:"type"` // the string form of the type
211 NamePos string `json:"namepos,omitempty"` // location of definition of type, if named
212 NameDef string `json:"namedef,omitempty"` // underlying definition of type, if named
213 Methods []DescribeMethod `json:"methods,omitempty"` // methods of the type
216 type DescribeMember struct {
217 Name string `json:"name"` // name of member
218 Type string `json:"type,omitempty"` // type of member (underlying, if 'type')
219 Value string `json:"value,omitempty"` // value of member (if 'const')
220 Pos string `json:"pos"` // location of definition of member
221 Kind string `json:"kind"` // one of {var,const,func,type}
222 Methods []DescribeMethod `json:"methods,omitempty"` // methods (if member is a type)
225 // A DescribePackage is the additional result of a 'describe' if
226 // the selection indicates a package.
227 type DescribePackage struct {
228 Path string `json:"path"` // import path of the package
229 Members []*DescribeMember `json:"members,omitempty"` // accessible members of the package
232 // A Describe is the result of a 'describe' query.
233 // It may contain an element describing the selected semantic entity
235 type Describe struct {
236 Desc string `json:"desc"` // description of the selected syntax node
237 Pos string `json:"pos"` // location of the selected syntax node
238 Detail string `json:"detail,omitempty"` // one of {package, type, value}, or "".
240 // At most one of the following fields is populated:
241 // the one specified by 'detail'.
242 Package *DescribePackage `json:"package,omitempty"`
243 Type *DescribeType `json:"type,omitempty"`
244 Value *DescribeValue `json:"value,omitempty"`
247 // A WhichErrs is the result of a 'whicherrs' query.
248 // It contains the position of the queried error and the possible globals,
249 // constants, and types it may point to.
250 type WhichErrs struct {
251 ErrPos string `json:"errpos,omitempty"` // location of queried error
252 Globals []string `json:"globals,omitempty"` // locations of globals
253 Constants []string `json:"constants,omitempty"` // locations of constants
254 Types []WhichErrsType `json:"types,omitempty"` // Types
257 type WhichErrsType struct {
258 Type string `json:"type,omitempty"`
259 Position string `json:"position,omitempty"`