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 ¶
- Constants
- Variables
- func GenerateLineageBinding(lin thema.Lineage, cfg *BindingConfig) ([]byte, error)
- func LineageTypes(cfg LineageTypeConfig) jenny.Jenny[thema.Lineage]
- func PostprocessGoFile(cfg GenGoFile) ([]byte, error)
- func SchemaTypes(cfg TypeConfig) jenny.Jenny[thema.Schema]
- type BindingConfig
- type GenGoFile
- type LineageTypeConfig
- type Syntax
- type TypeConfig
Constants ¶
const TypesFile = "types.go"
TypesFile is the name of the file SchemaTypes writes.
Variables ¶
var PackageFromDir = jenny.TreeMapper(func(f jenny.File, s Syntax) (Syntax, error) { pkg := path.Base(path.Dir(f.Path())) if !token.IsIdentifier(pkg) { return s, fmt.Errorf("%s: directory %q is not a Go package name", f.Path(), pkg) } file := *s.File name := *file.Name name.Name = pkg file.Name = &name return Syntax{Fset: s.Fset, File: &file}, nil })
PackageFromDir is a mapper that names the package of each Go file of Syntax after the directory the file is in, as LineageTypes does for each version. It fails for a file with no directory, or one whose directory is not a Go identifier, and passes every file that is not a tree of Syntax through unchanged.
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 LineageTypes ¶
func LineageTypes(cfg LineageTypeConfig) jenny.Jenny[thema.Lineage]
LineageTypes is a jenny that runs SchemaTypes for every schema in the lineage, and places each version's file in a directory and package of its own, named for the version: v0_0/types.go, in package v0_0, for version 0.0.
func PostprocessGoFile ¶
func SchemaTypes ¶
func SchemaTypes(cfg TypeConfig) jenny.Jenny[thema.Schema]
SchemaTypes is a jenny that writes TypesFile, declaring a type that the schema's instances can be decoded into, along with the types it needs: a named struct type for each nested struct, and a named string type with typed constants for each disjunction of strings.
Optional fields are pointers (or nil-able maps, slices and interfaces) with `omitzero`, and `null | T` is a pointer to T. Constraints Go cannot express, such as bounds and regular expressions, are dropped to the base type; a scalar field's default is noted in its doc comment. A disjunction of structs, or of values of different kinds, is `any`. CUE's int is int64, and number is float64.
The file is a jenny tree of Syntax.
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.
// The generated binding passes it to [thema.BindLineage] with the instance's
// root; empty means the lineage is the root.
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 LineageTypeConfig ¶
type LineageTypeConfig struct {
// RootName is the name of the Go type generated for each schema, as on
// [TypeConfig.RootName]. Each version is a package of its own, so every
// version's root type has the same name.
RootName string
}
LineageTypeConfig governs the behavior of LineageTypes.
type Syntax ¶
Syntax is a Go source file as a syntax tree. The Go types jennies emit their files as jenny trees of Syntax, so a pipeline can rewrite them with a jenny.TreeMapper[Syntax]; a tree renders gofmt-formatted.
type TypeConfig ¶
type TypeConfig struct {
// PackageName is the name of the generated Go package. If empty, the
// lowercase lineage name is used.
PackageName string
// RootName is the name of the Go type generated for the schema itself. If
// empty, it is the lineage name with its first letter capitalized: Ship
// for lineage "ship".
//
// Types generated for the schema's nested structs, enums and definitions
// are named with RootName as their prefix.
RootName string
}
TypeConfig governs the behavior of SchemaTypes.
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
gentest
Package gentest holds Go types generated by encoding/gocode from the exemplar lineages and from the shapes lineage in shapes.cue, each lineage in a directory named for it, as LineageTypes lays out its versions: expand/v0_2/types.go.
|
Package gentest holds Go types generated by encoding/gocode from the exemplar lineages and from the shapes lineage in shapes.cue, each lineage in a directory named for it, as LineageTypes lays out its versions: expand/v0_2/types.go. |