typeparams

package
Version: v0.1.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 15, 2022 License: BSD-3-Clause Imports: 8 Imported by: 0

Documentation

Overview

Package typeparams contains common utilities for writing tools that interact with generic Go code, as introduced with Go 1.18.

Many of the types and functions in this package are proxies for the new APIs introduced in the standard library with Go 1.18. For example, the typeparams.Union type is an alias for go/types.Union, and the ForTypeSpec function returns the value of the go/ast.TypeSpec.TypeParams field. At Go versions older than 1.18 these helpers are implemented as stubs, allowing users of this package to write code that handles generic constructs inline, even if the Go version being used to compile does not support generics.

Additionally, this package contains common utilities for working with the new generic constructs, to supplement the standard library APIs. Notably, the StructuralTerms API computes a minimal representation of the structural restrictions on a type parameter. In the future, this API may be available from go/types.

See the example/README.md for a more detailed guide on how to update tools to support generics.

Index

Constants

View Source
const Enabled = true

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

Variables

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

Functions

func ForFuncType added in v0.1.7

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

ForFuncType returns n.TypeParams.

func ForTypeSpec added in v0.1.7

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

ForTypeSpec returns n.TypeParams.

func GenericAssignableTo added in v0.1.10

func GenericAssignableTo(ctxt *Context, V, T types.Type) bool

GenericAssignableTo is a generalization of types.AssignableTo that implements the following rule for uninstantiated generic types:

If V and T are generic named types, then V is considered assignable to T if, for every possible instantation of V[A_1, ..., A_N], the instantiation T[A_1, ..., A_N] is valid and V[A_1, ..., A_N] implements T[A_1, ..., A_N].

If T has structural constraints, they must be satisfied by V.

For example, consider the following type declarations:

type Interface[T any] interface {
	Accept(T)
}

type Container[T any] struct {
	Element T
}

func (c Container[T]) Accept(t T) { c.Element = t }

In this case, GenericAssignableTo reports that instantiations of Container are assignable to the corresponding instantiation of Interface.

func GetInstances added in v0.1.8

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

GetInstances returns info.Instances.

func InitInstanceInfo added in v0.1.7

func InitInstanceInfo(info *types.Info)

InitInstanceInfo initializes info to record information about type and function instances.

func Instantiate added in v0.1.6

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

Instantiate calls types.Instantiate.

func IsComparable

func IsComparable(iface *types.Interface) bool

IsComparable calls iface.IsComparable().

func IsImplicit added in v0.1.8

func IsImplicit(iface *types.Interface) bool

IsImplicit calls iface.IsImplicit().

func IsMethodSet added in v0.1.8

func IsMethodSet(iface *types.Interface) bool

IsMethodSet calls iface.IsMethodSet().

func IsTypeParam added in v0.1.8

func IsTypeParam(t types.Type) bool

IsTypeParam reports whether t is a type parameter.

func MarkImplicit added in v0.1.8

func MarkImplicit(iface *types.Interface)

MarkImplicit calls iface.MarkImplicit().

func NamedTypeOrigin added in v0.1.7

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

NamedTypeOrigin returns named.Orig().

func NewSignatureType added in v0.1.8

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

NewSignatureType calls types.NewSignatureType.

func OriginMethod added in v0.1.10

func OriginMethod(fn *types.Func) *types.Func

OriginMethod returns the origin method associated with the method fn. For methods on a non-generic receiver base type, this is just fn. However, for methods with a generic receiver, OriginMethod returns the corresponding method in the method set of the origin type.

As a special case, if fn is not a method (has no receiver), OriginMethod returns fn.

func PackIndexExpr added in v0.1.8

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

PackIndexExpr returns an *ast.IndexExpr or *ast.IndexListExpr, depending on the cardinality of indices. Calling PackIndexExpr with len(indices) == 0 will panic.

func SetForNamed added in v0.1.6

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

SetForNamed sets the type params tparams on n. Each tparam must be of dynamic type *types.TypeParam.

func SetTypeParamConstraint added in v0.1.6

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

SetTypeParamConstraint calls tparam.SetConstraint(constraint).

func UnpackIndexExpr added in v0.1.9

func UnpackIndexExpr(n ast.Node) (x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos)

UnpackIndexExpr extracts data from AST nodes that represent index expressions.

For an ast.IndexExpr, the resulting indices slice will contain exactly one index expression. For an ast.IndexListExpr (go1.18+), it may have a variable number of index expressions.

For nodes that don't represent index expressions, the first return value of UnpackIndexExpr will be nil.

Types

type Context added in v0.1.8

type Context = types.Context

Context is an alias for types.Context.

func NewContext added in v0.1.10

func NewContext() *Context

NewContext calls types.NewContext.

type IndexListExpr added in v0.1.8

type IndexListExpr = ast.IndexListExpr

IndexListExpr is an alias for ast.IndexListExpr.

type Instance added in v0.1.8

type Instance = types.Instance

Instance is an alias for types.Instance.

type Term added in v0.1.6

type Term = types.Term

Term is an alias for types.Term.

func InterfaceTermSet added in v0.1.8

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 added in v0.1.6

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

NewTerm calls types.NewTerm.

func StructuralTerms added in v0.1.8

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 added in v0.1.8

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.

type TypeList added in v0.1.6

type TypeList = types.TypeList

TypeList is an alias for types.TypeList

func NamedTypeArgs added in v0.1.6

func NamedTypeArgs(named *types.Named) *TypeList

NamedTypeArgs returns named.TypeArgs().

type TypeParam added in v0.1.6

type TypeParam = types.TypeParam

TypeParam is an alias for types.TypeParam

func NewTypeParam added in v0.1.6

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

NewTypeParam calls types.NewTypeParam.

type TypeParamList added in v0.1.6

type TypeParamList = types.TypeParamList

TypeParamList is an alias for types.TypeParamList

func ForNamed

func ForNamed(named *types.Named) *TypeParamList

ForNamed extracts the (possibly empty) type parameter object list from named.

func ForSignature

func ForSignature(sig *types.Signature) *TypeParamList

ForSignature returns sig.TypeParams()

func RecvTypeParams added in v0.1.6

func RecvTypeParams(sig *types.Signature) *TypeParamList

RecvTypeParams returns sig.RecvTypeParams().

type Union added in v0.1.6

type Union = types.Union

Union is an alias for types.Union

func NewUnion added in v0.1.6

func NewUnion(terms []*Term) *Union

NewUnion calls types.NewUnion.

Directories

Path Synopsis
example
The genericfeatures package provides utilities for detecting usage of generic programming in Go packages.
The genericfeatures package provides utilities for detecting usage of generic programming in Go packages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL