...
▽

Package objectpath

import "golang.org/x/tools/go/types/objectpath"
Overview
Index

Overview ▾

Package objectpath defines a naming scheme for types.Objects (that is, named entities in Go programs) relative to their enclosing package.

Type-checker objects are canonical, so they are usually identified by their address in memory (a pointer), but a pointer has meaning only within one address space. By contrast, objectpath names allow the identity of an object to be sent from one program to another, establishing a correspondence between types.Object variables that are distinct but logically equivalent.

A single object may have multiple paths. In this example, 

type A struct{ X int }
type B A

the field X has two paths due to its membership of both A and B. The For(obj) function always returns one of these paths, arbitrarily but consistently.

func Object 

func Object(pkg *types.Package, p Path) (types.Object, error)

Object returns the object denoted by path p within the package pkg.

type Encoder

An Encoder amortizes the cost of encoding the paths of multiple objects. The zero value of an Encoder is ready to use. 

type Encoder struct {
    // contains filtered or unexported fields
}

func (*Encoder) For 

func (enc *Encoder) For(obj types.Object) (Path, error)

For returns the path to an object relative to its package, or an error if the object is not accessible from the package's Scope.

The For function guarantees to return a path only for the following objects: - package-level types - exported package-level non-types - methods - parameter and result variables - struct fields These objects are sufficient to define the API of their package. The objects described by a package's export data are drawn from this set.

The set of objects accessible from a package's Scope depends on whether the package was produced by type-checking syntax, or reading export data; the latter may have a smaller Scope since export data trims objects that are not reachable from an exported declaration. For example, the For function will return a path for an exported method of an unexported type that is not reachable from any public declaration; this path will cause the Object function to fail if called on a package loaded from export data. TODO(adonovan): is this a bug or feature? Should this package compute accessibility in the same way?

For does not return a path for predeclared names, imported package names, local names, and unexported package-level names (except types).

Example: given this definition, 

package p

type T interface {
	f() (a string, b struct{ X int })
}

For(X) would return a path that denotes the following sequence of operations: 

p.Scope().Lookup("T")				(TypeName T)
.Type().Underlying().Method(0).			(method Func f)
.Type().Results().At(1)				(field Var b)
.Type().Field(0)					(field Var X)

where p is the package (*types.Package) to which X belongs.

type Path

A Path is an opaque name that identifies a types.Object relative to its package. Conceptually, the name consists of a sequence of destructuring operations applied to the package scope to obtain the original object. The name does not include the package itself. 

type Path string

func For 

func For(obj types.Object) (Path, error)

For is equivalent to new(Encoder).For(obj).

It may be more efficient to reuse a single Encoder across several calls.