goverter

README

goverter

a "type-safe Go converter" generator

goverter is a tool for creating type-safe converters. All you have to do is create an interface and execute goverter. The project is meant as alternative to jinzhu/copier that doesn't use reflection.

Installation ᛫ Conversion Docs

Features

• Fast execution: No reflection is used at runtime
• Automatically deep copies builtin types: slices, maps, named types, primitive types, pointers, structs with same fields
• Customizable: You can implement custom converter methods
• Clear errors when generating the conversion methods if
  • the target struct has unmapped fields
  • types cannot be converted without losing information

Usage

1. Ensure your go version is 1.16 or above

2. Create a go modules project if you haven't done so already

   $ go mod init module-name
   

3. Create your converter interface and mark it with a comment containing goverter:converter

   input.go

   package example
   
   // goverter:converter
   type Converter interface {
     ConvertItems(source []Input) []Output
   
     // goverter:ignore Irrelevant
     // goverter:map Nested.AgeInYears Age
     Convert(source Input) Output
   }
   
   type Input struct {
     Name string
     Nested InputNested
   }
   type InputNested struct {
     AgeInYears int
   }
   type Output struct {
     Name string
     Age int
     Irrelevant bool
   }
   

   See Conversion for more information.

4. Run goverter:

   $ go run github.com/jmattheis/goverter/cmd/goverter@v0.17.4 ./
   

   See Installation for more information.

5. goverter created a file at ./generated/generated.go, it may look like this:

   package generated
   
   import example "goverter/example"
   
   type ConverterImpl struct{}
   
   func (c *ConverterImpl) Convert(source example.Input) example.Output {
       var exampleOutput example.Output
       exampleOutput.Name = source.Name
       exampleOutput.Age = source.Nested.AgeInYears
       return exampleOutput
   }
   func (c *ConverterImpl) ConvertItems(source []example.Input) []example.Output {
       var exampleOutputList []example.Output
       if source != nil {
           exampleOutputList = make([]example.Output, len(source))
           for i := 0; i < len(source); i++ {
               exampleOutputList[i] = c.Convert(source[i])
           }
       }
       return exampleOutputList
   }
   

Versioning

goverter uses SemVer for versioning the cli.

License

This project is licensed under the MIT License - see the LICENSE file for details

Logo by MariaLetta

Documentation

Index

• func GenerateConverter(c GenerateConfig) ([]byte, error)
• func GenerateConverterFile(fileName string, c GenerateConfig) error
• type GenerateConfig

Functions

func GenerateConverter

func GenerateConverter(c GenerateConfig) ([]byte, error)

GenerateConverter generates converters.

func GenerateConverterFile

func GenerateConverterFile(fileName string, c GenerateConfig) error

GenerateConverterFile generates converters and writes them to a file.

Types

type GenerateConfig

type GenerateConfig struct {
	// PackageName is the package to use for the generated code.
	PackageName string
	// ScanDir is the package with golang files to scan for goverter tags.
	ScanDir string
	// ExtendMethods is a list of extensions to load in addition to goverter:extend statements
	// declared on the interface itself.
	ExtendMethods []string
	// WorkingDir is the working directory (usually the location of go.mod file), can be empty.
	WorkingDir string
	// PackagePath is the full package where the generated code is going to be stored, can be empty.
	// PackagePath is needed if goverter:extend tags use exported methods from the package where
	// generated code resides, making sure goverter does not create a loop import statement from
	// the generated code into its own package.
	PackagePath string
	// WrapErrors instructs goverter to wrap conversion errors and return more details when such
	// are available. For examples, for structs, target field name is reported, for slices: index.
	WrapErrors bool
	// IgnoredUnexportedFields tells goverter to ignore fields that are not exported.
	IgnoredUnexportedFields bool
	// MatchFieldsIgnoreCase tells goverter to use case insensitive match everywhere.
	MatchFieldsIgnoreCase bool
}

GenerateConfig the config for generating a converter.