Design Principles

[rcoreilly]

This is an attempt to systematize and document the principles and decisions driving V2 rewrite:

Prefer generate to reflect

Generated code is faster and cleaner and can be targeted to just what is needed. reflect should be reserved for things like giv.StructView and other such views which need to be truly generic and operate on any kind of type from any package, etc.

• Limitation: generate is easiest for code we own.

This goki package represents the logical conclusion of this principle: a tool that combines multiple generate steps into one big generator pass -- once we have this infrastructure in place, it is easy to add new generator types.

Use interfaces instead of reflect

Interfaces go hand-in-hand with generated code: the boilerplate code that satisfies the interfaces is auto-generated as needed.

The prototype here is enums

Repositories and packages should be small, focused, minimal

Find the coherent chunks of functionality and encapsulate them in separate repositories, instead of creating sprawling mega-repos like ki was before. Now that we know all the functionality we need, we can think more carefully about how to package it.

Try to make these repos as independent as possible -- don't have them depend on other goki infrastructure unless absolutely necessary, so that they can be used by anyone in an unencumbered way.

This is what we look for, in considering whether to import a given package, so it is what we should provide.

Examples:

• colors -- pulled out of gi
• laser -- pulled reflection stuff out of kit
• greasi separated from grease to keep grease free of gogi dependency.

This is why we don't want to apply goki "desc" comment generator and type registry to all of our packages -- only required when using gi, so it should be in gi!

Use function libraries instead of putting lots of methods on a type

Go uses the strings package instead of adding a lot of builtin methods on the string type. The advantages are:

• More flexibility to add and change impls -- can even have a replacement impl with the same signatures.
• Multiple different such packages can be used for different subsets of functionality (e.g., regex, unicode etc are all separate).
• Type itself remains small and only handles most basic functionality -- presumably this works better for checking Interface implementation etc.

Consistent with this approach, colors implements functions operating on the standard color.RGBA data type, instead of the many methods we defined on gist.Color in V1.

Type registry is required for generic New

See ki issue #11 for logic.

Once we buy into the type registry, it provides a place to hang other things that we otherwise might need to use reflect for.

• Key question: do we need a type registry for non-Ki types?

[rcoreilly]

desc: field tags vs. comments

My claim: best to have desc description as standard comments above each field, and reserve the field tags for brief directives (view etc).

1. Having both as we do now is the worst of both worlds -- too much redundant info that overwhelms and makes it hard to see the actual functional tags.
2. Comments above makes it automatic for VSCode users and others to see the comments.
3. gopkg docs truncate the field tags when over some minimum length.

The main downside for using comments as desc is that it requires a generate function to extract from parsed code -- no way to access from reflect.

But we've already bought into the generator. And the type registry that is needed to hold the field descs for use in gi. So this is compatible with our overall approach.

There is no performance issue with having code bloated with lots of constant strings -- they go in a separate place and are just sitting there, likely offloaded from active RAM when needed. No harm at all.

[rcoreilly]

Because we want to keep packages minimal and unencumbered, we do not want to run the desc comment generator on all our packages, e.g., colors. Instead, there is a simple rule:

• If a package is a direct import (which go.mod nicely shows you, vs. indirects), and you want to have desc comment tooltips (not everything needs this), then you need to descify it. Gi will handle all of its direct imports, which covers all our goki.dev stuff, so any user app will only need to look at whatever else they import and decide if it is relevant.

• Ki types require the goki generate tool and will always have desc comments.

[kkoreilly]

Code is always the best solution

A common approach to programming, especially for the web, is to reduce the amount of actual programming that takes place and instead use simplified markup, configuration, and selection formats like CSS, HTML, YAML, and Regex. The promise of this is that you will be able to accomplish everything you need to do in a very easy, simple way. However, there are several problems with this strategy. Firstly, it requires learning many different languages, typically with very magic syntaxes packed with random symbols that do various things, with no clear connection between the symbols and the actions. Second of all, the simplified formats never end up covering all use cases, resulting in hacky workarounds to achieve the desired functionality, or, in some cases, entirely new languages that promise to cover all of the use cases, for real this time.

The eventual result of this trend is that people end up stuffing entire programming languages into these supposedly simple formats to cover their requirements (for example, SCSS, JSX, and templates). The resulting languages are neither simple, clear, nor extensible, creating massive amounts of unreadable and inefficient code. This means that everyone has to learn these languages and their magic syntaxes, struggle to read their complicated code, reach constant limits in functionality, and suffer runtime errors and bad performance due to the typically duck-typed, interpreted nature of these languages. Unless there are very limited uses for something, avoiding real code will always cause many problems and no benefits.

The solution to this is simple—whenever possible, everything should be written in real code, preferably in one language. Therefore, GoKi takes this approach: everything, from trees to widgets to styling to enums, is written in real, pure Go code. The only non-Go functional files in a GoKi package or app should be TOML files, which are only used for very simple configuration options to commands, and not for any actual code.

[rcoreilly]

Nested Embedding + Interfaces (i.e., virtual functions) -- i.e., traditional OOP

There is a class of domains where the classic OOP paradigm of type inheritance and virtual functions is the most efficient paradigm. This is the case in the GoGi GUI, and, arguably, in any kind of GUI framework.

Specifically, the OOP paradigm makes sense when:

• A tree data structure composed of heterogeneous types is needed (e.g., a scenegraph of GUI widgets, including the DOM in a web browser).

• These types are open ended -- it is not a closed set of types (e.g., an end-user application can add custom widget types), so a type switch approach is not possible (and in any case becomes cumbersome when the number of types is large).

• There is a significant amount of shared functionality required for each element, such that it does not make sense for each type to re-implement this Base functionality. Instead, embedding a Base type is the most efficient.

• The Base type implements an associated interface, and, by calling through a This() pointer that guarantees access to the actual final underlying type, subtypes can override base functionality as needed, but otherwise inherit it by default.

The Go ast framework for example is a closed set of Node types with minimal shared functionality (only two methods: Pos() and End()), so it does not require the OOP paradigm (but does suffer from requiring a lot of type switches).

Accessing embedded types

• When traversing the tree, you often want to access functionality at a given level of embedding. While one could wrap that functionality in a huge interface (including all field setters and getters), it is much better to keep the interface restricted to only those methods that need to be overridden, and handle everything else in terms of a concrete base type implementation.

• This means that you need an efficient way to access an unknown tree element at a given level of embedding.

• The overall best solution for end-user code efficiency is to have an interface and a global function for each type as follows -- this can be either a special Embeder interface or part of a larger interface. Note that a fully generic As method doesn't work because it only gets the top-level embedded type (it has multiple return types for each different instantiation). This is a sufficiently small amount of code, typically where there is a larger interface, that it doesn't make sense to auto-generate it.

// MyType does xyz..
type MyType struct {
}

type MyTypeEmbeder interface {
    AsMyTypeType() *MyType
}

func AsMyType(v any) *EmbedType { // note: can return the interface if part of a larger useful interface
   i, ok := v.(MyTypeEmbeder)
   if !ok {
        return nil
    }
    return i, i.AsMyType()
}

... // user code example, e.g., when iterating over nodes n

    mt := AsMyType(n)
    if mt == nil {
        continue
    }

• An alternative is a type registry and code generator that auto-creates an Embed method that takes a Type token, and returns either the embedded type or a nil, as in: embed generator and new type registry ki#19

    em, ok := n.Embed(TypeEmbedType).(*EmbedType)
    if !ok {
        continue
    }

[kkoreilly]

The Aser interface only works when you have one level of embedding, but if you have multiple embedded types with an As function, it no longer works.

package main

import (
	"fmt"
	"strconv"
)

// As infrastructure

type Aser[T any] interface {
	As() T
}

func As[T any](v any) T {
	a, ok := v.(Aser[T])
	if !ok {
		var res T
		return res
	}
	return a.As()
}

// Example embed type and node type

type EmbedType struct {
	BaseType
	Data string
}

func (e *EmbedType) As() *EmbedType { return e }

func (e *EmbedType) Hello() string {
	return "hello from embed type " + e.Data
}

type BaseType struct {
	Field int
}

func (e *BaseType) As() *BaseType {
	return e
}

func (e *BaseType) Hello() string {
	return "hello from base type " + strconv.Itoa(e.Field)
}

type ThirdType struct {
	BaseType
}

type Node struct {
	EmbedType
}

// Hypothetical end-user code

func main() {
	doSomethingWithEmbedType(&Node{})
}

func doSomethingWithEmbedType(a any) {
	em := As[*BaseType](a)
	if em == nil {
		panic("embed nil")
	}
	fmt.Println(em.Hello())
}

[rcoreilly]

Do NOT get too carried away with generator stuff!

Once we have a generator tool (goki), it is tempting to start generating everything. However, there is a real cost to generated code, in that it is therefore not under direct control of the user, and creates "hidden" links.

• Example: auto-generate interfaces from tagged struct methods: https://github.com/rjeczalik/interfaces https://github.com/vburenin/ifacemaker -- this is convenient for keeping the comment docs updated, but OTOH it is overall a rare (and breaking!) event to update the interface, so on balance, it is probably not worth it.

[rcoreilly]

Struct fields are better than maps for Config, Styling, etc

Configuration settings, typically settable with a config file and / or command-line arguments, are stored as key-value maps in the widely used cobra, viper and other such tools. Likewise, in v1 of GoGi, styling was set using Props maps.

However, using a struct with appropriately-named fields has the following advantages:

• Compile time name-safety: the compiler ensures you didn't mistype the key name.
• Compile time type-safety: the type of the property is not any but the actual type needed.
• Tab completion and full lookup in IDEs -- much easier when using config values in an app, and also when setting styling in GUI.
• GUI editor of config opts as a StructView has full access to field tag GUI hints, etc.
• gti can provide access to field comments for full docs for each option -- the map impl requires separate maps of docs vs. values.

This is why the grease configuration and app command management system is based structs, and v2 of GoGi uses "direct styling" functions that directly set values on the gist style structs.