types

README

types

Package types provides type information for Go types, methods, and functions.

Key functionality

• Generate tooltips for fields in forms

• Generate tooltips for functions in func buttons

• In cli, generate command function docs and config field docs

• In tree (optional) generate a new token of given type by name

• Package tree needs type variables when making children from serialized data

Notes

• It is NOT Go ast because it doesn't store type info for fields, methods, etc. There is no assumption that all types are processed, only designated types. It only records names, comments and directives.

Documentation

Overview

Package types provides type information for Go types, methods, and functions.

Index

• Variables
• func FormatDoc(doc, name, label string) string
• func FuncName(f any) string
• func GetDoc(value, parent reflect.Value, field reflect.StructField, label string) (string, bool)
• func StructGoString(str any) string
• func TypeName(typ reflect.Type) string
• func TypeNameValue(v any) string
• type Directive
  • func (d Directive) GoString() string
  • func (d Directive) String() string
• type Field
  • func GetField(val reflect.Value, field string) *Field
  • func (f Field) GoString() string
• type Func
  • func AddFunc(fun *Func) *Func
  • func FuncByName(nm string) *Func
  • func FuncByNameTry(nm string) (*Func, error)
  • func FuncInfo(f any) *Func
  • func FuncInfoTry(f any) (*Func, error)
  • func (f Func) GoString() string
• type Method
  • func (m Method) GoString() string
• type Type
  • func AddType(typ *Type) *Type
  • func BuiltinTypes() []*Type
  • func For[T any]() *Type
  • func TypeByName(name string) *Type
  • func TypeByReflectType(typ reflect.Type) *Type
  • func TypeByValue(v any) *Type
  • func (tp Type) GoString() string
  • func (tp *Type) Label() string
  • func (tp *Type) ReflectType() reflect.Type
  • func (tp *Type) ShortName() string
  • func (tp *Type) String() string

Variables

var (
	// Funcs records all types (i.e., a type registry)
	// key is long type name: package_url.Func, e.g., cogentcore.org/core/core.Button
	Funcs = map[string]*Func{}

	// FuncIDCounter is an atomically incremented uint64 used
	// for assigning new [Func.ID] numbers
	FuncIDCounter uint64
)

var (
	// Types is a type registry, initialized to contain all builtin types. New types
	// can be added with [AddType]. The key is the long type name: package/path.Type,
	// e.g., cogentcore.org/core/core.Button.
	Types = map[string]*Type{}
)

Functions

func FormatDoc

func FormatDoc(doc, name, label string) string

FormatDoc formats the given Go documentation string for an identifier with the given CamelCase name and intended label. It replaces the name with the label and cleans up trailing punctuation.

func FuncName

func FuncName(f any) string

FuncName returns the fully package-qualified name of given function This is guaranteed to be unique and used for the Funcs registry.

func GetDoc

func GetDoc(value, parent reflect.Value, field reflect.StructField, label string) (string, bool)

GetDoc gets the documentation for the given value with the given parent struct, field, and label. The value, parent value, and field may be nil/invalid. GetDoc uses the given label to format the documentation with FormatDoc before returning it.

func StructGoString

func StructGoString(str any) string

StructGoString creates a GoString for the given struct, omitting any zero values.

func TypeName

func TypeName(typ reflect.Type) string

TypeName returns the long, full package-path qualified type name. This is guaranteed to be unique and used for the Types registry.

func TypeNameValue

func TypeNameValue(v any) string

TypeNameValue returns the long, full package-path qualified type name of the given Go value. Automatically finds the non-pointer base type. This is guaranteed to be unique and used for the Types registry.

Types

type Directive

type Directive struct {
	Tool      string
	Directive string
	Args      []string
}

Directive represents a comment directive in the format:

//tool:directive args...

func (Directive) GoString

func (d Directive) GoString() string

func (Directive) String

func (d Directive) String() string

String returns a string representation of the directive in the format:

//tool:directive args...

type Field

type Field struct {

	// Name is the name of the field (eg: Icon)
	Name string

	// Doc has all of the comment documentation
	// info as one string with directives removed.
	Doc string
}

Field represents a field or embed in a struct.

func GetField

func GetField(val reflect.Value, field string) *Field

GetField recursively attempts to extract the Field with the given name from the given struct reflect.Value, by searching through all of the embeds if it can not find it directly in the struct.

func (Field) GoString

func (f Field) GoString() string

type Func

type Func struct {
	// Name is the fully qualified name of the function
	// (eg: cogentcore.org/core/core.NewButton)
	Name string

	// Doc has all of the comment documentation
	// info as one string with directives removed.
	Doc string

	// Directives are the parsed comment directives
	Directives []Directive

	// Args are the names of the arguments to the function
	Args []string

	// Returns are the names of the return values of the function
	Returns []string

	// ID is the unique function ID number
	ID uint64
}

Func represents a global function.

func AddFunc

func AddFunc(fun *Func) *Func

AddFunc adds a constructed Func to the registry and returns it. This sets the ID.

func FuncByName

func FuncByName(nm string) *Func

FuncByName returns a Func by name (package_url.Type, e.g., cogentcore.org/core/core.Button),

func FuncByNameTry

func FuncByNameTry(nm string) (*Func, error)

FuncByNameTry returns a Func by name (package_url.Type, e.g., cogentcore.org/core/core.Button), or error if not found

func FuncInfo

func FuncInfo(f any) *Func

FuncInfo returns function info for given function.

func FuncInfoTry

func FuncInfoTry(f any) (*Func, error)

FuncInfoTry returns function info for given function.

func (Func) GoString

func (f Func) GoString() string

type Method

type Method struct {
	// Name is the name of the method (eg: NewChild)
	Name string

	// Doc has all of the comment documentation
	// info as one string with directives removed.
	Doc string

	// Directives are the parsed comment directives
	Directives []Directive

	// Args are the names of the arguments to the function
	Args []string

	// Returns are the names of the return values of the function
	Returns []string
}

Method represents a method.

func (Method) GoString

func (m Method) GoString() string

type Type

type Type struct {
	// Name is the fully package-path-qualified name of the type
	// (eg: cogentcore.org/core/core.Button).
	Name string

	// IDName is the short, package-unqualified, kebab-case name of
	// the type that is suitable for use in an ID (eg: button).
	IDName string

	// Doc has all of the comment documentation
	// info as one string with directives removed.
	Doc string

	// Directives has the parsed comment directives.
	Directives []Directive

	// Methods of the type, which are available for all types.
	Methods []Method

	// Embedded fields of struct types.
	Embeds []Field

	// Fields of struct types.
	Fields []Field

	// Instance is an instance of a non-nil pointer to the type,
	// which is set by [For] and other external functions such that
	// a [Type] can be used to make new instances of the type by
	// reflection. It is not set by typegen.
	Instance any

	// ID is the unique type ID number set by [AddType].
	ID uint64
}

Type represents a type.

func AddType

func AddType(typ *Type) *Type

AddType adds a constructed Type to the registry and returns it. This sets the ID.

func BuiltinTypes

func BuiltinTypes() []*Type

BuiltinTypes returns all of the builtin types in the type registry.

func For

func For[T any]() *Type

For returns the Type of the generic type parameter, setting its [Type.Instance] to a new(T) if it is nil.

func TypeByName

func TypeByName(name string) *Type

TypeByName returns a Type by name (package/path.Type, e.g., cogentcore.org/core/core.Button),

func TypeByReflectType

func TypeByReflectType(typ reflect.Type) *Type

TypeByReflectType returns the Type of the given reflect type

func TypeByValue

func TypeByValue(v any) *Type

TypeByValue returns the Type of the given value

func (Type) GoString

func (tp Type) GoString() string

func (*Type) Label

func (tp *Type) Label() string

func (*Type) ReflectType

func (tp *Type) ReflectType() reflect.Type

ReflectType returns the reflect.Type for this type, using [Type.Instance].

func (*Type) ShortName

func (tp *Type) ShortName() string

ShortName returns the short name of the type (package.Type)

func (*Type) String

func (tp *Type) String() string