gti

README

gti

Package GTI provides general purpose type information for Go types, methods, functions and variables.

key questions:

• separate registries? YES -- keeps it type specific

• TypeRegistry

• FuncRegistry

not sure about these:

• VarRegistry
• ConstRegistry

Key functionality

• generate tooltips for fields in structs

• generate toolbar props for gogi methodview to generate greasi toolbars for arbitrary App types, and for Ki types.

• in grease, command method docs and config field docs

• in Ki (optional) generate a new token of given type by name (for Unmarshal)

• Ki needs NameAndType, need to be able to use Type token to specify type. Also for making a new child of given type.

notes

• GTI 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

Index

• Variables
• func FormatDoc(doc, name, label string) string
• func FuncName(f any) string
• func GetDoc(val, owner reflect.Value, field *reflect.StructField, label string) (string, bool)
• func StructGoString(str any) string
• func TypeName(typ reflect.Type) string
• func TypeNameObj(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 AllEmbeddersOf(typ *Type) []*Type
  • func TypeByName(nm string) *Type
  • func TypeByNameTry(nm string) (*Type, error)
  • func TypeByReflectType(typ reflect.Type) *Type
  • func TypeByReflectTypeTry(typ reflect.Type) (*Type, error)
  • func TypeByValue(val any) *Type
  • func TypeByValueTry(val any) (*Type, error)
  • func (tp *Type) CompileEmbeds()
  • func (tp Type) GoString() string
  • func (tp *Type) HasEmbed(typ *Type) bool
  • 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/gi.Button
	Funcs = map[string]*Func{}

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

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

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

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(val, owner reflect.Value, field *reflect.StructField, label string) (string, bool)

GetDoc gets the documentation for the given value with the given owner value, field, and label. The value, owner value, and field may be nil/invalid. The owner value, if valid, is the value that contains the value (the parent struct, map, slice, or array). The field, if non-nil, is the struct field that the value represents. 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 TypeNameObj

func TypeNameObj(v any) string

TypeNameObj returns the long, full package-path qualified type name from given object. 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 gti.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/gi.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/gi.Button),

func FuncByNameTry

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

FuncByNameTry returns a Func by name (package_url.Type, e.g., cogentcore.org/core/gi.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/gi.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 are available for all types
	Methods []Method

	// Embedded fields for struct types
	Embeds []Field

	// Fields for struct types
	Fields []Field

	// Instance is an optional instance of the type
	Instance any

	// ID is the unique type ID number
	ID uint64

	// All embedded fields (including nested ones) for struct types;
	// not set by gtigen -- HasEmbed automatically compiles it as needed.
	// Key is the ID of the type.
	AllEmbeds map[uint64]*Type
}

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 AllEmbeddersOf

func AllEmbeddersOf(typ *Type) []*Type

AllEmbeddersOf returns all registered types that embed the given type. List is sorted in alpha order by fully package-path-qualified Name.

func TypeByName

func TypeByName(nm string) *Type

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

func TypeByNameTry

func TypeByNameTry(nm string) (*Type, error)

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

func TypeByReflectType

func TypeByReflectType(typ reflect.Type) *Type

TypeByReflectType returns the Type of the given reflect type

func TypeByReflectTypeTry

func TypeByReflectTypeTry(typ reflect.Type) (*Type, error)

TypeByReflectTypeTry returns the Type of the given reflect type, or an error if it is not found

func TypeByValue

func TypeByValue(val any) *Type

TypeByValue returns the Type of the given value

func TypeByValueTry

func TypeByValueTry(val any) (*Type, error)

TypeByValueTry returns the Type of the given value, or an error if it is not found

func (*Type) CompileEmbeds

func (tp *Type) CompileEmbeds()

func (Type) GoString

func (tp Type) GoString() string

func (*Type) HasEmbed

func (tp *Type) HasEmbed(typ *Type) bool

HasEmbed returns true if this type has the given type at any level of embedding depth, including if this type is the given type. The first time called it will Compile a map of all embedded types so subsequent calls are very fast.

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 the 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