Copygen is a command-line code generator that generates type-to-type and field-to-field code without adding any reflection or dependencies to your project. Manual-copy code generated by Copygen is 391x faster than jinzhu/copier, and adds no allocation to your program. Copygen is the most customizable type-based generator to-date and features a rich yet simple setup. Copygen supports every Go type including basic, array, slice, map, chan, interface, and func types.
Each example has a README.
| Example | Description |
|---|---|
| main | The default example. |
| basic | Matches a basic type to a field. |
| automatch | Uses the automatch feature with depth. |
| map | Uses the manual map feature. |
| tag | Uses the manual tag feature. |
| deepcopy (Roadmap) | Uses the deepcopy option. |
| error | Uses .go templates to return an error. |
| tmpl | Uses .tmpl templates. |
| program | Uses Copygen programmatically. |
*multi tests every type.
This example uses three type-structs to generate the ModelsToDomain() function using a Command Line Interface.
The following types are defined in a program.
./domain/domain.go
// Package domain contains business logic models.
package domain
// Account represents a user account.
type Account struct {
ID int
UserID string
Name string
Other string // The other field is not used.
}./models/model.go
// Package models contains data storage models (i.e database).
package models
// Account represents the data model for account.
type Account struct {
ID int
Name string
Password string
Email string
}
// A User represents the data model for a user.
type User struct {
UserID int
Name string
UserData string
}The models.Account and models.User fields will be copied to domain.Account fields.
Setting up Copygen is a 2-step process involving a YML and GO file.
# Define where the code will be generated.
generated:
setup: ./setup.go
output: ../copygen.go
# Define the optional custom templates used to generate the file (.go, .tmpl supported).
template: ./generate.go
# Define custom options (which are passed to generator options) for customization.
custom:
option: The possibilities are endless.The main example ignores the template fields.
Create an interface in the specified setup file with a type Copygen interface. In each function, specify the types you want to copy from as parameters, and the type you want to copy to as return values. This interface is inspired by goverter.
/* Specify the name of the generated file's package. */
package copygen
/* Copygen defines the functions that will be generated. */
type Copygen interface {
// custom see table below for options
ModelsToDomain(*models.Account, *models.User) *domain.Account
}Copygen uses no allocation with pointers because Go is pass-by-value. Specifying a pointer results in the object's fields being assigned directly; as opposed to a copy of the object's fields.
You can specify options for your Copygen functions using comments: Do NOT put empty lines between comments that pertain to one function. Options are evaluated in order of declaration.
| Option | Use | Description | Example |
|---|---|---|---|
map from to |
Map fields manually. | Copygen uses its automatcher by default. Override this to map fields to and from each other. Regex is supported for from-fields. |
map .* package.Type.Field map models.Account.ID domain.Account.ID |
tag field key |
Map fields manually using tags. | Copygen uses its automatcher by default. Override this using tag with regex and a tag key. |
tag package.Type.Field key tag .* api (all fields) |
depth field level |
Use a specific field depth. | Copygen uses full-field depth by default. Override this using depth with regex and a depth-level integer. |
depth .* 2 depth models.Account.* 1 |
deepcopy field |
Deepcopy from-fields. | Copygen shallow copies fields by default. Override this using deepcopy with regex. For more info, view Shallow Copy vs. Deep Copy. |
deepcopy package.Type.Field deepcopy .* (all fields) |
automatch field |
Use the automatcher selectively or with map and tag. |
Using map or tag disables the default automatcher. Enable it using automatch with regex. |
automatch package.Type.Field automatch models.User.* |
custom option |
Specify custom function options. | Use custom options with templates. Returns map[string][]string (trim-spaced). |
ignore true swap false |
In certain cases, you may want to specify a how a specific type or field is copied with a function. This can be done by defining a function with a convert option.
/* Define the function and field this converter is applied to using regex. */
// convert .* models.User.UserID
// Itoa converts an integer to an ascii value.
func Itoa(i int) string {
return c.Itoa(i)
}Install the command line utility: Copygen is an executable and not a dependency, so use go install.
go install github.com/switchupcb/copygen@latest
Install a specific version by specifying a branch.
go install github.com/switchupcb/copygen@main
Install a specific version by specifying a tag.
go install github.com/switchupcb/copygen@v0.4.0
Run the executable with given options.
# Specify the .yml configuration file.
copygen -yml path/to/ymlThe path to the YML file is specified in reference to the current working directory.
This example outputs a copygen.go file with the specified imports and functions.
// Code generated by github.com/switchupcb/copygen
// DO NOT EDIT.
// Package copygen contains the setup information for copygen generated code.
package copygen
import (
c "strconv"
"github.com/switchupcb/copygen/examples/main/domain"
"github.com/switchupcb/copygen/examples/main/models"
)
// Itoa converts an integer to an ascii value.
func Itoa(i int) string {
return c.Itoa(i)
}
// ModelsToDomain copies a *models.Account, *models.User to a *domain.Account.
func ModelsToDomain(tA *domain.Account, fA *models.Account, fU *models.User) {
// *domain.Account fields
tA.ID = fA.ID
tA.UserID = Itoa(fU.UserID)
tA.Name = fA.Name
}Copygen's method of input and output allows you to generate code not limited to copying fields.
Custom types external to your application can be created for use in the setup.go file. When a file is generated, all types (structs, interfaces, funcs) are copied EXCEPT the type Copygen interface.
type DataTransferObject struct {
// ...
}
type Model interface {
// ...
}
func New() {
// ...
}The library generates a shallow copy function by default. An easy way to deep-copy fields with the same return type is by using new() as or in a converter function or by using a custom template.
Copygen supports three methods of code generation: .go, .tmpl, and programmatic. View the models.Generator type for context on the parameters passed to each function. Generator options are parsed from the YML configuration file. Function options are parsed from custom options. Any other option represents a FieldOption.
Use .go files to customize the code generation algorithm. The copygen generator uses the package template Generate(*models.Generator) (string, error) to generate code. As a result, this function is required for your .go templates to work. The error example modifies the .yml in order to use custom .go template functions that return error. The template/generate.go file provides the default code generation algorithm for generating code.
Use of non-extracted Go Module Imports in generate.go template files are unsupported at the current time.
Use .tmpl (text/templates) to customize the code generation algorithm. The template example uses a .tmpl file to generate code.
Use copygen as a third-party module in your application. For more information, read the program example.
Copygen provides two methods of field-matching: automatch and manual.
Disable the matcher from the command-line using -xm or programmatically by setting Enviroment.DisableMatcher = true.
When fields aren't specified using options, Copygen will attempt to automatch type-fields by name and definition. Automatch will match one from-field to many to-fields. Automatch supports field-depth (where types are located within fields) and recursive types (where the same type is in another type). Automatch loads types from Go modules (in GOPATH): Ensure your modules are up to date by using go get -u <insert/module/import/path>.
Using the map or tag option disables the automatcher, which allows you to manually match fields. In order to re-enable the automatcher, use the automatch option. Options are evaluated in order of declaration, so using automatch .* after declaring map and tag options provides an easy way to re-enable the automatcher for remaining fields.
The automatcher uses a field-based depth system. A field with a depth-level of 0 will only match itself. Increasing the depth-level allows its sub-fields to be matched. This system allows you to specify the depth-level for whole types and specific fields.
// depth-level in relation to the first-level field (0).
type Account
// 1
ID int
Name string
Email string
Basic domain.T // int
User domain.DomainUser
// 2
UserID string
Name string
UserData map[string]interface{}
// 1
Log log.Logger
// 2
mu sync.Mutex
// 3
state int32
sema uint32
// 2
prefix string
flag int
out io.Writer
// 3
Write func(p []byte) (n int, err error)
buf []byteCopygen's main purpose is to save you time by generating boilerplate code to map objects together.
In order to keep a program adaptable (to new features), a program may contain two types of models. The first type of model is the domain model which is used throughout your application to model its business logic. For example, the domain models of Copygen focus on field relations and manipulation. In contrast, the ideal way to store your data (such as in a database) may not match your domain model. In order to amend this problem, you create a data model. The data models of Copygen are located in its configuration loader. In many cases, you will need a way to map these models together to exchange information from your data-model to your domain (and vice-versa). It's tedious to repeatedly do this in the application (through assignment or function definitions). Copygen solves this problem.
Copygen's customizability with templates allows you to generate any code based on types (and their respective fields, tags, etc).
| Example | Description |
|---|---|
| Repogen | Generate a Business-Logic Repository package based on a Data Access Object (DAO) model. |
| Wrapper | Generate functions for requests using an API resource and request object model. |
Check out more usecases in real-world examples using Copygen Usecases.
Copygen uses a GPLv3 License. An exception is provided for template and example files, which are licensed under the MIT License.
Code generated by Copygen can be used without restriction (including proprietary and commercial usage) since generated code is not considered a derivative work. In contrast, modifications to the Copygen Software Source Code and/or implementing Copygen in a larger work programmatically requires you to adhere to the GPLv3 License. These restrictions do NOT apply to template or example files, as long as those files don't generate Copygen itself.
A license exception allows you to modify and/or use Copygen programmatically without restriction. In order to purchase a license exception, please contact SwitchUpCB using the Copygen License Exception Inquiry Form.
You can contribute to this repository by viewing the Project Structure, Code Specifications, CI/CD, and Roadmap.
