go-enum

An enum generator for Go that creates type-safe enumerations with useful methods from simple type declarations.

Key Features

• 🎯 Type-safe enums - Generate const declarations with proper typing
• 🔄 String conversion - Automatic String() and Parse() methods
• 📦 JSON marshaling - Built-in JSON marshal/unmarshal support
• 🗄️ SQL integration - Database scan and value functions
• 🧪 Custom templates - Extend with your own code generation
• ✅ Multiple types - Support for int, string, and other base types
• 🏷️ Flexible syntax - Simple comment-based enum declarations

Table of Contents

• Key Features
• Requirements
• Quick Start
• How it works
• String typed enums
• Recent Features
• Goal
• Docker image
• Installation
• Adding it to your project
• Command options
• Syntax
• Examples

Requirements

• Go 1.24.0 or later (recommended for new tool installation method)
• Go 1.23.0 or later (minimum for legacy installation)

Quick Start

1. Install go-enum as a project tool (Go 1.24+):

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

   Or for older Go versions:

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

2. Create a Go file with an enum declaration:

   package main
   // ENUM(red, green, blue)typeColorint

3. Generate the enum:

   # Go 1.24+ (recommended)
   go tool go-enum -f your_file.go
   # Or for older Go versions
   go-enum -f your_file.go

4. Use your generated enum:

   color:=ColorRedfmt.Println(color.String()) // prints "red"parsed, err:=ParseColor("green")
   iferr==nil {
   fmt.Println(parsed) // prints "green"
   }

How it works

go-enum will take a commented type declaration like this:

// ENUM(jpeg, jpg, png, tiff, gif)typeImageTypeint

and generate a file with the iota definition along various optional niceties that you may need:

const (
// ImageTypeJpeg is a ImageType of type Jpeg.ImageTypeJpegImageType=iota// ImageTypeJpg is a ImageType of type Jpg.ImageTypeJpg// ImageTypePng is a ImageType of type Png.ImageTypePng// ImageTypeTiff is a ImageType of type Tiff.ImageTypeTiff// ImageTypeGif is a ImageType of type Gif.ImageTypeGif
)
// String implements the Stringer interface.func (xImageType) String() string// ParseImageType attempts to convert a string to a ImageType.funcParseImageType(namestring) (ImageType, error)
// MarshalText implements the text marshaller method.func (xImageType) MarshalText() ([]byte, error)
// UnmarshalText implements the text unmarshaller method.func (x*ImageType) UnmarshalText(text []byte) error

Fear not the fact that the MarshalText and UnmarshalText are generated rather than JSON methods... they will still be utilized by the default JSON encoding methods.

If you find that the options given are not adequate for your use case, there is an option to add a custom template (-t flag) to the processing engine so that your custom code can be created!

Now with string typed enums

// ENUM(pending, running, completed, failed)typeStrStatestring

const (
// StrStatePending is a StrState of type pending.StrStatePendingStrState="pending"// StrStateRunning is a StrState of type running.StrStateRunningStrState="running"// StrStateCompleted is a StrState of type completed.StrStateCompletedStrState="completed"// StrStateFailed is a StrState of type failed.StrStateFailedStrState="failed"
)

If you would like to get integer values in sql, but strings elsewhere, you can assign an int value in the declaration like always, and specify the --sqlint flag. Those values will be then used to convey the int value to sql, while allowing you to use only strings elsewhere. This might be helpful for things like swagger docs where you want the same type being used on the api layer, as you do in the sql layer, and not have swagger assume that your enumerations are integers, but are in fact strings!

// swagger:enum StrState// ENUM(pending, running, completed, failed)typeStrStatestring

Recent Features

Custom JSON Package Support (v0.7.0+)

You can now specify a custom JSON package for imports instead of the standard encoding/json:

go-enum --marshal --jsonpkg="github.com/goccy/go-json" -f your_file.go

Disable iota (v0.9.0+)

For cases where you don't want to use iota in your generated enums:

go-enum --no-iota -f your_file.go

Custom Output Suffix

Change the default _enum.go suffix to something else:

go-enum --output-suffix="_generated" -f your_file.go # Creates your_file_generated.go

Goal

The goal of go-enum is to create an easy to use enum generator that will take a decorated type declaration like type EnumName int and create the associated constant values and funcs that will make life a little easier for adding new values. It's not perfect, but I think it's useful.

I took the output of the Stringer command as the String() method, and added a way to parse a string value.

Docker image

You can use the Docker image directly for running the command if you do not wish to install anything locally:

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

Installation

Using go get -tool (Go 1.24+, recommended)

Install go-enum as a project tool with dependency tracking in go.mod:

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

This will add a tool dependency to your go.mod file:

tool github.com/abice/go-enum

You can then run the tool using:

go tool go-enum [options]

Using go install (older Go versions)

Install the latest version directly from source:

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

Using GitHub releases

You can download a pre-built binary from GitHub releases. (Thanks to GoReleaser)

# Download the latest release for your platform
curl -fsSL "https://github.com/abice/go-enum/releases/download/v0.9.0/go-enum_$(uname -s)_$(uname -m)" -o go-enum
chmod +x go-enum
# Or use a specific version by replacing v0.9.0 with your desired version# Example: curl -fsSL "https://github.com/abice/go-enum/releases/download/v0.8.0/go-enum_$(uname -s)_$(uname -m)" -o go-enum

Using Docker

You can use the Docker image directly without installing anything locally:

# Use the latest version
docker run -w /app -v $(pwd):/app abice/go-enum:latest
# Or use a specific version
docker run -w /app -v $(pwd):/app abice/go-enum:v0.9.0

Adding it to your project

Using go generate

For Go 1.24+ with tool dependency:

1. Install the tool dependency: go get -tool github.com/abice/go-enum@latest
2. Add a go:generate line to your file: //go:generate go tool go-enum --marshal
3. Run go generate: go generate ./...
4. Enjoy your newly created Enumeration!

For older Go versions:

1. Add a go:generate line to your file: //go:generate go-enum --marshal
2. Run go generate: go generate ./...
3. Enjoy your newly created Enumeration!

Using Makefile

If you prefer makefile stuff, you can always do something like this:

For Go 1.24+ with tool dependency:

STANDARD_ENUMS = ./example/animal_enum.go \
./example/color_enum.go
NULLABLE_ENUMS = ./example/sql_enum.go
$(STANDARD_ENUMS): GO_ENUM_FLAGS=--nocase --marshal --names --ptr
$(NULLABLE_ENUMS): GO_ENUM_FLAGS=--nocase --marshal --names --sqlnullint --ptr
enums: $(STANDARD_ENUMS)$(NULLABLE_ENUMS)# The generator statement for go enum files using go tool (Go 1.24+)%_enum.go: %.go Makefile
go tool go-enum -f $*.go $(GO_ENUM_FLAGS)

For older Go versions:

# The generator statement for go enum files using go-enum binary%_enum.go: %.go $(GOENUM) Makefile
$(GOENUM) -f $*.go $(GO_ENUM_FLAGS)

Command options

go-enum --help
NAME:
go-enum - An enum generator for go
USAGE:
go-enum [global options]
VERSION:
example
GLOBAL OPTIONS:
--file value, -f value [ --file value, -f value ] The file(s) to generate enums. Use more than one flag for more files. [$GOFILE]
--noprefix Prevents the constants generated from having the Enum as a prefix. (default: false)
--lower Adds lowercase variants of the enum strings for lookup. (default: false)
--nocase Adds case insensitive parsing to the enumeration (forces lower flag). (default: false)
--marshal Adds text (and inherently json) marshalling functions. (default: false)
--sql Adds SQL database scan and value functions. (default: false)
--sqlint Tells the generator that a string typed enum should be stored in sql as an integer value. (default: false)
--flag Adds golang flag functions. (default: false)
--jsonpkg value Custom json package for imports instead encoding/json.
--prefix value Adds a prefix with a user one. If you would like to replace the prefix, then combine this option with --noprefix.
--names Generates a 'Names() []string' function, and adds the possible enum values in the error response during parsing (default: false)
--values Generates a 'Values() []{{ENUM}}' function. (default: false)
--nocamel Removes the snake_case to CamelCase name changing (default: false)
--ptr Adds a pointer method to get a pointer from const values (default: false)
--sqlnullint Adds a Null{{ENUM}} typefor marshalling a nullable int value to sql (default: false)
--sqlnullstr Adds a Null{{ENUM}} typefor marshalling a nullable string value to sql. If sqlnullint is specified too, it will be Null{{ENUM}}Str (default: false)
--template value, -t value [ --template value, -t value ] Additional template file(s) to generate enums. Use more than one flag formore files. Templates will be executedin alphabetical order.
--alias value, -a value [ --alias value, -a value ] Adds or replaces aliases for a non alphanumeric value that needs to be accounted for. [Format should be "key:value,key2:value2", or specify multiple entries, or both!]
--mustparse Adds a Must version of the Parse that will panic on failure. (default: false)
--forcelower Forces a camel cased comment to generate lowercased names. (default: false)
--forceupper Forces a camel cased comment to generate uppercased names. (default: false)
--nocomments Removes auto generated comments. If you add your own comments, these will still be created. (default: false)
--buildtag value, -b value [ --buildtag value, -b value ] Adds build tags to a generated enum file.
--output-suffix .go Changes the default filename suffix of _enum to something else. .go will be appended to the end of the string no matter what, so that `_test.go` cases can be accommodated
--no-iota Disables the use of iota in generated enums. (default: false)
--help, -h show help
--version, -v print the version

Syntax

The parser looks for comments on your type defs and parse the enum declarations from it. The parser will look for ENUM( and continue to look for comma separated values until it finds a ). You can put values on the same line, or on multiple lines.
If you need to have a specific value jump in the enum, you can now specify that by adding =numericValue to the enum declaration. Keep in mind, this resets the data for all following values. So if you specify 50 in the middle of an enum, each value after that will be 51, 52, 53...

Examples can be found in the example folder

Comments

You can use comments inside enum that start with //
The comment must be at the end of the same line as the comment value, only then it will be added as a comment to the generated constant.

// Commented is an enumeration of commented values/*ENUM(value1 // Commented value 1value2value3 // Commented value 3)*/typeCommentedint

The generated comments in code will look something like:

...const (
// CommentedValue1 is a Commented of type Value1// Commented value 1CommentedValue1Commented=iota// CommentedValue2 is a Commented of type Value2CommentedValue2// CommentedValue3 is a Commented of type Value3// Commented value 3CommentedValue3
)
...

Example

There are a few examples in the exampledirectory. I've included one here for easy access, but can't guarantee it's up to date.

// Color is an enumeration of colors that are allowed./* ENUM(Black, White, RedGreen = 33 // Green starts with 33*/// Blue// grey=// yellow// blue-green// red-orange// yellow_green// red-orange-blue// )typeColorint32

The generated code will look something like:

// Code generated by go-enum DO NOT EDIT.// Version: example// Revision: example// Build Date: example// Built By: examplepackage example
import (
"fmt""strings"
)
const (
// ColorBlack is a Color of type Black.ColorBlackColor=iota// ColorWhite is a Color of type White.ColorWhite// ColorRed is a Color of type Red.ColorRed// ColorGreen is a Color of type Green.// Green starts with 33ColorGreenColor=iota+30// ColorBlue is a Color of type Blue.ColorBlue// ColorGrey is a Color of type Grey.ColorGrey// ColorYellow is a Color of type Yellow.ColorYellow// ColorBlueGreen is a Color of type Blue-Green.ColorBlueGreen// ColorRedOrange is a Color of type Red-Orange.ColorRedOrange// ColorYellowGreen is a Color of type Yellow_green.ColorYellowGreen// ColorRedOrangeBlue is a Color of type Red-Orange-Blue.ColorRedOrangeBlue
)
const_ColorName="BlackWhiteRedGreenBluegreyyellowblue-greenred-orangeyellow_greenred-orange-blue"var_ColorMap=map[Color]string{
ColorBlack: _ColorName[0:5],
ColorWhite: _ColorName[5:10],
ColorRed: _ColorName[10:13],
ColorGreen: _ColorName[13:18],
ColorBlue: _ColorName[18:22],
ColorGrey: _ColorName[22:26],
ColorYellow: _ColorName[26:32],
ColorBlueGreen: _ColorName[32:42],
ColorRedOrange: _ColorName[42:52],
ColorYellowGreen: _ColorName[52:64],
ColorRedOrangeBlue: _ColorName[64:79],
}
// String implements the Stringer interface.func (xColor) String() string {
ifstr, ok:=_ColorMap[x]; ok {
returnstr
}
returnfmt.Sprintf("Color(%d)", x)
}
var_ColorValue=map[string]Color{
_ColorName[0:5]: ColorBlack,
strings.ToLower(_ColorName[0:5]): ColorBlack,
_ColorName[5:10]: ColorWhite,
strings.ToLower(_ColorName[5:10]): ColorWhite,
_ColorName[10:13]: ColorRed,
strings.ToLower(_ColorName[10:13]): ColorRed,
_ColorName[13:18]: ColorGreen,
strings.ToLower(_ColorName[13:18]): ColorGreen,
_ColorName[18:22]: ColorBlue,
strings.ToLower(_ColorName[18:22]): ColorBlue,
_ColorName[22:26]: ColorGrey,
strings.ToLower(_ColorName[22:26]): ColorGrey,
_ColorName[26:32]: ColorYellow,
strings.ToLower(_ColorName[26:32]): ColorYellow,
_ColorName[32:42]: ColorBlueGreen,
strings.ToLower(_ColorName[32:42]): ColorBlueGreen,
_ColorName[42:52]: ColorRedOrange,
strings.ToLower(_ColorName[42:52]): ColorRedOrange,
_ColorName[52:64]: ColorYellowGreen,
strings.ToLower(_ColorName[52:64]): ColorYellowGreen,
_ColorName[64:79]: ColorRedOrangeBlue,
strings.ToLower(_ColorName[64:79]): ColorRedOrangeBlue,
}
// ParseColor attempts to convert a string to a ColorfuncParseColor(namestring) (Color, error) {
ifx, ok:=_ColorValue[name]; ok {
returnx, nil
}
returnColor(0), fmt.Errorf("%s is not a valid Color", name)
}
func (xColor) Ptr() *Color {
return&x
}
// MarshalText implements the text marshaller methodfunc (xColor) MarshalText() ([]byte, error) {
return []byte(x.String()), nil
}
// UnmarshalText implements the text unmarshaller methodfunc (x*Color) UnmarshalText(text []byte) error {
name:=string(text)
tmp, err:=ParseColor(name)
iferr!=nil {
returnerr
}
*x=tmpreturnnil
}