cuegen

README

CUE Generator

Auto generation of CUE schema and docs from Go struct

Type Conversion

• All comments will be copied to CUE schema

Basic Types

Go Type	CUE Type
int	int
int8	int8
int16	int16
int32	int32
int64	int64
uint	uint
uint8	uint8
uint16	uint16
uint32	uint32
uint64	uint64
float32	float32
float64	float64
string	string
bool	bool
nil	null
byte	uint8
uintptr	uint64
[]byte	bytes
interface{}/any	_

Map Type

• CUE only supports map[string]T type, which is converted to [string]: T in CUE schema
• All map[string]any/map[string]interface{} are converted to {...} in CUE schema

Struct Type

• Fields will be expanded recursively in CUE schema
• All unexported fields will be ignored
• Do not support recursive struct type, which will cause infinite loop

json Tag:

• Fields with json:"FIELD_NAME" tag will be renamed to FIELD_NAME in CUE schema, otherwise the field name will be used
• Fields with json:"-" tag will be ignored in generation
• Anonymous fields with json:",inline" tag will be expanded inlined in CUE schema
• Fields with json:",omitempty" tag will be marked as optional in CUE schema

cue Tag:

• Format: cue:"key1:value1;key2:value2;boolValue1;boolValue2"
• Fields with cue:"enum:VALUE1,VALUE2" tag will be set with enum values VALUE1 and VALUE2 in CUE schema
• Fields with cue:"default:VALUE" tag will be set with default value VALUE in CUE schema, and VALUE must be one of go basic types, including int, float, string, bool
• Separators ';', ':' and ',' can be escaped with '\', e.g. cue:"default:va\\;lue\\:;enum:e\\;num1,e\\:num2\\,enum3" will be parsed as Default: "va;lue:", Enum: []string{"e;num1", "e:num2,enum3"}}

Documentation

Index

• func Ident(name string, isDef bool) *cueast.Ident
• type CommonFields
• type Decl
• type Generator
  • func NewGenerator(f string) (*Generator, error)
  • func (g *Generator) Format(w io.Writer, decls []Decl) error
  • func (g *Generator) Generate(opts ...Option) (decls []Decl, _ error)
  • func (g *Generator) Package() *packages.Package
• type Option
  • func WithNullable() Option
  • func WithTypeFilter(filter func(typ *goast.TypeSpec) bool) Option
  • func WithTypes(types map[string]Type) Option
• type Struct
  • func (s *Struct) Build() cueast.Decl
• type Type

Functions

func Ident

func Ident(name string, isDef bool) *cueast.Ident

Ident returns a new cue identifier with the given name.

Types

type CommonFields

type CommonFields struct {
	Expr    cueast.Expr
	Name    string
	Comment *goast.CommentGroup
	Doc     *goast.CommentGroup
	Pos     cuetoken.Pos
}

CommonFields is a struct that contains common fields for all decls.

type Decl

type Decl interface {
	Build() cueast.Decl
}

Decl is an interface that can build a cueast.Decl.

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator generates CUE schema from Go struct.

func NewGenerator

func NewGenerator(f string) (*Generator, error)

NewGenerator creates a new generator with given file or package path.

func (*Generator) Format

func (g *Generator) Format(w io.Writer, decls []Decl) error

Format formats CUE ast decls with package header and writes to w.

func (*Generator) Generate

func (g *Generator) Generate(opts ...Option) (decls []Decl, _ error)

Generate generates CUE schema from Go struct and writes to w. And it can be called multiple times with different options.

NB: it's not thread-safe.

func (*Generator) Package

func (g *Generator) Package() *packages.Package

Package returns internal package struct, which should be read-only.

type Option

type Option func(opts *options)

Option is a function that configures generation options

func WithNullable

func WithNullable() Option

WithNullable will generate null enum for pointer type

func WithTypeFilter

func WithTypeFilter(filter func(typ *goast.TypeSpec) bool) Option

WithTypeFilter filters top struct types to be generated, and filter returns true to generate the type, otherwise false

func WithTypes

func WithTypes(types map[string]Type) Option

WithTypes appends go types as specified cue types in generation

Example:*k8s.io/apimachinery/pkg/apis/meta/v1/unstructured.Unstructured, TypeEllipsis

• Default any types: interface{}, any
• Default ellipsis types: map[string]interface{}, map[string]any

type Struct

type Struct struct {
	CommonFields
}

Struct is a struct that represents a CUE struct.

func (*Struct) Build

func (s *Struct) Build() cueast.Decl

Build creates a cueast.Decl from Struct.

type Type

type Type string

Type is a special cue type

const (
	// TypeAny converts go type to _(top value) in cue
	TypeAny Type = "any"
	// TypeEllipsis converts go type to {...} in cue
	TypeEllipsis Type = "ellipsis"
)