gocode

Documentation

Overview

Package tgo provides tools for generating native Go types from Thema's lineage and schema abstractions. Eventually, this package may also support generating Thema from Go inputs.

"tgo" is the package name rather than simply "go" because the latter is a reserved keyword.

Index

• func GenerateLineageBinding(lin thema.Lineage, cfg *BindingConfig) ([]byte, error)
• func GenerateTypesOpenAPI(sch thema.Schema, cfg *TypeConfigOpenAPI) ([]byte, error)
• func PostprocessGoFile(cfg GenGoFile) ([]byte, error)
• type BindingConfig
• type GenGoFile
• type TypeConfigOpenAPI

Functions

func GenerateLineageBinding

func GenerateLineageBinding(lin thema.Lineage, cfg *BindingConfig) ([]byte, error)

GenerateLineageBinding generates Go code that makes a Thema lineage defined in a .cue file reliably available in Go via a thema.LineageFactory or thema.ConvergentLineageFactory.

The thema CLI implements the capabilities of this function via the `thema lineage gen go` subcommand. The CLI command should meet most use cases, though some may require the additional flexibility earned by writing a Go program that calls this function directly.

func GenerateTypesOpenAPI

func GenerateTypesOpenAPI(sch thema.Schema, cfg *TypeConfigOpenAPI) ([]byte, error)

GenerateTypesOpenAPI generates native Go code corresponding to the provided Schema.

func PostprocessGoFile

func PostprocessGoFile(cfg GenGoFile) ([]byte, error)

Types

type BindingConfig

type BindingConfig struct {
	// EmbedPath is the path that will appear in the generated go:embed variable
	// that is expected to contain the definition of the provided lineage.
	//
	// It is the responsibility of the caller to ensure that the file referenced
	// by EmbedPath contains the definition of the provided Lineage.
	//
	// If empty, no embed will be generated.
	//
	// EmbedPath is passed unmodified to the binding template, so multiple paths may be
	// provided, separated by spaces, per the //go:embed spec.
	EmbedPath string

	// LoadDir is the path that will be passed to when calling
	// [load.InstanceWithThema] within the generated loadInstanceFor$NAME func.
	//
	// If empty, the func will not be generated.
	LoadDir string

	// CueModName is the name of the CUE module that will be used when calling
	// [load.AsModFS] within the generated themaFSFor$NAME func.
	//
	// If empty, the func will not be generated.
	CueModName string

	// TitleName is the title-case name of the lineage. If empty, this will default
	// to the result of [strings.Title] called on lineage.name.
	TitleName string

	// CuePath is the path to the lineage within the instance referred to by EmbedPath.
	// If non-empty, the generated binding will include a [cue.Value.LookupPath] call
	// prior to calling [thema.BindLineage].
	CuePath cue.Path

	// FactoryNameSuffix determines whether the [thema.LineageFactory] or
	// [thema.ConvergentLineageFactory] implementation will be generated with
	// a title-cased lineage.name as a suffix.
	//
	// For example, for a lineage with lineage.name "foo", if this
	// property is false, the generated code will be:
	//  func Lineage(...) {...}
	// but if true, the following code will be generated:
	//  func LineageFoo(...) {...}
	FactoryNameSuffix bool

	// PrivateFactory determines whether the generated lineage factory will be
	// exported (`func Lineage` vs. `func doLineage`).
	//
	// A private factory may be preferable in cases where, for example, it is
	// desirable to ensure that certain [thema.BindOption] are always passed, or to
	// memoize the generated lineage factory function using the *thema.Runtime
	// parameter as a key.
	PrivateFactory bool

	// Assignee is an dst.Ident that determines the generic type parameter used
	// in the generated [thema.ConvergentLineageFactory]. If this parameter is nil,
	// a [thema.LineageFactory] is generated instead.
	Assignee *dst.Ident

	// TargetSchemaVersion determines the schema version that will be used in a call
	// to [thema.BindType], along with Assignee, in order to create a
	// thema.ConvergentLineage.
	//
	// This value is ignored if Assignee is nil.
	TargetSchemaVersion thema.SyntacticVersion

	// PackageName determines the name of the generated Go package. If empty, the
	// lowercase version of the Lineage.Name() is used.
	PackageName string

	// ApplyFuncs is a slice of AST manipulation funcs that will be executed against
	// the generated Go file prior to running it through goimports. For each slice
	// element, [dstutil.Apply] is called with the element as the "pre" parameter.
	ApplyFuncs []dstutil.ApplyFunc

	// IgnoreDiscoveredImports causes the generator not to fail with an error in the
	// event that goimports adds additional import statements. (The default behavior
	// is to fail because adding imports entails a search, which can slow down
	// codegen by multiple orders of magnitude. Succeeding silently but slowly is a bad
	// default behavior when the fix is usually quite easy.)
	IgnoreDiscoveredImports bool
}

BindingConfig governs the behavior of GenerateLineageBinding.

type GenGoFile

type GenGoFile struct {
	Path     string
	Appliers []dstutil.ApplyFunc
	In       []byte

	// IgnoreDiscoveredImports causes the processing not to fail with an error in the
	// event that goimports adds additional import statements. (The default behavior
	// is to fail because adding imports entails a search, which can slow down
	// codegen by multiple orders of magnitude. Succeeding silently but slowly is a bad
	// default behavior when the fix is usually quite easy.)
	IgnoreDiscoveredImports bool
}

type TypeConfigOpenAPI

type TypeConfigOpenAPI struct {
	// PackageName determines the name of the generated Go package. If empty, the
	// lowercase version of the Lineage.Name() is used.
	PackageName string

	// ApplyFuncs is a slice of AST manipulation funcs that will be executed against
	// the generated Go file prior to running it through goimports. For each slice
	// element, [dstutil.Apply] is called with the element as the "pre" parameter.
	ApplyFuncs []dstutil.ApplyFunc

	// IgnoreDiscoveredImports causes the generator not to fail with an error in the
	// event that goimports adds additional import statements. (The default behavior
	// is to fail because adding imports entails a search, which can slow down
	// codegen by multiple orders of magnitude. Succeeding silently but slowly is a bad
	// default behavior when the fix is usually quite easy.)
	IgnoreDiscoveredImports bool

	// NoOptionalPointers causes optional schema fields to be represented as normal
	// Go struct fields, rather than as pointers. For example, a `foo?: string`
	// field is usually converted to `Foo *string`, but is instead converted `Foo
	// string` when NoOptionalPointers is true.
	NoOptionalPointers bool

	// UseGoDeclInComments sets the name of the fields and structs at the beginning of each comment.
	UseGoDeclInComments bool

	// Config is passed through to the Thema OpenAPI encoder, [openapi.GenerateSchema].
	Config *openapi.Config
}

TypeConfigOpenAPI governs the behavior of GenerateTypesOpenAPI.