object.go

Documentation: go/types

     1  // Code generated by "go test -run=Generate -write=all"; DO NOT EDIT.
     2  
     3  // Copyright 2013 The Go Authors. All rights reserved.
     4  // Use of this source code is governed by a BSD-style
     5  // license that can be found in the LICENSE file.
     6  
     7  package types
     8  
     9  import (
    10  	"bytes"
    11  	"fmt"
    12  	"go/constant"
    13  	"go/token"
    14  	"unicode"
    15  	"unicode/utf8"
    16  )
    17  
    18  // An Object describes a named language entity such as a package,
    19  // constant, type, variable, function (incl. methods), or label.
    20  // All objects implement the Object interface.
    21  type Object interface {
    22  	Parent() *Scope // scope in which this object is declared; nil for methods and struct fields
    23  	Pos() token.Pos // position of object identifier in declaration
    24  	Pkg() *Package  // package to which this object belongs; nil for labels and objects in the Universe scope
    25  	Name() string   // package local object name
    26  	Type() Type     // object type
    27  	Exported() bool // reports whether the name starts with a capital letter
    28  	Id() string     // object name if exported, qualified name if not exported (see func Id)
    29  
    30  	// String returns a human-readable string of the object.
    31  	String() string
    32  
    33  	// order reflects a package-level object's source order: if object
    34  	// a is before object b in the source, then a.order() < b.order().
    35  	// order returns a value > 0 for package-level objects; it returns
    36  	// 0 for all other objects (including objects in file scopes).
    37  	order() uint32
    38  
    39  	// color returns the object's color.
    40  	color() color
    41  
    42  	// setType sets the type of the object.
    43  	setType(Type)
    44  
    45  	// setOrder sets the order number of the object. It must be > 0.
    46  	setOrder(uint32)
    47  
    48  	// setColor sets the object's color. It must not be white.
    49  	setColor(color color)
    50  
    51  	// setParent sets the parent scope of the object.
    52  	setParent(*Scope)
    53  
    54  	// sameId reports whether obj.Id() and Id(pkg, name) are the same.
    55  	sameId(pkg *Package, name string) bool
    56  
    57  	// scopePos returns the start position of the scope of this Object
    58  	scopePos() token.Pos
    59  
    60  	// setScopePos sets the start position of the scope for this Object.
    61  	setScopePos(pos token.Pos)
    62  }
    63  
    64  func isExported(name string) bool {
    65  	ch, _ := utf8.DecodeRuneInString(name)
    66  	return unicode.IsUpper(ch)
    67  }
    68  
    69  // Id returns name if it is exported, otherwise it
    70  // returns the name qualified with the package path.
    71  func Id(pkg *Package, name string) string {
    72  	if isExported(name) {
    73  		return name
    74  	}
    75  	// unexported names need the package path for differentiation
    76  	// (if there's no package, make sure we don't start with '.'
    77  	// as that may change the order of methods between a setup
    78  	// inside a package and outside a package - which breaks some
    79  	// tests)
    80  	path := "_"
    81  	// pkg is nil for objects in Universe scope and possibly types
    82  	// introduced via Eval (see also comment in object.sameId)
    83  	if pkg != nil && pkg.path != "" {
    84  		path = pkg.path
    85  	}
    86  	return path + "." + name
    87  }
    88  
    89  // An object implements the common parts of an Object.
    90  type object struct {
    91  	parent    *Scope
    92  	pos       token.Pos
    93  	pkg       *Package
    94  	name      string
    95  	typ       Type
    96  	order_    uint32
    97  	color_    color
    98  	scopePos_ token.Pos
    99  }
   100  
   101  // color encodes the color of an object (see Checker.objDecl for details).
   102  type color uint32
   103  
   104  // An object may be painted in one of three colors.
   105  // Color values other than white or black are considered grey.
   106  const (
   107  	white color = iota
   108  	black
   109  	grey // must be > white and black
   110  )
   111  
   112  func (c color) String() string {
   113  	switch c {
   114  	case white:
   115  		return "white"
   116  	case black:
   117  		return "black"
   118  	default:
   119  		return "grey"
   120  	}
   121  }
   122  
   123  // colorFor returns the (initial) color for an object depending on
   124  // whether its type t is known or not.
   125  func colorFor(t Type) color {
   126  	if t != nil {
   127  		return black
   128  	}
   129  	return white
   130  }
   131  
   132  // Parent returns the scope in which the object is declared.
   133  // The result is nil for methods and struct fields.
   134  func (obj *object) Parent() *Scope { return obj.parent }
   135  
   136  // Pos returns the declaration position of the object's identifier.
   137  func (obj *object) Pos() token.Pos { return obj.pos }
   138  
   139  // Pkg returns the package to which the object belongs.
   140  // The result is nil for labels and objects in the Universe scope.
   141  func (obj *object) Pkg() *Package { return obj.pkg }
   142  
   143  // Name returns the object's (package-local, unqualified) name.
   144  func (obj *object) Name() string { return obj.name }
   145  
   146  // Type returns the object's type.
   147  func (obj *object) Type() Type { return obj.typ }
   148  
   149  // Exported reports whether the object is exported (starts with a capital letter).
   150  // It doesn't take into account whether the object is in a local (function) scope
   151  // or not.
   152  func (obj *object) Exported() bool { return isExported(obj.name) }
   153  
   154  // Id is a wrapper for Id(obj.Pkg(), obj.Name()).
   155  func (obj *object) Id() string { return Id(obj.pkg, obj.name) }
   156  
   157  func (obj *object) String() string      { panic("abstract") }
   158  func (obj *object) order() uint32       { return obj.order_ }
   159  func (obj *object) color() color        { return obj.color_ }
   160  func (obj *object) scopePos() token.Pos { return obj.scopePos_ }
   161  
   162  func (obj *object) setParent(parent *Scope)   { obj.parent = parent }
   163  func (obj *object) setType(typ Type)          { obj.typ = typ }
   164  func (obj *object) setOrder(order uint32)     { assert(order > 0); obj.order_ = order }
   165  func (obj *object) setColor(color color)      { assert(color != white); obj.color_ = color }
   166  func (obj *object) setScopePos(pos token.Pos) { obj.scopePos_ = pos }
   167  
   168  func (obj *object) sameId(pkg *Package, name string) bool {
   169  	// spec:
   170  	// "Two identifiers are different if they are spelled differently,
   171  	// or if they appear in different packages and are not exported.
   172  	// Otherwise, they are the same."
   173  	if name != obj.name {
   174  		return false
   175  	}
   176  	// obj.Name == name
   177  	if obj.Exported() {
   178  		return true
   179  	}
   180  	// not exported, so packages must be the same (pkg == nil for
   181  	// fields in Universe scope; this can only happen for types
   182  	// introduced via Eval)
   183  	if pkg == nil || obj.pkg == nil {
   184  		return pkg == obj.pkg
   185  	}
   186  	// pkg != nil && obj.pkg != nil
   187  	return pkg.path == obj.pkg.path
   188  }
   189  
   190  // less reports whether object a is ordered before object b.
   191  //
   192  // Objects are ordered nil before non-nil, exported before
   193  // non-exported, then by name, and finally (for non-exported
   194  // functions) by package path.
   195  func (a *object) less(b *object) bool {
   196  	if a == b {
   197  		return false
   198  	}
   199  
   200  	// Nil before non-nil.
   201  	if a == nil {
   202  		return true
   203  	}
   204  	if b == nil {
   205  		return false
   206  	}
   207  
   208  	// Exported functions before non-exported.
   209  	ea := isExported(a.name)
   210  	eb := isExported(b.name)
   211  	if ea != eb {
   212  		return ea
   213  	}
   214  
   215  	// Order by name and then (for non-exported names) by package.
   216  	if a.name != b.name {
   217  		return a.name < b.name
   218  	}
   219  	if !ea {
   220  		return a.pkg.path < b.pkg.path
   221  	}
   222  
   223  	return false
   224  }
   225  
   226  // A PkgName represents an imported Go package.
   227  // PkgNames don't have a type.
   228  type PkgName struct {
   229  	object
   230  	imported *Package
   231  	used     bool // set if the package was used
   232  }
   233  
   234  // NewPkgName returns a new PkgName object representing an imported package.
   235  // The remaining arguments set the attributes found with all Objects.
   236  func NewPkgName(pos token.Pos, pkg *Package, name string, imported *Package) *PkgName {
   237  	return &PkgName{object{nil, pos, pkg, name, Typ[Invalid], 0, black, nopos}, imported, false}
   238  }
   239  
   240  // Imported returns the package that was imported.
   241  // It is distinct from Pkg(), which is the package containing the import statement.
   242  func (obj *PkgName) Imported() *Package { return obj.imported }
   243  
   244  // A Const represents a declared constant.
   245  type Const struct {
   246  	object
   247  	val constant.Value
   248  }
   249  
   250  // NewConst returns a new constant with value val.
   251  // The remaining arguments set the attributes found with all Objects.
   252  func NewConst(pos token.Pos, pkg *Package, name string, typ Type, val constant.Value) *Const {
   253  	return &Const{object{nil, pos, pkg, name, typ, 0, colorFor(typ), nopos}, val}
   254  }
   255  
   256  // Val returns the constant's value.
   257  func (obj *Const) Val() constant.Value { return obj.val }
   258  
   259  func (*Const) isDependency() {} // a constant may be a dependency of an initialization expression
   260  
   261  // A TypeName represents a name for a (defined or alias) type.
   262  type TypeName struct {
   263  	object
   264  }
   265  
   266  // NewTypeName returns a new type name denoting the given typ.
   267  // The remaining arguments set the attributes found with all Objects.
   268  //
   269  // The typ argument may be a defined (Named) type or an alias type.
   270  // It may also be nil such that the returned TypeName can be used as
   271  // argument for NewNamed, which will set the TypeName's type as a side-
   272  // effect.
   273  func NewTypeName(pos token.Pos, pkg *Package, name string, typ Type) *TypeName {
   274  	return &TypeName{object{nil, pos, pkg, name, typ, 0, colorFor(typ), nopos}}
   275  }
   276  
   277  // NewTypeNameLazy returns a new defined type like NewTypeName, but it
   278  // lazily calls resolve to finish constructing the Named object.
   279  func _NewTypeNameLazy(pos token.Pos, pkg *Package, name string, load func(named *Named) (tparams []*TypeParam, underlying Type, methods []*Func)) *TypeName {
   280  	obj := NewTypeName(pos, pkg, name, nil)
   281  	NewNamed(obj, nil, nil).loader = load
   282  	return obj
   283  }
   284  
   285  // IsAlias reports whether obj is an alias name for a type.
   286  func (obj *TypeName) IsAlias() bool {
   287  	switch t := obj.typ.(type) {
   288  	case nil:
   289  		return false
   290  	// case *Alias:
   291  	//	handled by default case
   292  	case *Basic:
   293  		// unsafe.Pointer is not an alias.
   294  		if obj.pkg == Unsafe {
   295  			return false
   296  		}
   297  		// Any user-defined type name for a basic type is an alias for a
   298  		// basic type (because basic types are pre-declared in the Universe
   299  		// scope, outside any package scope), and so is any type name with
   300  		// a different name than the name of the basic type it refers to.
   301  		// Additionally, we need to look for "byte" and "rune" because they
   302  		// are aliases but have the same names (for better error messages).
   303  		return obj.pkg != nil || t.name != obj.name || t == universeByte || t == universeRune
   304  	case *Named:
   305  		return obj != t.obj
   306  	case *TypeParam:
   307  		return obj != t.obj
   308  	default:
   309  		return true
   310  	}
   311  }
   312  
   313  // A Variable represents a declared variable (including function parameters and results, and struct fields).
   314  type Var struct {
   315  	object
   316  	embedded bool // if set, the variable is an embedded struct field, and name is the type name
   317  	isField  bool // var is struct field
   318  	used     bool // set if the variable was used
   319  	origin   *Var // if non-nil, the Var from which this one was instantiated
   320  }
   321  
   322  // NewVar returns a new variable.
   323  // The arguments set the attributes found with all Objects.
   324  func NewVar(pos token.Pos, pkg *Package, name string, typ Type) *Var {
   325  	return &Var{object: object{nil, pos, pkg, name, typ, 0, colorFor(typ), nopos}}
   326  }
   327  
   328  // NewParam returns a new variable representing a function parameter.
   329  func NewParam(pos token.Pos, pkg *Package, name string, typ Type) *Var {
   330  	return &Var{object: object{nil, pos, pkg, name, typ, 0, colorFor(typ), nopos}, used: true} // parameters are always 'used'
   331  }
   332  
   333  // NewField returns a new variable representing a struct field.
   334  // For embedded fields, the name is the unqualified type name
   335  // under which the field is accessible.
   336  func NewField(pos token.Pos, pkg *Package, name string, typ Type, embedded bool) *Var {
   337  	return &Var{object: object{nil, pos, pkg, name, typ, 0, colorFor(typ), nopos}, embedded: embedded, isField: true}
   338  }
   339  
   340  // Anonymous reports whether the variable is an embedded field.
   341  // Same as Embedded; only present for backward-compatibility.
   342  func (obj *Var) Anonymous() bool { return obj.embedded }
   343  
   344  // Embedded reports whether the variable is an embedded field.
   345  func (obj *Var) Embedded() bool { return obj.embedded }
   346  
   347  // IsField reports whether the variable is a struct field.
   348  func (obj *Var) IsField() bool { return obj.isField }
   349  
   350  // Origin returns the canonical Var for its receiver, i.e. the Var object
   351  // recorded in Info.Defs.
   352  //
   353  // For synthetic Vars created during instantiation (such as struct fields or
   354  // function parameters that depend on type arguments), this will be the
   355  // corresponding Var on the generic (uninstantiated) type. For all other Vars
   356  // Origin returns the receiver.
   357  func (obj *Var) Origin() *Var {
   358  	if obj.origin != nil {
   359  		return obj.origin
   360  	}
   361  	return obj
   362  }
   363  
   364  func (*Var) isDependency() {} // a variable may be a dependency of an initialization expression
   365  
   366  // A Func represents a declared function, concrete method, or abstract
   367  // (interface) method. Its Type() is always a *Signature.
   368  // An abstract method may belong to many interfaces due to embedding.
   369  type Func struct {
   370  	object
   371  	hasPtrRecv_ bool  // only valid for methods that don't have a type yet; use hasPtrRecv() to read
   372  	origin      *Func // if non-nil, the Func from which this one was instantiated
   373  }
   374  
   375  // NewFunc returns a new function with the given signature, representing
   376  // the function's type.
   377  func NewFunc(pos token.Pos, pkg *Package, name string, sig *Signature) *Func {
   378  	// don't store a (typed) nil signature
   379  	var typ Type
   380  	if sig != nil {
   381  		typ = sig
   382  	}
   383  	return &Func{object{nil, pos, pkg, name, typ, 0, colorFor(typ), nopos}, false, nil}
   384  }
   385  
   386  // FullName returns the package- or receiver-type-qualified name of
   387  // function or method obj.
   388  func (obj *Func) FullName() string {
   389  	var buf bytes.Buffer
   390  	writeFuncName(&buf, obj, nil)
   391  	return buf.String()
   392  }
   393  
   394  // Scope returns the scope of the function's body block.
   395  // The result is nil for imported or instantiated functions and methods
   396  // (but there is also no mechanism to get to an instantiated function).
   397  func (obj *Func) Scope() *Scope { return obj.typ.(*Signature).scope }
   398  
   399  // Origin returns the canonical Func for its receiver, i.e. the Func object
   400  // recorded in Info.Defs.
   401  //
   402  // For synthetic functions created during instantiation (such as methods on an
   403  // instantiated Named type or interface methods that depend on type arguments),
   404  // this will be the corresponding Func on the generic (uninstantiated) type.
   405  // For all other Funcs Origin returns the receiver.
   406  func (obj *Func) Origin() *Func {
   407  	if obj.origin != nil {
   408  		return obj.origin
   409  	}
   410  	return obj
   411  }
   412  
   413  // Pkg returns the package to which the function belongs.
   414  //
   415  // The result is nil for methods of types in the Universe scope,
   416  // like method Error of the error built-in interface type.
   417  func (obj *Func) Pkg() *Package { return obj.object.Pkg() }
   418  
   419  // hasPtrRecv reports whether the receiver is of the form *T for the given method obj.
   420  func (obj *Func) hasPtrRecv() bool {
   421  	// If a method's receiver type is set, use that as the source of truth for the receiver.
   422  	// Caution: Checker.funcDecl (decl.go) marks a function by setting its type to an empty
   423  	// signature. We may reach here before the signature is fully set up: we must explicitly
   424  	// check if the receiver is set (we cannot just look for non-nil obj.typ).
   425  	if sig, _ := obj.typ.(*Signature); sig != nil && sig.recv != nil {
   426  		_, isPtr := deref(sig.recv.typ)
   427  		return isPtr
   428  	}
   429  
   430  	// If a method's type is not set it may be a method/function that is:
   431  	// 1) client-supplied (via NewFunc with no signature), or
   432  	// 2) internally created but not yet type-checked.
   433  	// For case 1) we can't do anything; the client must know what they are doing.
   434  	// For case 2) we can use the information gathered by the resolver.
   435  	return obj.hasPtrRecv_
   436  }
   437  
   438  func (*Func) isDependency() {} // a function may be a dependency of an initialization expression
   439  
   440  // A Label represents a declared label.
   441  // Labels don't have a type.
   442  type Label struct {
   443  	object
   444  	used bool // set if the label was used
   445  }
   446  
   447  // NewLabel returns a new label.
   448  func NewLabel(pos token.Pos, pkg *Package, name string) *Label {
   449  	return &Label{object{pos: pos, pkg: pkg, name: name, typ: Typ[Invalid], color_: black}, false}
   450  }
   451  
   452  // A Builtin represents a built-in function.
   453  // Builtins don't have a valid type.
   454  type Builtin struct {
   455  	object
   456  	id builtinId
   457  }
   458  
   459  func newBuiltin(id builtinId) *Builtin {
   460  	return &Builtin{object{name: predeclaredFuncs[id].name, typ: Typ[Invalid], color_: black}, id}
   461  }
   462  
   463  // Nil represents the predeclared value nil.
   464  type Nil struct {
   465  	object
   466  }
   467  
   468  func writeObject(buf *bytes.Buffer, obj Object, qf Qualifier) {
   469  	var tname *TypeName
   470  	typ := obj.Type()
   471  
   472  	switch obj := obj.(type) {
   473  	case *PkgName:
   474  		fmt.Fprintf(buf, "package %s", obj.Name())
   475  		if path := obj.imported.path; path != "" && path != obj.name {
   476  			fmt.Fprintf(buf, " (%q)", path)
   477  		}
   478  		return
   479  
   480  	case *Const:
   481  		buf.WriteString("const")
   482  
   483  	case *TypeName:
   484  		tname = obj
   485  		buf.WriteString("type")
   486  		if isTypeParam(typ) {
   487  			buf.WriteString(" parameter")
   488  		}
   489  
   490  	case *Var:
   491  		if obj.isField {
   492  			buf.WriteString("field")
   493  		} else {
   494  			buf.WriteString("var")
   495  		}
   496  
   497  	case *Func:
   498  		buf.WriteString("func ")
   499  		writeFuncName(buf, obj, qf)
   500  		if typ != nil {
   501  			WriteSignature(buf, typ.(*Signature), qf)
   502  		}
   503  		return
   504  
   505  	case *Label:
   506  		buf.WriteString("label")
   507  		typ = nil
   508  
   509  	case *Builtin:
   510  		buf.WriteString("builtin")
   511  		typ = nil
   512  
   513  	case *Nil:
   514  		buf.WriteString("nil")
   515  		return
   516  
   517  	default:
   518  		panic(fmt.Sprintf("writeObject(%T)", obj))
   519  	}
   520  
   521  	buf.WriteByte(' ')
   522  
   523  	// For package-level objects, qualify the name.
   524  	if obj.Pkg() != nil && obj.Pkg().scope.Lookup(obj.Name()) == obj {
   525  		buf.WriteString(packagePrefix(obj.Pkg(), qf))
   526  	}
   527  	buf.WriteString(obj.Name())
   528  
   529  	if typ == nil {
   530  		return
   531  	}
   532  
   533  	if tname != nil {
   534  		switch t := typ.(type) {
   535  		case *Basic:
   536  			// Don't print anything more for basic types since there's
   537  			// no more information.
   538  			return
   539  		case *Named:
   540  			if t.TypeParams().Len() > 0 {
   541  				newTypeWriter(buf, qf).tParamList(t.TypeParams().list())
   542  			}
   543  		}
   544  		if tname.IsAlias() {
   545  			buf.WriteString(" =")
   546  		} else if t, _ := typ.(*TypeParam); t != nil {
   547  			typ = t.bound
   548  		} else {
   549  			// TODO(gri) should this be fromRHS for *Named?
   550  			typ = under(typ)
   551  		}
   552  	}
   553  
   554  	// Special handling for any: because WriteType will format 'any' as 'any',
   555  	// resulting in the object string `type any = any` rather than `type any =
   556  	// interface{}`. To avoid this, swap in a different empty interface.
   557  	if obj == universeAny {
   558  		assert(Identical(typ, &emptyInterface))
   559  		typ = &emptyInterface
   560  	}
   561  
   562  	buf.WriteByte(' ')
   563  	WriteType(buf, typ, qf)
   564  }
   565  
   566  func packagePrefix(pkg *Package, qf Qualifier) string {
   567  	if pkg == nil {
   568  		return ""
   569  	}
   570  	var s string
   571  	if qf != nil {
   572  		s = qf(pkg)
   573  	} else {
   574  		s = pkg.Path()
   575  	}
   576  	if s != "" {
   577  		s += "."
   578  	}
   579  	return s
   580  }
   581  
   582  // ObjectString returns the string form of obj.
   583  // The Qualifier controls the printing of
   584  // package-level objects, and may be nil.
   585  func ObjectString(obj Object, qf Qualifier) string {
   586  	var buf bytes.Buffer
   587  	writeObject(&buf, obj, qf)
   588  	return buf.String()
   589  }
   590  
   591  func (obj *PkgName) String() string  { return ObjectString(obj, nil) }
   592  func (obj *Const) String() string    { return ObjectString(obj, nil) }
   593  func (obj *TypeName) String() string { return ObjectString(obj, nil) }
   594  func (obj *Var) String() string      { return ObjectString(obj, nil) }
   595  func (obj *Func) String() string     { return ObjectString(obj, nil) }
   596  func (obj *Label) String() string    { return ObjectString(obj, nil) }
   597  func (obj *Builtin) String() string  { return ObjectString(obj, nil) }
   598  func (obj *Nil) String() string      { return ObjectString(obj, nil) }
   599  
   600  func writeFuncName(buf *bytes.Buffer, f *Func, qf Qualifier) {
   601  	if f.typ != nil {
   602  		sig := f.typ.(*Signature)
   603  		if recv := sig.Recv(); recv != nil {
   604  			buf.WriteByte('(')
   605  			if _, ok := recv.Type().(*Interface); ok {
   606  				// gcimporter creates abstract methods of
   607  				// named interfaces using the interface type
   608  				// (not the named type) as the receiver.
   609  				// Don't print it in full.
   610  				buf.WriteString("interface")
   611  			} else {
   612  				WriteType(buf, recv.Type(), qf)
   613  			}
   614  			buf.WriteByte(')')
   615  			buf.WriteByte('.')
   616  		} else if f.pkg != nil {
   617  			buf.WriteString(packagePrefix(f.pkg, qf))
   618  		}
   619  	}
   620  	buf.WriteString(f.name)
   621  }
   622
View as plain text