go-builder-generator

KO | EN

gitlite — search

#golang #go #rust #deep-learning #linux #docker #java #windows #awesome #cli #vue #awesome-list #pytorch #security

go-builder-generator

(★ 10)

Easily generate builders for golang structs

go-builder-generator Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# go-builder-generator

---

- [How to use ?](#how-to-use-)
  - [Go mod (recommended)](#go-mod-recommended)
  - [Go](#go)
  - [Linux](#linux)
- [Commands](#commands)
  - [Generate](#generate)
- [Generation cases](#generation-cases)
  - [Simple struct](#simple-struct)
  - [Generic struct](#generic-struct)
  - [Imported module struct](#imported-module-struct)
  - [Standard library module struct](#standard-library-module-struct)
- [Contributing](#contributing)

## How to use ?

### Go mod (recommended)

See [go1.24 update](https://go.dev/blog/go1.24).

```sh
go get -tool github.com/kilianpaquier/go-builder-generator/cmd/go-builder-generator
```

### Go

```sh
go install github.com/kilianpaquier/go-builder-generator/cmd/go-builder-generator@latest
```

### Linux

```sh
OS="linux" # change it depending on your case
ARCH="amd64" # change it depending on your case
INSTALL_DIR="$HOME/.local/bin" # change it depending on your case

new_version=$(curl -fsSL "https://api.github.com/repos/kilianpaquier/go-builder-generator/releases/latest" | jq -r '.tag_name')
url="https://github.com/kilianpaquier/go-builder-generator/releases/download/$new_version/go-builder-generator_${OS}_${ARCH}.tar.gz"
curl -fsSL "$url" | (mkdir -p "/tmp/go-builder-generator/$new_version" && cd "/tmp/go-builder-generator/$new_version" && tar -xz)
cp "/tmp/go-builder-generator/$new_version/go-builder-generator" "$INSTALL_DIR/go-builder-generator"
```

## Commands

```
Usage:
  go-builder-generator [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  generate    Generate builders for structs arguments present in file argument.
  help        Help about any command
  version     Show current version

Flags:
  -h, --help                help for go-builder-generator
      --log-format string   set logging format (either "text" or "json") (default "text")
      --log-level string    set logging level (default "info")
```

### Generate

```
Generate builders for structs arguments present in file argument.

Usage:
  go-builder-generator generate [flags]

Flags:
  -d, --dest string            destination directory for the generated files (default ".")
  -f, --file string            input file containing golang struct(s) to generate builders on
  -h, --help                   help for generate
      --no-cmd                 removes top comment 'go:generate ...' from generated files
      --no-notice              removes top notice 'Code generated by ...' from generated files
      --no-tool                avoid using go-build-generator as go tool when 'go:generate ...' is added in generated files
      --package-name string    defines a specific package name instead of '--dest', '-d' directory name. Only available when generating files in another directory
  -p, --prefix string          specific prefix to apply on setter functions
      --return-copy            returns a copy of the builder each time a setter function is called
  -s, --structs strings        struct names to generate builders on (they must be contained in given input file). Multiple elements may be given by separating them with a comma or by providing multiple times the flag.
      --validate-func string   validate function name to be executed in Build, must have the signature 'func () error' and associated to built struct

Global Flags:
      --log-format string   set logging format (either "text" or "json") (default "text")
      --log-level string    set logging level (default "info")
```

#### Tags

It's possible to tune builders generation with the struct tag `builder`. The available options are:

- `append`: when provided on a slice (only), the generated builder will append instead of reaffecting.
- `default_func`: when provided, an additional function will be generated in another file suffixed with `_impl.go` to allow manual affectation of field (or even other fields).
- `func_name`: when provided, the name of the function generated in the builder is set to the provided name, ignoring prefix or field name.
- `ignore`: when provided, the field will be ignored in builder generation.
- `pointer`: when provided on a pointer, the generated builder will keep it's pointer on the input parameter.
- `export`: when provided, the builder function associated to the given field (unexported field for that matter) will be exported.
  - It's only applicable when generation is done in the same package as the generated struct and the struct is exported.
  - In the case of an unexported field for an exported struct with the generation in another package, the field will always be ignored during generation.
  - In the case of an unexported field for an unexported struct with the generation in the same package, the builder function will always be exported (because the builder and the new function are unexported).

**Note:** `append` option and `pointer` option are exclusive with a priority for `append` if both provided. Also if `append` is provided on a field not being a slice, it will just be ignored.

Example:

```go
package pkg

//go:generate go tool go-builder-generator generate -f types.go -s StructName -d builders

type StructName struct {
	Pointer               *int64   `builder:"pointer"` // generated builder will be 'SetPointer(pointer *int64)'
	NoPointer             *int64   // generated builder will be 'SetNoPointer(noPointer int64)'
	ASlice                []string `builder:"append"` // generated builder will be 'SetASlice(aSlice ...string)', additionally the affectation will be `b.ASlice = append(b.ASlice, aSlice...)`
	NoAppend              []string // generated builder will be 'SetASlice(noAppend []string)', additionally the affectation will be `b.NoAppend = noAppend`
	Ignore                int64    `builder:"ignore"`                            // no builder will be generated on this field
	DefaultFunc           int64    `builder:"default_func=SomeFuncName"`         // an additional function named 'SomeFuncName' will be generated in target package file '_impl.go' and associated to builder struct
	IgnoreWithDefaultFunc int64    `builder:"ignore,default_func=SomeOtherFunc"` // no builder will be generated and the additional function will be generated
	CustomFuncName        string   `builder:"func_name=FuncNameOverride"`        // generated builder will be 'FuncNameOverride(customFuncName string)'
}

//go:generate go tool go-builder-generator generate -f types.go -s AnotherStructName

type AnotherStructName struct {
	unexportedField string `builder:"export"` // generated builder will be 'UnexportedField(unexportedField string)'
}
```

## Generation cases

### Simple struct

```go
//go:generate go tool go-builder-generator generate -f types.go -s StructName -d builders

type StructName struct {...}
```

### Generic struct

```go
//go:generate go tool go-builder-generator generate -f types.go -s GenericStruct,GenericStructUnary,GenericFieldStruct -d builders

type GenericStruct[T any, ...] struct {...}

type GenericStructUnary[T ~E, E any, ...] struct {...}

type GenericFieldStruct struct {
  Field GenericStruct[string, ...]
}
```

### Imported module struct

In case it's needed to generate a builder on a struct not being one of the current module,
one may provide the `module::` prefix to tell `go-builder-generator` to generate the struct from an **imported** module.
The provided module must be imported in the current module `go.mod`.

This case works with both simple structs and generic structs. Under the hood, `go-builder-generator`
will retrieve the appropriate version from the current module `go.mod` (it works with `replace` too)
and generate with those specific rules:
- If `replace` is provided with a custom path, then it will retrieve the file from that path
- if `GOMODCACHE` environment variable exists, it will retrieve the file from `${GOMODCACHE}/module_name/...`
- If `GOPATH` environment variable exists, it will retrieve the file from `${GOPATH}/pkg/mod/module_name/...`
- If neither `GOMODCACHE` and `GOPATH` environment variables exist, it will retrieve the file from `${HOME}/go/pkg/mod/module_name/...`

```go
//go:generate go tool go-builder-generator generate -f module::github.com/kilianpaquier/go-builder-generator/path/to/file.go -s ExternalStructName -d builders
```

### Standard library module struct

In case it's needed to generate a builder on a struct being in the standard library, one may provide the `std::` prefix to tell `go-builder-generator`.
The difference with `module::` is that the tool will not check whether the package is imported (because of course it's already embedded).

To find the appropriate file, `go-builder-generator` will check in the following order:
- `GOROOT` environment variable to retrieve the path to Golang root directory, the computed path will be `${GOROOT}/src/<path provided with std::>`
- Run `go env GOROOT` to retrieve computed `GOROOT` from Golang directly, the computed path will be `${go env GOROOT}/src/<path provided with std::>`

```go
//go:generate go tool go-builder-generator generate -f std::go/build/build.go -s Context -d builders
```

You may see the [examples](./examples/) folder for real generation cases.

## Contributing

When contributing, you can generate testdata files with `make testdata`.

It will avoid painful manual updates, however, make sure that generated testdata matches what you expect.
Also, make sure to add or update associated tests to your change(s).

go-builder-generator

go-builder-generator Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

go-builder-generator

go-builder-generator Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README