https://github.com/switchupcb/copygen
Go generator to copy values from type to type and fields from struct to struct (copier without reflection). Generate any code based on types.
https://github.com/switchupcb/copygen
code-generation code-generator copy generator go golang
Last synced: 24 days ago
JSON representation
Go generator to copy values from type to type and fields from struct to struct (copier without reflection). Generate any code based on types.
- Host: GitHub
- URL: https://github.com/switchupcb/copygen
- Owner: switchupcb
- License: gpl-3.0
- Created: 2021-09-21T01:51:04.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-03-10T21:16:42.000Z (about 1 year ago)
- Last Synced: 2024-07-31T20:51:43.539Z (9 months ago)
- Topics: code-generation, code-generator, copy, generator, go, golang
- Language: Go
- Homepage: https://switchupcb.com/copygen-license-exception/
- Size: 429 KB
- Stars: 339
- Watchers: 4
- Forks: 22
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - copygen - Generate type-to-type and type-based code without reflection. (Generators / Search and Analytic Databases)
- awesome-go-extra - copygen - 09-21T01:51:04Z|2022-07-28T12:28:22Z| (Generators / Utility/Miscellaneous)
README
[
](https://github.com/switchupcb/copygen#copygen)
---
[](https://pkg.go.dev/github.com/switchupcb/copygen)
[](https://github.com/switchupcb/copygen/blob/main/LICENSE)
[
](https://github.com/avelino/awesome-go#generators)
Copygen saves you from losing time writing repetitive code with a type-based code generator.
## What is Copygen?
Copygen is a command-line and programmatic **code generator** that generates custom type-based code, including 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**](https://github.com/gotidy/copy#benchmark) than **jinzhu/copier** and adds no allocation to your program.
_Copygen supports **every** Go type including `basic`, `array`, `slice`, `map`, `chan`, `interface`, and `func` types._
## Table of Contents
| Topic | Categories |
| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| [Usage](#how-do-you-use-copygen) | [Types](#step-1-define-go-types), [Setup](#step-2-configure-the-setup-files), [Command Line](#step-3-use-the-command-line), [Output](#output) |
| [Customization](#customization) | [Custom Objects](#custom-objects), [Templates](#templates) |
| [Matcher](#matcher) | [Automatch](#automatch), [Manual](#manual), [Depth](#depth) |
| [Usecases](#usecase) | [When to Use](#when-to-use-copygen), [Custom Generation](#custom-generation) |
| [License](#what-is-the-license) | [What can I do?](#what-can-you-do-with-this-license), [License Exception](#what-is-a-license-exception) |
## How do you use Copygen?
Each example has a **README**.
| Example | Description |
| :------------------------------- | :--------------------------------------- |
| main | The default example. |
| [basic](examples/basic/) | Matches a `basic` type to a field. |
| [automatch](examples/automatch/) | Uses the automatch matcher with depth. |
| [map](examples/map/) | Uses the manual map matcher. |
| [tag](examples/tag/) | Uses the manual tag matcher. |
| [cast](examples/cast/) | Uses the cast modifier. |
| deepcopy _(Roadmap)_ | Uses the deepcopy option. |
| [error](examples/error/) | Uses `.go` templates to return an error. |
| [tmpl](examples/tmpl/) | Uses `.tmpl` templates. |
| [program](examples/program/) | Uses Copygen programmatically. |
_*[`multi`](examples/_tests/multi/setup/setup.go) tests every type._
This [example](examples/main/) uses three type-structs to generate the `ModelsToDomain()` function using a Command Line Interface.
### Step 1. Define Go Types
Go types are defined in a file.
`./domain/domain.go`
```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`
```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.
### Step 2. Configure the setup files
You set up Copygen with a `YML` and `GO` file.
#### setup.yml
```yml
# Define where the code is 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.
```
#### setup.go
Define a `type Copygen interface` in the specified setup file.
In each function, specify _the types you want to copy from_ as parameters, and _the types you want to copy to_ as return values.
_This interface is inspired by **goverter**._
```go
/* Specify the name of the generated file's package. */
package copygen
/* Copygen defines the functions that are 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. So, using a pointer results in the object's fields being assigned directly as opposed to a copy of the object's fields._
#### options
Use comments to specify options for Copygen functions: Do **NOT** add empty lines between comments that pertain to one function.
**Options are evaluated in order of declaration.**
| Option | Use | Description | Example |
| :------------------ | :--------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
| `automatch field` | Use the automatcher selectively or with `map` and `tag` options. | Using `map` or `tag` disables the default automatcher.
Enable it again using `automatch` with _regex_. | `automatch package.Type.Field`
`automatch models.User.*` |
| `map from to` | Map fields manually. | `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 struct tags. | Use `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](#depth) by default.
Override this using `depth` with _regex_ and a [depth-level](#depth) 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](#shallow-copy-vs-deep-copy). | `deepcopy package.Type.Field`
`deepcopy .*` _(all fields)_ |
| `custom option` | Specify custom function options. | Use custom options with [templates](#templates).
Returns `map[string][]string` _(trim-spaced)_. | `ignore true`
`swap false` |
_[View a reference on Regex.](https://cheatography.com/davechild/cheat-sheets/regular-expressions/)_
A matching option _(e.g. `map`, `automatch`, `tag`)_ determines whether the field is matched to another field, but a modifying option _(e.g. `convert`, `cast`)_ is only applied when a field is matched.
#### Convert
Use the `convert function field` option to control how a type or field is copied within a function when the field is matched.
```go
/* 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)
}
```
_This example converts the `models.User.UserID` value using `Itoa` within all functions (`.*`) when the `models.User.UserID` field is matched._
#### Cast
Use the `setup.yml` `matcher: cast` generator option to enable automatic casting when a field is matched.
Use the `setup.go` `cast from to modifier` option to perform direct type assertion, conversion, expressions, function usage, and property usage with a matched field.
For more information, read the [`cast` example](/examples/cast/).
### Step 3. Use the Command Line
Install the command line utility: Copygen.
```
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/[email protected]
```
Run the executable with given options.
```bash
copygen -yml path/to/yml
```
_The path to the YML file must be specified in reference to the current working directory._
### Output
This example outputs a `copygen.go` file with the specified imports and functions.
```go
// 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
}
```
## Customization
Copygen's method of input and output lets you generate code that isn't limited to copying fields.
### Custom Objects
Custom types external to your application can be defined in the setup file (`.go`): When an output file is generated, all types _(structs, interfaces, funcs)_ defined in the setup file (`.go`) are copied **EXCEPT** the `type Copygen interface`.
```go
type DataTransferObject struct {
// ...
}
type Model interface {
// ...
}
func New() {
// ...
}
```
### Shallow Copy vs. Deep Copy
The library generates [shallow copy](https://en.m.wikipedia.org/wiki/Object_copying#Shallow_copy) functions by default.
Do you need to deepcopy instead? Use `new()` within a `convert` or `cast` function **or** use a customized generator template.
### Templates
Copygen supports three methods of code generation: `.go`, `.tmpl`, and `programmatic`.
You can view the [models.Generator](cli/models/generator.go) 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`.
#### .go
Use `.go` files to customize the code generation algorithm: The `copygen` generator uses the [`package template Generate(*models.Generator) (string, error)`](cli/generator/template/generate.go) to generate code. So, **this function is required** for your `.go` templates to work.
The [error example](examples/error/) modifies the configuration file (`.yml`) to use **custom `.go` template functions** that `return error`. The [`template/generate.go`](/cli//generator/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](cli/generator/template/generate.go) are unsupported at the current time._
#### .tmpl
Use `.tmpl` _([`text/templates`](https://pkg.go.dev/text/template))_ to customize the code generation algorithm. The [template example](examples/tmpl/) uses a [`.tmpl`](/examples/tmpl/template/generate.tmpl) file to generate code.
#### programmatic
Use `copygen` as a third-party module in your application. For more information, read the [program example](/examples/program/README.md).
## Matcher
Copygen provides two methods of field-matching: `automatch` and `manual`.
_You can disable the matcher using the `matcher: skip: true` option in the setup file._
### Automatch
Copygen automatically matches the function's fields by field name and definition when a [matching option _(`automatch`,`map`,`tag`)_](#options) isn't specified on a function.
- Automatch matches one from-field to many to-fields
- **Automatch supports field-depth** (when fields contain fields) **and recursive types** (when the field contains itself).
- Automatch loads types from Go modules _(in the `GOPATH`)_: Confirm your Go modules are up-to-date using `go get -u `.
### Manual
Using the `map` or `tag` option disables the automatcher, which lets you 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 is an easy way to re-enable the _automatcher_ for remaining fields.
#### Depth
The automatcher uses a field-based depth system where a field with a depth-level of 0 only matches itself. This system lets you specify the depth-level for specific types and fields. Increasing the depth-level lets the field's sub-fields at a specified depth-level be matched.
```go
// 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 []byte
```
## Usecase
### When to Use Copygen
Copygen's default purpose is to save you time by generating code to map objects together.
### Why would you do that?
You generate code to map objects together when your program contains multiple models types (e.g., `domain`, `database`), which improves feature development speed without affecting performance.
_Here is an example._
Suppose a program maintains two types of models for feature development.
- The **domain model** is a human-optimized definition of the business logic, and is used by a human to develop business logic. For example, an `account` model which is defined for use by a human.
- The **data model** is a machine-optimized definition of the business logic, and is used by a machine to execute business logic efficiently. For example, a database model of an `account` which defines `username`, `profile_picture`, and other account related data in separate models for database efficiency.
These models are created because the ideal method of data storage is not the ideal domain model. However, you must map these models together to exchange information from your data model to your domain model and vice-versa.
_Here is an example of how Copygen uses this development pattern._
- The [domain models of Copygen](cli/models/) focus on field relations and manipulation as understood by a human.
- The [data models of Copygen](cli/config/models.go) are located in its configuration loader and Go type `ast` structs.
- The "business logic" of Copygen is defined in the `parser`, `matcher`, and `generator`, which use the `domain` models of Copygen to generate code instead of underlying `ast` data structs.
### Custom Generation
Copygen's customizability with templates lets you 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](https://github.com/switchupcb/copygen/discussions/categories/usecases)._
## What is the License?
Copygen uses a [AGPLv3 License](https://www.gnu.org/licenses/agpl-3.0.en.html).
An exception is provided for template and example files, which are licensed under the [MIT License](cli/generator/template/LICENSE.md).
### What can you do with this license?
**Code generated by Copygen can be used without restriction (including proprietary and commercial usage)** since generated code is not considered a derivative work. However, **modifications** to the _Copygen Software Source Code_ or implementing Copygen in a larger work **programmatically** requires you to [adhere to the AGPLv3 License](https://www.gnu.org/licenses/gpl-faq.html).
_These restrictions do **NOT** apply to template or example files, as long as those files don't generate Copygen itself._
### What is a license exception?
A license exception lets you modify and use Copygen programmatically **without restriction**.
You can receive a license exception for Copygen by contacting SwitchUpCB using the [Copygen License Exception Inquiry Form](https://switchupcb.com/copygen-license-exception/).
## Contributing
You can contribute to this repository by viewing the [Project Structure, Code Specifications, CI/CD, and Roadmap](CONTRIBUTING.md).