object.go

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