typeparams

Documentation

Overview

Package typeparams provides functions to work indirectly with type parameter data stored in go/ast and go/types objects, while these API are guarded by a build constraint.

This package exists to make it easier for tools to work with generic code, while also compiling against older Go versions.

Index

• Constants
• Variables
• func ForFuncType(*ast.FuncType) *ast.FieldList
• func ForTypeSpec(*ast.TypeSpec) *ast.FieldList
• func GetInstances(info *types.Info) map[*ast.Ident]Instance
• func InitInstanceInfo(*types.Info)
• func Instantiate(ctxt *Context, typ types.Type, targs []types.Type, validate bool) (types.Type, error)
• func IsComparable(*types.Interface) bool
• func IsImplicit(*types.Interface) bool
• func IsMethodSet(*types.Interface) bool
• func IsTypeParam(t types.Type) bool
• func MarkImplicit(*types.Interface)
• func NamedTypeOrigin(named *types.Named) types.Type
• func NewSignatureType(recv *types.Var, recvTypeParams, typeParams []*TypeParam, ...) *types.Signature
• func PackIndexExpr(x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos) ast.Expr
• func SetForNamed(_ *types.Named, tparams []*TypeParam)
• func SetTypeParamConstraint(tparam *TypeParam, constraint types.Type)
• type Context
• type IndexExprData
  • func GetIndexExprData(n ast.Node) *IndexExprData
• type IndexListExpr
• type Instance
• type Term
  • func InterfaceTermSet(iface *types.Interface) ([]*Term, error)
  • func NewTerm(tilde bool, typ types.Type) *Term
  • func StructuralTerms(tparam *TypeParam) ([]*Term, error)
  • func UnionTermSet(union *Union) ([]*Term, error)
  • func (m *Term) String() string
  • func (m *Term) Tilde() bool
  • func (m *Term) Type() types.Type
• type TypeList
  • func NamedTypeArgs(*types.Named) *TypeList
  • func (*TypeList) At(int) types.Type
  • func (*TypeList) Len() int
• type TypeParam
  • func NewTypeParam(name *types.TypeName, constraint types.Type) *TypeParam
  • func (*TypeParam) Constraint() types.Type
  • func (*TypeParam) Index() int
  • func (*TypeParam) Obj() *types.TypeName
• type TypeParamList
  • func ForNamed(*types.Named) *TypeParamList
  • func ForSignature(*types.Signature) *TypeParamList
  • func RecvTypeParams(sig *types.Signature) *TypeParamList
  • func (*TypeParamList) At(int) *TypeParam
  • func (*TypeParamList) Len() int
• type Union
  • func NewUnion(terms []*Term) *Union
  • func (*Union) Len() int
  • func (*Union) Term(i int) *Term

Constants

const Enabled = false

Enabled reports whether type parameters are enabled in the current build environment.

Variables

var ErrEmptyTypeSet = errors.New("empty type set")

Functions

func ForFuncType

func ForFuncType(*ast.FuncType) *ast.FieldList

ForFuncType returns an empty field list, as type parameters are not supported at this Go version.

func ForTypeSpec

func ForTypeSpec(*ast.TypeSpec) *ast.FieldList

ForTypeSpec returns an empty field list, as type parameters on not supported at this Go version.

func GetInstances

func GetInstances(info *types.Info) map[*ast.Ident]Instance

GetInstances returns a nil map, as type parameters are not supported at this Go version.

func InitInstanceInfo

func InitInstanceInfo(*types.Info)

InitInstanceInfo is a noop at this Go version.

func Instantiate

func Instantiate(ctxt *Context, typ types.Type, targs []types.Type, validate bool) (types.Type, error)

Instantiate is unsupported on this Go version, and panics.

func IsComparable

func IsComparable(*types.Interface) bool

IsComparable returns false, as no interfaces are type-restricted at this Go version.

func IsImplicit

func IsImplicit(*types.Interface) bool

IsImplicit returns false, as no interfaces are implicit at this Go version.

func IsMethodSet

func IsMethodSet(*types.Interface) bool

IsMethodSet returns true, as no interfaces are type-restricted at this Go version.

func IsTypeParam

func IsTypeParam(t types.Type) bool

IsTypeParam reports whether t is a type parameter.

func MarkImplicit

func MarkImplicit(*types.Interface)

MarkImplicit does nothing, because this Go version does not have implicit interfaces.

func NamedTypeOrigin

func NamedTypeOrigin(named *types.Named) types.Type

NamedTypeOrigin is the identity method at this Go version.

func NewSignatureType

func NewSignatureType(recv *types.Var, recvTypeParams, typeParams []*TypeParam, params, results *types.Tuple, variadic bool) *types.Signature

NewSignatureType calls types.NewSignature, panicking if recvTypeParams or typeParams is non-empty.

func PackIndexExpr

func PackIndexExpr(x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos) ast.Expr

PackIndexExpr returns an *ast.IndexExpr with the given index. Calling PackIndexExpr with len(indices) != 1 will panic.

func SetForNamed

func SetForNamed(_ *types.Named, tparams []*TypeParam)

SetForNamed panics if tparams is non-empty.

func SetTypeParamConstraint

func SetTypeParamConstraint(tparam *TypeParam, constraint types.Type)

SetTypeParamConstraint is unsupported at this Go version, and panics.

Types

type Context

type Context struct{}

Context is a placeholder type, as type parameters are not supported at this Go version.

type IndexExprData

type IndexExprData struct {
	X       ast.Expr   // expression
	Lbrack  token.Pos  // position of "["
	Indices []ast.Expr // index expressions
	Rbrack  token.Pos  // position of "]"
}

A IndexExprData holds data from both ast.IndexExpr and the new ast.MultiIndexExpr, which was introduced in Go 1.18.

func GetIndexExprData

func GetIndexExprData(n ast.Node) *IndexExprData

GetIndexExprData extracts data from *ast.IndexExpr nodes. For other nodes, GetIndexExprData returns nil.

type IndexListExpr

type IndexListExpr struct {
	ast.Expr
	X       ast.Expr   // expression
	Lbrack  token.Pos  // position of "["
	Indices []ast.Expr // index expressions
	Rbrack  token.Pos  // position of "]"
}

IndexListExpr is a placeholder type, as type parameters are not supported at this Go version. Its methods panic on use.

type Instance

type Instance struct {
	TypeArgs *TypeList
	Type     types.Type
}

Instance is a placeholder type, as type parameters are not supported at this Go version.

type Term

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

Term holds information about a structural type restriction.

func InterfaceTermSet

func InterfaceTermSet(iface *types.Interface) ([]*Term, error)

InterfaceTermSet computes the normalized terms for a constraint interface, returning an error if the term set cannot be computed or is empty. In the latter case, the error will be ErrEmptyTypeSet.

See the documentation of StructuralTerms for more information on normalization.

func NewTerm

func NewTerm(tilde bool, typ types.Type) *Term

NewTerm is unsupported at this Go version, and panics.

func StructuralTerms

func StructuralTerms(tparam *TypeParam) ([]*Term, error)

StructuralTerms returns a slice of terms representing the normalized structural type restrictions of a type parameter, if any.

Structural type restrictions of a type parameter are created via non-interface types embedded in its constraint interface (directly, or via a chain of interface embeddings). For example, in the declaration

type T[P interface{~int; m()}] int

the structural restriction of the type parameter P is ~int.

With interface embedding and unions, the specification of structural type restrictions may be arbitrarily complex. For example, consider the following:

type A interface{ ~string|~[]byte }

type B interface{ int|string }

type C interface { ~string|~int }

type T[P interface{ A|B; C }] int

In this example, the structural type restriction of P is ~string|int: A|B expands to ~string|~[]byte|int|string, which reduces to ~string|~[]byte|int, which when intersected with C (~string|~int) yields ~string|int.

StructuralTerms computes these expansions and reductions, producing a "normalized" form of the embeddings. A structural restriction is normalized if it is a single union containing no interface terms, and is minimal in the sense that removing any term changes the set of types satisfying the constraint. It is left as a proof for the reader that, modulo sorting, there is exactly one such normalized form.

Because the minimal representation always takes this form, StructuralTerms returns a slice of tilde terms corresponding to the terms of the union in the normalized structural restriction. An error is returned if the constraint interface is invalid, exceeds complexity bounds, or has an empty type set. In the latter case, StructuralTerms returns ErrEmptyTypeSet.

StructuralTerms makes no guarantees about the order of terms, except that it is deterministic.

func UnionTermSet

func UnionTermSet(union *Union) ([]*Term, error)

UnionTermSet computes the normalized terms for a union, returning an error if the term set cannot be computed or is empty. In the latter case, the error will be ErrEmptyTypeSet.

See the documentation of StructuralTerms for more information on normalization.

func (*Term) String

func (m *Term) String() string

func (*Term) Tilde

func (m *Term) Tilde() bool

func (*Term) Type

func (m *Term) Type() types.Type

type TypeList

type TypeList struct{}

TypeList is a placeholder for an empty type list.

func NamedTypeArgs

func NamedTypeArgs(*types.Named) *TypeList

NamedTypeArgs returns nil.

func (*TypeList) At

func (*TypeList) At(int) types.Type

func (*TypeList) Len

func (*TypeList) Len() int

type TypeParam

type TypeParam struct{ types.Type }

TypeParam is a placeholder type, as type parameters are not supported at this Go version. Its methods panic on use.

func NewTypeParam

func NewTypeParam(name *types.TypeName, constraint types.Type) *TypeParam

NewTypeParam is unsupported at this Go version, and panics.

func (*TypeParam) Constraint

func (*TypeParam) Constraint() types.Type

func (*TypeParam) Index

func (*TypeParam) Index() int

func (*TypeParam) Obj

func (*TypeParam) Obj() *types.TypeName

type TypeParamList

type TypeParamList struct{}

TypeParamList is a placeholder for an empty type parameter list.

func ForNamed

func ForNamed(*types.Named) *TypeParamList

ForNamed returns an empty type parameter list, as type parameters are not supported at this Go version.

func ForSignature

func ForSignature(*types.Signature) *TypeParamList

ForSignature returns an empty slice.

func RecvTypeParams

func RecvTypeParams(sig *types.Signature) *TypeParamList

RecvTypeParams returns a nil slice.

func (*TypeParamList) At

func (*TypeParamList) At(int) *TypeParam

func (*TypeParamList) Len

func (*TypeParamList) Len() int

type Union

type Union struct{ types.Type }

Union is a placeholder type, as type parameters are not supported at this Go version. Its methods panic on use.

func NewUnion

func NewUnion(terms []*Term) *Union

NewUnion is unsupported at this Go version, and panics.

func (*Union) Len

func (*Union) Len() int

func (*Union) Term

func (*Union) Term(i int) *Term