type.go

Documentation: go/types

     1  // Copyright 2011 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 types
     6  
     7  import "sort"
     8  
     9  // A Type represents a type of Go.
    10  // All types implement the Type interface.
    11  type Type interface {
    12  	// Underlying returns the underlying type of a type.
    13  	Underlying() Type
    14  
    15  	// String returns a string representation of a type.
    16  	String() string
    17  }
    18  
    19  // BasicKind describes the kind of basic type.
    20  type BasicKind int
    21  
    22  const (
    23  	Invalid BasicKind = iota // type is invalid
    24  
    25  	// predeclared types
    26  	Bool
    27  	Int
    28  	Int8
    29  	Int16
    30  	Int32
    31  	Int64
    32  	Uint
    33  	Uint8
    34  	Uint16
    35  	Uint32
    36  	Uint64
    37  	Uintptr
    38  	Float32
    39  	Float64
    40  	Complex64
    41  	Complex128
    42  	String
    43  	UnsafePointer
    44  
    45  	// types for untyped values
    46  	UntypedBool
    47  	UntypedInt
    48  	UntypedRune
    49  	UntypedFloat
    50  	UntypedComplex
    51  	UntypedString
    52  	UntypedNil
    53  
    54  	// aliases
    55  	Byte = Uint8
    56  	Rune = Int32
    57  )
    58  
    59  // BasicInfo is a set of flags describing properties of a basic type.
    60  type BasicInfo int
    61  
    62  // Properties of basic types.
    63  const (
    64  	IsBoolean BasicInfo = 1 << iota
    65  	IsInteger
    66  	IsUnsigned
    67  	IsFloat
    68  	IsComplex
    69  	IsString
    70  	IsUntyped
    71  
    72  	IsOrdered   = IsInteger | IsFloat | IsString
    73  	IsNumeric   = IsInteger | IsFloat | IsComplex
    74  	IsConstType = IsBoolean | IsNumeric | IsString
    75  )
    76  
    77  // A Basic represents a basic type.
    78  type Basic struct {
    79  	kind BasicKind
    80  	info BasicInfo
    81  	name string
    82  }
    83  
    84  // Kind returns the kind of basic type b.
    85  func (b *Basic) Kind() BasicKind { return b.kind }
    86  
    87  // Info returns information about properties of basic type b.
    88  func (b *Basic) Info() BasicInfo { return b.info }
    89  
    90  // Name returns the name of basic type b.
    91  func (b *Basic) Name() string { return b.name }
    92  
    93  // An Array represents an array type.
    94  type Array struct {
    95  	len  int64
    96  	elem Type
    97  }
    98  
    99  // NewArray returns a new array type for the given element type and length.
   100  // A negative length indicates an unknown length.
   101  func NewArray(elem Type, len int64) *Array { return &Array{len, elem} }
   102  
   103  // Len returns the length of array a.
   104  // A negative result indicates an unknown length.
   105  func (a *Array) Len() int64 { return a.len }
   106  
   107  // Elem returns element type of array a.
   108  func (a *Array) Elem() Type { return a.elem }
   109  
   110  // A Slice represents a slice type.
   111  type Slice struct {
   112  	elem Type
   113  }
   114  
   115  // NewSlice returns a new slice type for the given element type.
   116  func NewSlice(elem Type) *Slice { return &Slice{elem} }
   117  
   118  // Elem returns the element type of slice s.
   119  func (s *Slice) Elem() Type { return s.elem }
   120  
   121  // A Struct represents a struct type.
   122  type Struct struct {
   123  	fields []*Var
   124  	tags   []string // field tags; nil if there are no tags
   125  }
   126  
   127  // NewStruct returns a new struct with the given fields and corresponding field tags.
   128  // If a field with index i has a tag, tags[i] must be that tag, but len(tags) may be
   129  // only as long as required to hold the tag with the largest index i. Consequently,
   130  // if no field has a tag, tags may be nil.
   131  func NewStruct(fields []*Var, tags []string) *Struct {
   132  	var fset objset
   133  	for _, f := range fields {
   134  		if f.name != "_" && fset.insert(f) != nil {
   135  			panic("multiple fields with the same name")
   136  		}
   137  	}
   138  	if len(tags) > len(fields) {
   139  		panic("more tags than fields")
   140  	}
   141  	return &Struct{fields: fields, tags: tags}
   142  }
   143  
   144  // NumFields returns the number of fields in the struct (including blank and embedded fields).
   145  func (s *Struct) NumFields() int { return len(s.fields) }
   146  
   147  // Field returns the i'th field for 0 <= i < NumFields().
   148  func (s *Struct) Field(i int) *Var { return s.fields[i] }
   149  
   150  // Tag returns the i'th field tag for 0 <= i < NumFields().
   151  func (s *Struct) Tag(i int) string {
   152  	if i < len(s.tags) {
   153  		return s.tags[i]
   154  	}
   155  	return ""
   156  }
   157  
   158  // A Pointer represents a pointer type.
   159  type Pointer struct {
   160  	base Type // element type
   161  }
   162  
   163  // NewPointer returns a new pointer type for the given element (base) type.
   164  func NewPointer(elem Type) *Pointer { return &Pointer{base: elem} }
   165  
   166  // Elem returns the element type for the given pointer p.
   167  func (p *Pointer) Elem() Type { return p.base }
   168  
   169  // A Tuple represents an ordered list of variables; a nil *Tuple is a valid (empty) tuple.
   170  // Tuples are used as components of signatures and to represent the type of multiple
   171  // assignments; they are not first class types of Go.
   172  type Tuple struct {
   173  	vars []*Var
   174  }
   175  
   176  // NewTuple returns a new tuple for the given variables.
   177  func NewTuple(x ...*Var) *Tuple {
   178  	if len(x) > 0 {
   179  		return &Tuple{x}
   180  	}
   181  	return nil
   182  }
   183  
   184  // Len returns the number variables of tuple t.
   185  func (t *Tuple) Len() int {
   186  	if t != nil {
   187  		return len(t.vars)
   188  	}
   189  	return 0
   190  }
   191  
   192  // At returns the i'th variable of tuple t.
   193  func (t *Tuple) At(i int) *Var { return t.vars[i] }
   194  
   195  // A Signature represents a (non-builtin) function or method type.
   196  // The receiver is ignored when comparing signatures for identity.
   197  type Signature struct {
   198  	// We need to keep the scope in Signature (rather than passing it around
   199  	// and store it in the Func Object) because when type-checking a function
   200  	// literal we call the general type checker which returns a general Type.
   201  	// We then unpack the *Signature and use the scope for the literal body.
   202  	scope    *Scope // function scope, present for package-local signatures
   203  	recv     *Var   // nil if not a method
   204  	params   *Tuple // (incoming) parameters from left to right; or nil
   205  	results  *Tuple // (outgoing) results from left to right; or nil
   206  	variadic bool   // true if the last parameter's type is of the form ...T (or string, for append built-in only)
   207  }
   208  
   209  // NewSignature returns a new function type for the given receiver, parameters,
   210  // and results, either of which may be nil. If variadic is set, the function
   211  // is variadic, it must have at least one parameter, and the last parameter
   212  // must be of unnamed slice type.
   213  func NewSignature(recv *Var, params, results *Tuple, variadic bool) *Signature {
   214  	if variadic {
   215  		n := params.Len()
   216  		if n == 0 {
   217  			panic("types.NewSignature: variadic function must have at least one parameter")
   218  		}
   219  		if _, ok := params.At(n - 1).typ.(*Slice); !ok {
   220  			panic("types.NewSignature: variadic parameter must be of unnamed slice type")
   221  		}
   222  	}
   223  	return &Signature{nil, recv, params, results, variadic}
   224  }
   225  
   226  // Recv returns the receiver of signature s (if a method), or nil if a
   227  // function. It is ignored when comparing signatures for identity.
   228  //
   229  // For an abstract method, Recv returns the enclosing interface either
   230  // as a *Named or an *Interface. Due to embedding, an interface may
   231  // contain methods whose receiver type is a different interface.
   232  func (s *Signature) Recv() *Var { return s.recv }
   233  
   234  // Params returns the parameters of signature s, or nil.
   235  func (s *Signature) Params() *Tuple { return s.params }
   236  
   237  // Results returns the results of signature s, or nil.
   238  func (s *Signature) Results() *Tuple { return s.results }
   239  
   240  // Variadic reports whether the signature s is variadic.
   241  func (s *Signature) Variadic() bool { return s.variadic }
   242  
   243  // An Interface represents an interface type.
   244  type Interface struct {
   245  	methods   []*Func // ordered list of explicitly declared methods
   246  	embeddeds []Type  // ordered list of explicitly embedded types
   247  
   248  	allMethods []*Func // ordered list of methods declared with or embedded in this interface (TODO(gri): replace with mset)
   249  }
   250  
   251  // emptyInterface represents the empty (completed) interface
   252  var emptyInterface = Interface{allMethods: markComplete}
   253  
   254  // markComplete is used to mark an empty interface as completely
   255  // set up by setting the allMethods field to a non-nil empty slice.
   256  var markComplete = make([]*Func, 0)
   257  
   258  // NewInterface returns a new (incomplete) interface for the given methods and embedded types.
   259  // Each embedded type must have an underlying type of interface type.
   260  // NewInterface takes ownership of the provided methods and may modify their types by setting
   261  // missing receivers. To compute the method set of the interface, Complete must be called.
   262  //
   263  // Deprecated: Use NewInterfaceType instead which allows any (even non-defined) interface types
   264  // to be embedded. This is necessary for interfaces that embed alias type names referring to
   265  // non-defined (literal) interface types.
   266  func NewInterface(methods []*Func, embeddeds []*Named) *Interface {
   267  	tnames := make([]Type, len(embeddeds))
   268  	for i, t := range embeddeds {
   269  		tnames[i] = t
   270  	}
   271  	return NewInterfaceType(methods, tnames)
   272  }
   273  
   274  // NewInterfaceType returns a new (incomplete) interface for the given methods and embedded types.
   275  // Each embedded type must have an underlying type of interface type (this property is not
   276  // verified for defined types, which may be in the process of being set up and which don't
   277  // have a valid underlying type yet).
   278  // NewInterfaceType takes ownership of the provided methods and may modify their types by setting
   279  // missing receivers. To compute the method set of the interface, Complete must be called.
   280  func NewInterfaceType(methods []*Func, embeddeds []Type) *Interface {
   281  	typ := new(Interface)
   282  
   283  	if len(methods) == 0 && len(embeddeds) == 0 {
   284  		return typ
   285  	}
   286  
   287  	var mset objset
   288  	for _, m := range methods {
   289  		if mset.insert(m) != nil {
   290  			panic("multiple methods with the same name")
   291  		}
   292  		// set receiver if we don't have one
   293  		if sig := m.typ.(*Signature); sig.recv == nil {
   294  			sig.recv = NewVar(m.pos, m.pkg, "", typ)
   295  		}
   296  	}
   297  	sort.Sort(byUniqueMethodName(methods))
   298  
   299  	if len(embeddeds) > 0 {
   300  		// All embedded types should be interfaces; however, defined types
   301  		// may not yet be fully resolved. Only verify that non-defined types
   302  		// are interfaces. This matches the behavior of the code before the
   303  		// fix for #25301 (issue #25596).
   304  		for _, t := range embeddeds {
   305  			if _, ok := t.(*Named); !ok && !IsInterface(t) {
   306  				panic("embedded type is not an interface")
   307  			}
   308  		}
   309  		sort.Stable(byUniqueTypeName(embeddeds))
   310  	}
   311  
   312  	typ.methods = methods
   313  	typ.embeddeds = embeddeds
   314  	return typ
   315  }
   316  
   317  // NumExplicitMethods returns the number of explicitly declared methods of interface t.
   318  func (t *Interface) NumExplicitMethods() int { return len(t.methods) }
   319  
   320  // ExplicitMethod returns the i'th explicitly declared method of interface t for 0 <= i < t.NumExplicitMethods().
   321  // The methods are ordered by their unique Id.
   322  func (t *Interface) ExplicitMethod(i int) *Func { return t.methods[i] }
   323  
   324  // NumEmbeddeds returns the number of embedded types in interface t.
   325  func (t *Interface) NumEmbeddeds() int { return len(t.embeddeds) }
   326  
   327  // Embedded returns the i'th embedded defined (*Named) type of interface t for 0 <= i < t.NumEmbeddeds().
   328  // The result is nil if the i'th embedded type is not a defined type.
   329  //
   330  // Deprecated: Use EmbeddedType which is not restricted to defined (*Named) types.
   331  func (t *Interface) Embedded(i int) *Named { tname, _ := t.embeddeds[i].(*Named); return tname }
   332  
   333  // EmbeddedType returns the i'th embedded type of interface t for 0 <= i < t.NumEmbeddeds().
   334  func (t *Interface) EmbeddedType(i int) Type { return t.embeddeds[i] }
   335  
   336  // NumMethods returns the total number of methods of interface t.
   337  func (t *Interface) NumMethods() int { return len(t.allMethods) }
   338  
   339  // Method returns the i'th method of interface t for 0 <= i < t.NumMethods().
   340  // The methods are ordered by their unique Id.
   341  func (t *Interface) Method(i int) *Func { return t.allMethods[i] }
   342  
   343  // Empty returns true if t is the empty interface.
   344  func (t *Interface) Empty() bool { return len(t.allMethods) == 0 }
   345  
   346  // Complete computes the interface's method set. It must be called by users of
   347  // NewInterfaceType and NewInterface after the interface's embedded types are
   348  // fully defined and before using the interface type in any way other than to
   349  // form other types. Complete returns the receiver.
   350  func (t *Interface) Complete() *Interface {
   351  	if t.allMethods != nil {
   352  		return t
   353  	}
   354  
   355  	var allMethods []*Func
   356  	allMethods = append(allMethods, t.methods...)
   357  	for _, et := range t.embeddeds {
   358  		it := et.Underlying().(*Interface)
   359  		it.Complete()
   360  		for _, tm := range it.allMethods {
   361  			// Make a copy of the method and adjust its receiver type.
   362  			newm := *tm
   363  			newmtyp := *tm.typ.(*Signature)
   364  			newm.typ = &newmtyp
   365  			newmtyp.recv = NewVar(newm.pos, newm.pkg, "", t)
   366  			allMethods = append(allMethods, &newm)
   367  		}
   368  	}
   369  	sort.Sort(byUniqueMethodName(allMethods))
   370  
   371  	// t.methods and/or t.embeddeds may have been empty
   372  	if allMethods == nil {
   373  		allMethods = markComplete
   374  	}
   375  	t.allMethods = allMethods
   376  
   377  	return t
   378  }
   379  
   380  // A Map represents a map type.
   381  type Map struct {
   382  	key, elem Type
   383  }
   384  
   385  // NewMap returns a new map for the given key and element types.
   386  func NewMap(key, elem Type) *Map {
   387  	return &Map{key, elem}
   388  }
   389  
   390  // Key returns the key type of map m.
   391  func (m *Map) Key() Type { return m.key }
   392  
   393  // Elem returns the element type of map m.
   394  func (m *Map) Elem() Type { return m.elem }
   395  
   396  // A Chan represents a channel type.
   397  type Chan struct {
   398  	dir  ChanDir
   399  	elem Type
   400  }
   401  
   402  // A ChanDir value indicates a channel direction.
   403  type ChanDir int
   404  
   405  // The direction of a channel is indicated by one of these constants.
   406  const (
   407  	SendRecv ChanDir = iota
   408  	SendOnly
   409  	RecvOnly
   410  )
   411  
   412  // NewChan returns a new channel type for the given direction and element type.
   413  func NewChan(dir ChanDir, elem Type) *Chan {
   414  	return &Chan{dir, elem}
   415  }
   416  
   417  // Dir returns the direction of channel c.
   418  func (c *Chan) Dir() ChanDir { return c.dir }
   419  
   420  // Elem returns the element type of channel c.
   421  func (c *Chan) Elem() Type { return c.elem }
   422  
   423  // A Named represents a named type.
   424  type Named struct {
   425  	obj        *TypeName // corresponding declared object
   426  	underlying Type      // possibly a *Named during setup; never a *Named once set up completely
   427  	methods    []*Func   // methods declared for this type (not the method set of this type)
   428  }
   429  
   430  // NewNamed returns a new named type for the given type name, underlying type, and associated methods.
   431  // If the given type name obj doesn't have a type yet, its type is set to the returned named type.
   432  // The underlying type must not be a *Named.
   433  func NewNamed(obj *TypeName, underlying Type, methods []*Func) *Named {
   434  	if _, ok := underlying.(*Named); ok {
   435  		panic("types.NewNamed: underlying type must not be *Named")
   436  	}
   437  	typ := &Named{obj: obj, underlying: underlying, methods: methods}
   438  	if obj.typ == nil {
   439  		obj.typ = typ
   440  	}
   441  	return typ
   442  }
   443  
   444  // Obj returns the type name for the named type t.
   445  func (t *Named) Obj() *TypeName { return t.obj }
   446  
   447  // NumMethods returns the number of explicit methods whose receiver is named type t.
   448  func (t *Named) NumMethods() int { return len(t.methods) }
   449  
   450  // Method returns the i'th method of named type t for 0 <= i < t.NumMethods().
   451  func (t *Named) Method(i int) *Func { return t.methods[i] }
   452  
   453  // SetUnderlying sets the underlying type and marks t as complete.
   454  func (t *Named) SetUnderlying(underlying Type) {
   455  	if underlying == nil {
   456  		panic("types.Named.SetUnderlying: underlying type must not be nil")
   457  	}
   458  	if _, ok := underlying.(*Named); ok {
   459  		panic("types.Named.SetUnderlying: underlying type must not be *Named")
   460  	}
   461  	t.underlying = underlying
   462  }
   463  
   464  // AddMethod adds method m unless it is already in the method list.
   465  func (t *Named) AddMethod(m *Func) {
   466  	if i, _ := lookupMethod(t.methods, m.pkg, m.name); i < 0 {
   467  		t.methods = append(t.methods, m)
   468  	}
   469  }
   470  
   471  // Implementations for Type methods.
   472  
   473  func (b *Basic) Underlying() Type     { return b }
   474  func (a *Array) Underlying() Type     { return a }
   475  func (s *Slice) Underlying() Type     { return s }
   476  func (s *Struct) Underlying() Type    { return s }
   477  func (p *Pointer) Underlying() Type   { return p }
   478  func (t *Tuple) Underlying() Type     { return t }
   479  func (s *Signature) Underlying() Type { return s }
   480  func (t *Interface) Underlying() Type { return t }
   481  func (m *Map) Underlying() Type       { return m }
   482  func (c *Chan) Underlying() Type      { return c }
   483  func (t *Named) Underlying() Type     { return t.underlying }
   484  
   485  func (b *Basic) String() string     { return TypeString(b, nil) }
   486  func (a *Array) String() string     { return TypeString(a, nil) }
   487  func (s *Slice) String() string     { return TypeString(s, nil) }
   488  func (s *Struct) String() string    { return TypeString(s, nil) }
   489  func (p *Pointer) String() string   { return TypeString(p, nil) }
   490  func (t *Tuple) String() string     { return TypeString(t, nil) }
   491  func (s *Signature) String() string { return TypeString(s, nil) }
   492  func (t *Interface) String() string { return TypeString(t, nil) }
   493  func (m *Map) String() string       { return TypeString(m, nil) }
   494  func (c *Chan) String() string      { return TypeString(c, nil) }
   495  func (t *Named) String() string     { return TypeString(t, nil) }
   496
View as plain text