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 ᛫ CLI ᛫ Config

Features

• Fast execution: No reflection is used at runtime
• Automatically converts builtin types: slices, maps, named types, primitive types, pointers, structs with same fields
• Deep copies per default and supports shallow copying
• 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
• Detailed documentation with a lot examples
• Thoroughly tested, see our test scenarios

Getting Started

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 Settings for more information.

4. Run goverter:

   $ go run github.com/emp1re/goverter-test/cmd/goverter@latest gen ./
   

   It's recommended to use an explicit version instead of latest. See Installation and CLI 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
   }
   

   See Generation for more information.

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 GenerateConverters(c *GenerateConfig) error
• type GenerateConfig

Functions

func GenerateConverters

func GenerateConverters(c *GenerateConfig) error

GenerateConverters generates converters.

Types

type GenerateConfig

type GenerateConfig struct {
	// PackagePatterns are golang package patterns to scan, required.
	PackagePatterns []string
	// WorkingDir is the working directory (usually the location of go.mod file), can be empty.
	WorkingDir string
	// Global are the global config commands that will be applied to all converters
	Global config.RawLines
	// BuildTags is a comma separated list passed to -tags when scanning for conversion interfaces.
	BuildTags string
	// OutputBuildConstraint will be added as go:build constraints to all files.
	OutputBuildConstraint string
}

GenerateConfig the config for generating a converter.