go-enum

The go-enum parser identifies enum declarations by looking for an ENUM(...) block within comments preceding a type definition. You can list values on a single line or multiple lines. To assign a specific numeric value to an enum member, use the =numericValue syntax. Note that assigning a specific value resets the sequence for all subsequent members (e.g., if you set a value to 50, the next will be 51).

/* ENUM(
Black, White, Red
Green = 33
)
*/
type Color int32

The generator parses a commented type declaration and produces a companion file containing constants, string conversion, and marshaling logic.

Input Syntax

// ENUM(jpeg, jpg, png, tiff, gif)
type ImageType int

Generated Output

For the input above, go-enum generates:

• Constants: ImageTypeJpeg, ImageTypeJpg, etc., using iota.
• Stringer: A String() method for the type.
• Parser: A ParseImageType(name string) function to convert strings back to the type.
• Marshaling: MarshalText() and UnmarshalText() methods (which are also used by the standard encoding/json package).

You can automate enum generation by adding a //go:generate directive to your Go files.

For Go 1.24+ (with tool dependency)

Add this to your file:

//go:generate go tool go-enum --marshal

For older Go versions

Add this to your file:

//go:generate go-enum --marshal

Then run go generate ./... in your terminal.

To include comments in the generated code, place a // comment on the same line as the enum value inside the ENUM() block. The parser will attach these comments to the corresponding generated constant.

/*
ENUM(
value1 // Commented value 1
value2
value3 // Commented value 3
)
*/
type Commented int

Depending on your Go version, use one of the following methods to install go-enum:

Go 1.24+ (Recommended)

Install as a project tool to track it in your go.mod file:

go get -tool github.com/abice/go-enum@latest

Then run it using go tool go-enum.

Older Go Versions

Install directly to your $GOPATH/bin:

go install github.com/abice/go-enum@latest

Then run it using the go-enum command.

Using Docker

Run the tool without local installation:

docker run -w /app -v $(pwd):/app abice/go-enum:latest

To generate an enum, follow these steps:

1. Declare your type in a Go file using the // ENUM(val1, val2, ...) comment syntax.
2. Run the generator pointing to your file using the -f flag.
3. Use the generated methods like .String() and Parse<TypeName>() in your code.

Example declaration:

// ENUM(red, green, blue)
type Color int

go tool go-enum -f your_file.go

You can define enums where the underlying type is a string instead of an int. This is useful for APIs or documentation where string values are preferred over integer constants.

Example:

// ENUM(pending, running, completed, failed)
type StrState string

This generates constants like StrStatePending StrState = "pending".

The go-enum CLI tool accepts several global options to customize the generated code. Common options include:

• --file, -f: The file(s) to generate enums from.
• --marshal: Adds text (and JSON) marshalling functions.
• --sql: Adds SQL database scan and value functions.
• --names: Generates a Names() []string function.
• --values: Generates a Values() []{{ENUM}} function.
• --ptr: Adds a .Ptr() method to get a pointer from constant values.
• --mustparse: Adds a MustParse version of the Parse function that panics on failure.
• --no-iota: Disables the use of iota in generated enums.
• --jsonpkg <value>: Specifies a custom JSON package for imports instead of encoding/json.

go-enum --help

Common flags for the go-enum CLI tool:

The go-enum CLI tool parses Go source files and generates companion enum files. By default, it appends _enum.go to the original filename. You can specify input files using the --file (or -f) flag, which supports glob patterns (e.g., *.go).

Common workflows include adding JSON marshalling, SQL support, or pointer methods to your generated enums via CLI flags.

# Basic usage with a specific file
go-enum --file my_types.go

# Using glob patterns to process multiple files
go-enum --file models/*.go

# Generating enums with JSON and SQL support
go-enum --file types.go --marshal --sql