generator

README

This package exposes ConversionGenerator, a public struct that fulfills the Generator interface in an generic, extensible way to be able to write custom generators for converting similar structs across two (or more) packages.

See for example how kubernetes wraps ConversionGenerator into its own genConversion generator struct to generate its conversion functions.

Documentation

Index

• func ConversionFunctionName(in, out *types.Type) string
• func ConversionNamer() *namer.NameStrategy
• type ConversionGenerator
  • func NewConversionGenerator(context *generator.Context, outputFileName, typesPackage, outputPackage string, ...) (*ConversionGenerator, error)
  • func (g *ConversionGenerator) Filter(context *generator.Context, t *types.Type) bool
  • func (g *ConversionGenerator) GenerateType(context *generator.Context, t *types.Type, writer io.Writer) error
  • func (g *ConversionGenerator) GetPeerTypeFor(context *generator.Context, t *types.Type) *types.Type
  • func (g *ConversionGenerator) Imports(context *generator.Context) (imports []string)
  • func (g *ConversionGenerator) ManualConversions() map[ConversionPair]*types.Type
  • func (g *ConversionGenerator) Namers(context *generator.Context) namer.NameSystems
  • func (g *ConversionGenerator) WithExternalConversionsHandler(...) *ConversionGenerator
  • func (g *ConversionGenerator) WithFunctionTagName(functionTagName string) *ConversionGenerator
  • func (g *ConversionGenerator) WithInconvertibleFieldsHandler(...) *ConversionGenerator
  • func (g *ConversionGenerator) WithManualConversionsTracker(tracker *ManualConversionsTracker) *ConversionGenerator
  • func (g *ConversionGenerator) WithMissingFieldsHandler(...) *ConversionGenerator
  • func (g *ConversionGenerator) WithTagName(tagName string) *ConversionGenerator
  • func (g *ConversionGenerator) WithUnsupportedTypesHandler(handler func(inVar, outVar NamedVariable, sw *generator.SnippetWriter) error) *ConversionGenerator
  • func (g *ConversionGenerator) WithoutUnsafeConversions() *ConversionGenerator
• type ConversionPair
• type ManualConversionsTracker
  • func NewManualConversionsTracker(additionalConversionArguments ...NamedVariable) *ManualConversionsTracker
• type NamedVariable
  • func NewNamedVariable(name string, t *types.Type) NamedVariable

Functions

func ConversionFunctionName

func ConversionFunctionName(in, out *types.Type) string

ConversionFunctionName returns the name of the conversion function for in to out.

func ConversionNamer

func ConversionNamer() *namer.NameStrategy

ConversionNamer returns a namer for conversion function names. It is a good namer to use as a default namer when using conversion generators, so as to limit the number of changes the generator makes.

Types

type ConversionGenerator

type ConversionGenerator struct {
	generator.DefaultGen

	// ImportTracker tracks the raw namer's imports.
	// It can be re-used by wrapper generators.
	ImportTracker namer.ImportTracker
	// contains filtered or unexported fields
}

func NewConversionGenerator

func NewConversionGenerator(context *generator.Context, outputFileName, typesPackage, outputPackage string, peerPackages []string, manualConversionsTracker *ManualConversionsTracker) (*ConversionGenerator, error)

NewConversionGenerator builds a new ConversionGenerator. The manual conversion tracker can be nil, but should be set either if there are additional conversion arguments, or to re-use a single tracker across several generators, for efficiency.

func (*ConversionGenerator) Filter

func (g *ConversionGenerator) Filter(context *generator.Context, t *types.Type) bool

Filter filters the types this generator operates on.

func (*ConversionGenerator) GenerateType

func (g *ConversionGenerator) GenerateType(context *generator.Context, t *types.Type, writer io.Writer) error

GenerateType processes the given type.

func (*ConversionGenerator) GetPeerTypeFor

func (g *ConversionGenerator) GetPeerTypeFor(context *generator.Context, t *types.Type) *types.Type

GetPeerTypeFor returns the peer type for type t.

func (*ConversionGenerator) Imports

func (g *ConversionGenerator) Imports(context *generator.Context) (imports []string)

Imports returns the imports to add to generated files.

func (*ConversionGenerator) ManualConversions

func (g *ConversionGenerator) ManualConversions() map[ConversionPair]*types.Type

func (*ConversionGenerator) Namers

func (g *ConversionGenerator) Namers(context *generator.Context) namer.NameSystems

Namers returns the name system used by ConversionGenerators.

func (*ConversionGenerator) WithExternalConversionsHandler

func (g *ConversionGenerator) WithExternalConversionsHandler(handler func(inVar, outVar NamedVariable, sw *generator.SnippetWriter) (bool, error)) *ConversionGenerator

WithExternalConversionsHandler allows setting a callback to decide what happens when converting from inVar.Type to outVar.Type, but outVar.Type is in a different package than inVar.Type - and so this generator can't know where to find a conversion function for that. Same as for other handlers, the callback can freely write into the snippet writer, at the spot in the auto-generated conversion function where the conversion code for that type should be. If the handler returns an error, the auto-generated private conversion function (i.e. autoConvert_a_X_To_b_Y) will still be generated, but not the public wrapper for it (i.e. Convert_a_X_To_b_Y). The handler can also choose to panic to stop the generation altogether, e.g. by calling klog.Fatalf. If this is not set, missing fields are silently ignored. The boolean returned by the handler should indicate whether it has written code to handle the conversion. Note that the snippet writer's context is that of the generator (in particular, it can use any namers defined by the generator).

func (*ConversionGenerator) WithFunctionTagName

func (g *ConversionGenerator) WithFunctionTagName(functionTagName string) *ConversionGenerator

WithFunctionTagName allows setting the function tag name, ie the marker that this generator will look for in comments on manual conversion functions. In a function's comments:

• "+<tag-name>=copy-only" : copy-only functions that are directly assignable can be inlined instead of invoked. As an example, conversion functions exist that allow types with private fields to be correctly copied between types. These functions are equivalent to a memory assignment, and are necessary for the reflection path, but should not block memory conversion.
• "+<tag-name>=drop" means to drop that conversion altogether.

func (*ConversionGenerator) WithInconvertibleFieldsHandler

func (g *ConversionGenerator) WithInconvertibleFieldsHandler(handler func(inVar, outVar NamedVariable, inMember, outMember *types.Member, sw *generator.SnippetWriter) error) *ConversionGenerator

WithInconvertibleFieldsHandler allows setting a callback to decide what happens when converting from inVar.Type to outVar.Type, and when inVar.Type's inMember and outVar.Type's outMember are of inconvertible types. Same as for other handlers, the callback can freely write into the snippet writer, at the spot in the auto-generated conversion function where the conversion code for that field should be. If the handler returns an error, the auto-generated private conversion function (i.e. autoConvert_a_X_To_b_Y) will still be generated, but not the public wrapper for it (i.e. Convert_a_X_To_b_Y). The handler can also choose to panic to stop the generation altogether, e.g. by calling klog.Fatalf. If this is not set, missing fields are silently ignored. Note that the snippet writer's context is that of the generator (in particular, it can use any namers defined by the generator).

func (*ConversionGenerator) WithManualConversionsTracker

func (g *ConversionGenerator) WithManualConversionsTracker(tracker *ManualConversionsTracker) *ConversionGenerator

WithManualConversionsTracker allows setting the ManualConversionsTracker that this generator uses. This is convenient to re-use the same tracker for multiple generators, thus avoiding to re-do the work of looking for manual conversions in the same packages several times - which is especially notably for peer packages, which often are the same across multiple generators. Note that also sets the additional conversion arguments to be those of the tracker (see WithAdditionalConversionArguments).

func (*ConversionGenerator) WithMissingFieldsHandler

func (g *ConversionGenerator) WithMissingFieldsHandler(handler func(inVar, outVar NamedVariable, member *types.Member, sw *generator.SnippetWriter) error) *ConversionGenerator

WithMissingFieldsHandler allows setting a callback to decide what happens when converting from inVar.Type to outVar.Type, and when inVar.Type's member doesn't exist in outType. The callback can freely write into the snippet writer, at the spot in the auto-generated conversion function where the conversion code for that field should be. If the handler returns an error, the auto-generated private conversion function (i.e. autoConvert_a_X_To_b_Y) will still be generated, but not the public wrapper for it (i.e. Convert_a_X_To_b_Y). The handler can also choose to panic to stop the generation altogether, e.g. by calling klog.Fatalf. If this is not set, missing fields are silently ignored. Note that the snippet writer's context is that of the generator (in particular, it can use any namers defined by the generator).

func (*ConversionGenerator) WithTagName

func (g *ConversionGenerator) WithTagName(tagName string) *ConversionGenerator

WithTagName allows setting the tag name, ie the marker that this generator will look for in comments on types. * "+<tag-name>=false" in a type's comment will instruct conversion-gen to skip that type.

func (*ConversionGenerator) WithUnsupportedTypesHandler

func (g *ConversionGenerator) WithUnsupportedTypesHandler(handler func(inVar, outVar NamedVariable, sw *generator.SnippetWriter) error) *ConversionGenerator

WithUnsupportedTypesHandler allows setting a callback to decide what happens when converting from inVar.Type to outVar.Type, and this generator has no idea how to handle that conversion. Same as for other handlers, the callback can freely write into the snippet writer, at the spot in the auto-generated conversion function where the conversion code for that type should be. If the handler returns an error, the auto-generated private conversion function (i.e. autoConvert_a_X_To_b_Y) will still be generated, but not the public wrapper for it (i.e. Convert_a_X_To_b_Y). The handler can also choose to panic to stop the generation altogether, e.g. by calling klog.Fatalf. If this is not set, missing fields are silently ignored. Note that the snippet writer's context is that of the generator (in particular, it can use any namers defined by the generator).

func (*ConversionGenerator) WithoutUnsafeConversions

func (g *ConversionGenerator) WithoutUnsafeConversions() *ConversionGenerator

WithoutUnsafeConversions allows disabling the use of unsafe conversions between types that share the same memory layouts.

type ConversionPair

type ConversionPair struct {
	InType  *types.Type
	OutType *types.Type
}

a ConversionPair represents a conversion pair from inType to outType

type ManualConversionsTracker

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

a ManualConversionsTracker keeps track of manually defined conversion functions.

func NewManualConversionsTracker

func NewManualConversionsTracker(additionalConversionArguments ...NamedVariable) *ManualConversionsTracker

NewManualConversionsTracker builds a new ManualConversionsTracker. Additional conversion arguments allow users to set which arguments should be part of a conversion function signature. When generating conversion code, those will be added to the signature of each conversion function, and then passed down to conversion functions for embedded types. This allows to generate conversion code with additional argument, eg

Convert_a_X_To_b_Y(in *a.X, out *b.Y, s conversion.Scope) error

Manually defined conversion functions will also be expected to have similar signatures.

type NamedVariable

type NamedVariable struct {
	Name string
	Type *types.Type
}

A NamedVariable represents a named variable to be rendered in snippets.

func NewNamedVariable

func NewNamedVariable(name string, t *types.Type) NamedVariable