import "go/types"
Package types declares the data types and implements the algorithms for type-checking of Go packages. Use Config.Check to invoke the type checker for a package. Alternatively, create a new type checker with NewChecker and invoke it incrementally by calling Checker.Files.
Type-checking consists of several interdependent phases:
Name resolution maps each identifier (ast.Ident) in the program to the language object (Object) it denotes. Use Info.{Defs,Uses,Implicits} for the results of name resolution.
Constant folding computes the exact constant value (constant.Value) for every expression (ast.Expr) that is a compile-time constant. Use Info.Types[expr].Value for the results of constant folding.
Type inference computes the type (Type) of every expression (ast.Expr) and checks for compliance with the language specification. Use Info.Types[expr].Type for the results of type inference.
For a tutorial, see https://github.com/golang/go/blob/master/s/types-tutorial.
api.go assignments.go builtins.go call.go check.go conversions.go decl.go errors.go eval.go expr.go exprstring.go initorder.go labels.go lookup.go methodset.go object.go objset.go operand.go ordering.go package.go predicates.go resolver.go return.go scope.go selection.go sizes.go stmt.go type.go typestring.go typexpr.go universe.go
AssertableTo reports whether a value of type V can be asserted to have type T.
AssignableTo reports whether a value of type V is assignable to a variable of type T.
Comparable reports whether values of type T are comparable.
ConvertibleTo reports whether a value of type V is convertible to a value of type T.
DefPredeclaredTestFuncs defines the assert and trace built-ins. These built-ins are intended for debugging and testing of this package only.
ExprString returns the (possibly simplified) string representation for x.
Id returns name if it is exported, otherwise it returns the name qualified with the package path.
Identical reports whether x and y are identical.
IdenticalIgnoreTags reports whether x and y are identical if tags are ignored.
Implements reports whether type V implements interface T.
IsInterface reports whether typ is an interface type.
ObjectString returns the string form of obj. The Qualifier controls the printing of package-level objects, and may be nil.
SelectionString returns the string form of s. The Qualifier controls the printing of package-level objects, and may be nil.
Examples:
"field (T) f int" "method (T) f(X) Y" "method expr (T) f(X) Y"
TypeString returns the string representation of typ. The Qualifier controls the printing of package-level objects, and may be nil.
WriteExpr writes the (possibly simplified) string representation for x to buf.
WriteSignature writes the representation of the signature sig to buf, without a leading "func" keyword. The Qualifier controls the printing of package-level objects, and may be nil.
WriteType writes the string representation of typ to buf. The Qualifier controls the printing of package-level objects, and may be nil.
An Array represents an array type.
NewArray returns a new array type for the given element type and length.
Elem returns element type of array a.
Len returns the length of array a.
A Basic represents a basic type.
Info returns information about properties of basic type b.
Kind returns the kind of basic type b.
Name returns the name of basic type b.
BasicInfo is a set of flags describing properties of a basic type.
Properties of basic types.
BasicKind describes the kind of basic type.
A Builtin represents a built-in function. Builtins don't have a valid type.
A Chan represents a channel type.
NewChan returns a new channel type for the given direction and element type.
Dir returns the direction of channel c.
Elem returns the element type of channel c.
A ChanDir value indicates a channel direction.
The direction of a channel is indicated by one of these constants.
A Checker maintains the state of the type checker. It must be created with NewChecker.
NewChecker returns a new Checker instance for a given package. Package files may be added incrementally via checker.Files.
Files checks the provided files as part of the checker's package.
A Config specifies the configuration for type checking. The zero value for Config is a ready-to-use default configuration.
Check type-checks a package and returns the resulting package object and the first error if any. Additionally, if info != nil, Check populates each of the non-nil maps in the Info struct.
The package is marked as complete if no errors occurred, otherwise it is incomplete. See Config.Error for controlling behavior in the presence of errors.
The package is specified by a list of *ast.Files and corresponding file set, and the package path the package is identified with. The clean path must not be empty or dot (".").
A Const represents a declared constant.
An Error describes a type-checking error; it implements the error interface. A "soft" error is an error that still permits a valid interpretation of a package (such as "unused variable"); "hard" errors may lead to unpredictable behavior if ignored.
Error returns an error string formatted as follows: filename:line:column: message
A Func represents a declared function, concrete method, or abstract (interface) method. Its Type() is always a *Signature. An abstract method may belong to many interfaces due to embedding.
MissingMethod returns (nil, false) if V implements T, otherwise it returns a missing method required by T and whether it is missing or just has the wrong type.
For non-interface types V, or if static is set, V implements T if all methods of T are present in V. Otherwise (V is an interface and static is not set), MissingMethod only checks that methods of T which are also present in V have matching types (e.g., for a type assertion x.(T) where x is of interface type V).
FullName returns the package- or receiver-type-qualified name of function or method obj.
ImportMode is reserved for future use.
An Importer resolves import paths to Packages.
CAUTION: This interface does not support the import of locally vendored packages. See https://github.com/golang/go/blob/master/s/go15vendor. If possible, external implementations should implement ImporterFrom.
An ImporterFrom resolves import paths to packages; it supports vendoring per https://github.com/golang/go/blob/master/s/go15vendor. Use go/importer to obtain an ImporterFrom implementation.
Info holds result type information for a type-checked package. Only the information for which a map is provided is collected. If the package has type errors, the collected information may be incomplete.
ExampleInfo prints various facts recorded by the type checker in a types.Info struct: definitions of and references to each named object, and the type, value, and mode of every expression in the package.
Code:
// Parse a single source file. const input = ` package fib type S string var a, b, c = len(b), S(c), "hello" func fib(x int) int { if x < 2 { return x } return fib(x-1) - fib(x-2) }` fset := token.NewFileSet() f, err := parser.ParseFile(fset, "fib.go", input, 0) if err != nil { log.Fatal(err) } // Type-check the package. // We create an empty map for each kind of input // we're interested in, and Check populates them. info := types.Info{ Types: make(map[ast.Expr]types.TypeAndValue), Defs: make(map[*ast.Ident]types.Object), Uses: make(map[*ast.Ident]types.Object), } var conf types.Config pkg, err := conf.Check("fib", fset, []*ast.File{f}, &info) if err != nil { log.Fatal(err) } // Print package-level variables in initialization order. fmt.Printf("InitOrder: %v\n\n", info.InitOrder) // For each named object, print the line and // column of its definition and each of its uses. fmt.Println("Defs and Uses of each named object:") usesByObj := make(map[types.Object][]string) for id, obj := range info.Uses { posn := fset.Position(id.Pos()) lineCol := fmt.Sprintf("%d:%d", posn.Line, posn.Column) usesByObj[obj] = append(usesByObj[obj], lineCol) } var items []string for obj, uses := range usesByObj { sort.Strings(uses) item := fmt.Sprintf("%s:\n defined at %s\n used at %s", types.ObjectString(obj, types.RelativeTo(pkg)), fset.Position(obj.Pos()), strings.Join(uses, ", ")) items = append(items, item) } sort.Strings(items) // sort by line:col, in effect fmt.Println(strings.Join(items, "\n")) fmt.Println() fmt.Println("Types and Values of each expression:") items = nil for expr, tv := range info.Types { var buf bytes.Buffer posn := fset.Position(expr.Pos()) tvstr := tv.Type.String() if tv.Value != nil { tvstr += " = " + tv.Value.String() } // line:col | expr | mode : type = value fmt.Fprintf(&buf, "%2d:%2d | %-19s | %-7s : %s", posn.Line, posn.Column, exprString(fset, expr), mode(tv), tvstr) items = append(items, buf.String()) } sort.Strings(items) fmt.Println(strings.Join(items, "\n"))
Output:
InitOrder: [c = "hello" b = S(c) a = len(b)] Defs and Uses of each named object: builtin len: defined at - used at 6:15 func fib(x int) int: defined at fib.go:8:6 used at 12:20, 12:9 type S string: defined at fib.go:4:6 used at 6:23 type int int: defined at - used at 8:12, 8:17 type string string: defined at - used at 4:8 var b S: defined at fib.go:6:8 used at 6:19 var c string: defined at fib.go:6:11 used at 6:25 var x int: defined at fib.go:8:10 used at 10:10, 12:13, 12:24, 9:5 Types and Values of each expression: 4: 8 | string | type : string 6:15 | len | builtin : func(string) int 6:15 | len(b) | value : int 6:19 | b | var : fib.S 6:23 | S | type : fib.S 6:23 | S(c) | value : fib.S 6:25 | c | var : string 6:29 | "hello" | value : string = "hello" 8:12 | int | type : int 8:17 | int | type : int 9: 5 | x | var : int 9: 5 | x < 2 | value : untyped bool 9: 9 | 2 | value : int = 2 10:10 | x | var : int 12: 9 | fib | value : func(x int) int 12: 9 | fib(x - 1) | value : int 12: 9 | fib(x-1) - fib(x-2) | value : int 12:13 | x | var : int 12:13 | x - 1 | value : int 12:15 | 1 | value : int = 1 12:20 | fib | value : func(x int) int 12:20 | fib(x - 2) | value : int 12:24 | x | var : int 12:24 | x - 2 | value : int 12:26 | 2 | value : int = 2
ObjectOf returns the object denoted by the specified id, or nil if not found.
If id is an anonymous struct field, ObjectOf returns the field (*Var) it uses, not the type (*TypeName) it defines.
Precondition: the Uses and Defs maps are populated.
TypeOf returns the type of expression e, or nil if not found. Precondition: the Types, Uses and Defs maps are populated.
An Initializer describes a package-level variable, or a list of variables in case of a multi-valued initialization expression, and the corresponding initialization expression.
An Interface represents an interface type.
NewInterface returns a new interface for the given methods and embedded types.
Complete computes the interface's method set. It must be called by users of NewInterface after the interface's embedded types are fully defined and before using the interface type in any way other than to form other types. Complete returns the receiver.
Embedded returns the i'th embedded type of interface t for 0 <= i < t.NumEmbeddeds(). The types are ordered by the corresponding TypeName's unique Id.
Empty returns true if t is the empty interface.
ExplicitMethod returns the i'th explicitly declared method of interface t for 0 <= i < t.NumExplicitMethods(). The methods are ordered by their unique Id.
Method returns the i'th method of interface t for 0 <= i < t.NumMethods(). The methods are ordered by their unique Id.
NumEmbeddeds returns the number of embedded types in interface t.
NumExplicitMethods returns the number of explicitly declared methods of interface t.
NumMethods returns the total number of methods of interface t.
A Label represents a declared label.
A Map represents a map type.
NewMap returns a new map for the given key and element types.
Elem returns the element type of map m.
Key returns the key type of map m.
A MethodSet is an ordered set of concrete or abstract (interface) methods; a method is a MethodVal selection, and they are ordered by ascending m.Obj().Id(). The zero value for a MethodSet is a ready-to-use empty method set.
ExampleMethodSet prints the method sets of various types.
Code:play
// Parse a single source file. const input = ` package temperature import "fmt" type Celsius float64 func (c Celsius) String() string { return fmt.Sprintf("%g°C", c) } func (c *Celsius) SetF(f float64) { *c = Celsius(f - 32 / 9 * 5) } ` fset := token.NewFileSet() f, err := parser.ParseFile(fset, "celsius.go", input, 0) if err != nil { log.Fatal(err) } // Type-check a package consisting of this file. // Type information for the imported packages // comes from $GOROOT/pkg/$GOOS_$GOOARCH/fmt.a. conf := types.Config{Importer: importer.Default()} pkg, err := conf.Check("temperature", fset, []*ast.File{f}, nil) if err != nil { log.Fatal(err) } // Print the method sets of Celsius and *Celsius. celsius := pkg.Scope().Lookup("Celsius").Type() for _, t := range []types.Type{celsius, types.NewPointer(celsius)} { fmt.Printf("Method set of %s:\n", t) mset := types.NewMethodSet(t) for i := 0; i < mset.Len(); i++ { fmt.Println(mset.At(i)) } fmt.Println() }
Output:
Method set of temperature.Celsius: method (temperature.Celsius) String() string Method set of *temperature.Celsius: method (*temperature.Celsius) SetF(f float64) method (*temperature.Celsius) String() string
NewMethodSet returns the method set for the given type T. It always returns a non-nil method set, even if it is empty.
At returns the i'th method in s for 0 <= i < s.Len().
Len returns the number of methods in s.
Lookup returns the method with matching package and name, or nil if not found.
A Named represents a named type.
NewNamed returns a new named type for the given type name, underlying type, and associated methods. The underlying type must not be a *Named.
AddMethod adds method m unless it is already in the method list. TODO(gri) find a better solution instead of providing this function
Method returns the i'th method of named type t for 0 <= i < t.NumMethods().
NumMethods returns the number of explicit methods whose receiver is named type t.
TypeName returns the type name for the named type t.
SetUnderlying sets the underlying type and marks t as complete. TODO(gri) determine if there's a better solution rather than providing this function
Nil represents the predeclared value nil.
An Object describes a named language entity such as a package, constant, type, variable, function (incl. methods), or label. All objects implement the Object interface.
LookupFieldOrMethod looks up a field or method with given package and name in T and returns the corresponding *Var or *Func, an index sequence, and a bool indicating if there were any pointer indirections on the path to the field or method. If addressable is set, T is the type of an addressable variable (only matters for method lookups).
The last index entry is the field or method index in the (possibly embedded) type where the entry was found, either:
1) the list of declared methods of a named type; or 2) the list of all methods (method set) of an interface type; or 3) the list of fields of a struct type.
The earlier index entries are the indices of the anonymous struct fields traversed to get to the found entry, starting at depth 0.
If no entry is found, a nil object is returned. In this case, the returned index and indirect values have the following meaning:
- If index != nil, the index sequence points to an ambiguous entry
(the same name appeared more than once at the same embedding level).
- If indirect is set, a method with a pointer receiver type was found
but there was no pointer on the path from the actual receiver type to
the method's formal receiver base type, nor was the receiver addressable.
A Package describes a Go package.
NewPackage returns a new Package for the given package path and name; the name must not be the blank identifier. The package is not complete and contains no explicit imports.
A package is complete if its scope contains (at least) all exported objects; otherwise it is incomplete.
Imports returns the list of packages directly imported by pkg; the list is in source order. Package unsafe is excluded.
If pkg was loaded from export data, Imports includes packages that provide package-level objects referenced by pkg. This may be more or less than the set of packages directly imported by pkg's source code.
MarkComplete marks a package as complete.
Name returns the package name.
Path returns the package path.
Scope returns the (complete or incomplete) package scope holding the objects declared at package level (TypeNames, Consts, Vars, and Funcs).
SetImports sets the list of explicitly imported packages to list. It is the caller's responsibility to make sure list elements are unique.
SetName sets the package name.
A PkgName represents an imported Go package.
Imported returns the package that was imported. It is distinct from Pkg(), which is the package containing the import statement.
A Pointer represents a pointer type.
NewPointer returns a new pointer type for the given element (base) type.
Elem returns the element type for the given pointer p.
A Qualifier controls how named package-level objects are printed in calls to TypeString, ObjectString, and SelectionString.
These three formatting routines call the Qualifier for each package-level object O, and if the Qualifier returns a non-empty string p, the object is printed in the form p.O. If it returns an empty string, only the object name O is printed.
Using a nil Qualifier is equivalent to using (*Package).Path: the object is qualified by the import path, e.g., "encoding/json.Marshal".
RelativeTo(pkg) returns a Qualifier that fully qualifies members of all packages other than pkg.
A Scope maintains a set of objects and links to its containing (parent) and contained (children) scopes. Objects may be inserted and looked up by name. The zero value for Scope is a ready-to-use empty scope.
ExampleScope prints the tree of Scopes of a package created from a set of parsed files.
Code:play
// Parse the source files for a package. fset := token.NewFileSet() var files []*ast.File for _, file := range []struct{ name, input string }{ {"main.go", ` package main import "fmt" func main() { freezing := FToC(-18) fmt.Println(freezing, Boiling) } `}, {"celsius.go", ` package main import "fmt" type Celsius float64 func (c Celsius) String() string { return fmt.Sprintf("%g°C", c) } func FToC(f float64) Celsius { return Celsius(f - 32 / 9 * 5) } const Boiling Celsius = 100 `}, } { f, err := parser.ParseFile(fset, file.name, file.input, 0) if err != nil { log.Fatal(err) } files = append(files, f) } // Type-check a package consisting of these files. // Type information for the imported "fmt" package // comes from $GOROOT/pkg/$GOOS_$GOOARCH/fmt.a. conf := types.Config{Importer: importer.Default()} pkg, err := conf.Check("temperature", fset, files, nil) if err != nil { log.Fatal(err) } // Print the tree of scopes. // For determinism, we redact addresses. var buf bytes.Buffer pkg.Scope().WriteTo(&buf, 0, true) rx := regexp.MustCompile(` 0x[a-fA-F0-9]*`) fmt.Println(rx.ReplaceAllString(buf.String(), ""))
Output:
package "temperature" scope {
. const temperature.Boiling temperature.Celsius
. type temperature.Celsius float64
. func temperature.FToC(f float64) temperature.Celsius
. func temperature.main()
. main.go scope {
. . package fmt
. . function scope {
. . . var freezing temperature.Celsius
. . }. }
. celsius.go scope {
. . package fmt
. . function scope {
. . . var c temperature.Celsius
. . }
. . function scope {
. . . var f float64
. . }. }}
NewScope returns a new, empty scope contained in the given parent scope, if any. The comment is for debugging only.
Child returns the i'th child scope for 0 <= i < NumChildren().
Contains returns true if pos is within the scope's extent. The result is guaranteed to be valid only if the type-checked AST has complete position information.
Innermost returns the innermost (child) scope containing pos. If pos is not within any scope, the result is nil. The result is also nil for the Universe scope. The result is guaranteed to be valid only if the type-checked AST has complete position information.
Insert attempts to insert an object obj into scope s. If s already contains an alternative object alt with the same name, Insert leaves s unchanged and returns alt. Otherwise it inserts obj, sets the object's parent scope if not already set, and returns nil.
Len() returns the number of scope elements.
Lookup returns the object in scope s with the given name if such an object exists; otherwise the result is nil.
LookupParent follows the parent chain of scopes starting with s until it finds a scope where Lookup(name) returns a non-nil object, and then returns that scope and object. If a valid position pos is provided, only objects that were declared at or before pos are considered. If no such scope and object exists, the result is (nil, nil).
Note that obj.Parent() may be different from the returned scope if the object was inserted into the scope and already had a parent at that time (see Insert, below). This can only happen for dot-imported objects whose scope is the scope of the package that exported them.
Names returns the scope's element names in sorted order.
NumChildren() returns the number of scopes nested in s.
Parent returns the scope's containing (parent) scope.
Pos and End describe the scope's source code extent [pos, end). The results are guaranteed to be valid only if the type-checked AST has complete position information. The extent is undefined for Universe and package scopes.
String returns a string representation of the scope, for debugging.
WriteTo writes a string representation of the scope to w, with the scope elements sorted by name. The level of indentation is controlled by n >= 0, with n == 0 for no indentation. If recurse is set, it also writes nested (children) scopes.
A Selection describes a selector expression x.f. For the declarations:
type T struct{ x int; E }
type E struct{}
func (e E) m() {}
var p *T
the following relations exist:
Selector Kind Recv Obj Type Index Indirect
p.x FieldVal T x int {0} true
p.m MethodVal *T m func (e *T) m() {1, 0} true
T.m MethodExpr T m func m(_ T) {1, 0} false
Index describes the path from x to f in x.f. The last index entry is the field or method index of the type declaring f; either:
1) the list of declared methods of a named type; or 2) the list of methods of an interface type; or 3) the list of fields of a struct type.
The earlier index entries are the indices of the embedded fields implicitly traversed to get from (the type of) x to f, starting at embedding depth 0.
Indirect reports whether any pointer indirection was required to get from x to f in x.f.
Kind returns the selection kind.
Obj returns the object denoted by x.f; a *Var for a field selection, and a *Func in all other cases.
Recv returns the type of x in x.f.
Type returns the type of x.f, which may be different from the type of f. See Selection for more information.
SelectionKind describes the kind of a selector expression x.f (excluding qualified identifiers).
A Signature represents a (non-builtin) function or method type.
NewSignature returns a new function type for the given receiver, parameters, and results, either of which may be nil. If variadic is set, the function is variadic, it must have at least one parameter, and the last parameter must be of unnamed slice type.
Params returns the parameters of signature s, or nil.
Recv returns the receiver of signature s (if a method), or nil if a function.
For an abstract method, Recv returns the enclosing interface either as a *Named or an *Interface. Due to embedding, an interface may contain methods whose receiver type is a different interface.
Results returns the results of signature s, or nil.
Variadic reports whether the signature s is variadic.
Sizes defines the sizing functions for package unsafe.
A Slice represents a slice type.
NewSlice returns a new slice type for the given element type.
Elem returns the element type of slice s.
StdSizes is a convenience type for creating commonly used Sizes. It makes the following simplifying assumptions:
- The size of explicitly sized basic types (int16, etc.) is the
specified size.
- The size of strings and interfaces is 2*WordSize.
- The size of slices is 3*WordSize.
- The size of an array of n elements corresponds to the size of
a struct of n consecutive fields of the array's element type.
- The size of a struct is the offset of the last field plus that
field's size. As with all element types, if the struct is used
in an array its size must first be aligned to a multiple of the
struct's alignment.
- All other types have size WordSize.
- Arrays and structs are aligned per spec definition; all other
types are naturally aligned with a maximum alignment MaxAlign.
*StdSizes implements Sizes.
A Struct represents a struct type.
NewStruct returns a new struct with the given fields and corresponding field tags. If a field with index i has a tag, tags[i] must be that tag, but len(tags) may be only as long as required to hold the tag with the largest index i. Consequently, if no field has a tag, tags may be nil.
Field returns the i'th field for 0 <= i < NumFields().
NumFields returns the number of fields in the struct (including blank and anonymous fields).
Tag returns the i'th field tag for 0 <= i < NumFields().
A Tuple represents an ordered list of variables; a nil *Tuple is a valid (empty) tuple. Tuples are used as components of signatures and to represent the type of multiple assignments; they are not first class types of Go.
NewTuple returns a new tuple for the given variables.
At returns the i'th variable of tuple t.
Len returns the number variables of tuple t.
A Type represents a type of Go. All types implement the Type interface.
Default returns the default "typed" type for an "untyped" type; it returns the incoming type for all other types. The default type for untyped nil is untyped nil.
TypeAndValue reports the type and value (for constants) of the corresponding expression.
Eval returns the type and, if constant, the value for the expression expr, evaluated at position pos of package pkg, which must have been derived from type-checking an AST with complete position information relative to the provided file set.
If the expression contains function literals, their bodies are ignored (i.e., the bodies are not type-checked).
If pkg == nil, the Universe scope is used and the provided position pos is ignored. If pkg != nil, and pos is invalid, the package scope is used. Otherwise, pos must belong to the package.
An error is returned if pos is not within the package or if the node cannot be evaluated.
Note: Eval should not be used instead of running Check to compute types and values, but in addition to Check. Eval will re-evaluate its argument each time, and it also does not know about the context in which an expression is used (e.g., an assignment). Thus, top- level untyped constants will return an untyped type rather then the respective context-specific type.
Addressable reports whether the corresponding expression is addressable (https://github.com/golang/go/blob/master/ref/spec#Address_operators).
Assignable reports whether the corresponding expression is assignable to (provided a value of the right type).
HasOk reports whether the corresponding expression may be used on the lhs of a comma-ok assignment.
IsBuiltin reports whether the corresponding expression denotes a (possibly parenthesized) built-in function.
IsNil reports whether the corresponding expression denotes the predeclared value nil.
IsType reports whether the corresponding expression specifies a type.
IsValue reports whether the corresponding expression is a value. Builtins are not considered values. Constant values have a non- nil Value.
IsVoid reports whether the corresponding expression is a function call without results.
A TypeName represents a declared type.
A Variable represents a declared variable (including function parameters and results, and struct fields).