Enumer

Enumer generates Go code that adds useful methods to enums (constants with a specific type).

Given this:

//go:generate go run github.com/dmarkham/enumer@latest -type=Pill -json
type Pill int

const (
	Placebo Pill = iota
	Aspirin
	Ibuprofen
	Paracetamol
	Acetaminophen = Paracetamol
)

go generate writes pill_enumer.go and you can do this:

fmt.Println(Aspirin)               // Aspirin
p, err := PillString("ibuprofen")  // p == Ibuprofen (case-insensitive)
PillValues()                       // [Placebo Aspirin Ibuprofen Paracetamol]
PillStrings()                      // [Placebo Aspirin Ibuprofen Paracetamol]
Pill(42).IsAPill()                 // false
json.Marshal(Aspirin)              // "Aspirin"

Enumer is a drop-in replacement for stringer. It generates the same String() method plus the extras below, so existing code keeps working.

Install

Enumer needs Go 1.25 or newer.

The recommended setup pins enumer in go.mod as a tool dependency, so go generate works on a fresh clone with no separate install:

go get -tool github.com/dmarkham/enumer@latest

//go:generate go tool enumer -type=Pill

examples/gomods is a runnable module set up this way.

Two other options:

# Run on demand from go:generate without touching go.mod.
//go:generate go run github.com/dmarkham/enumer@latest -type=Pill

# Install a binary on your PATH.
go install github.com/dmarkham/enumer@latest

Prebuilt binaries for Linux, macOS, and Windows are on the releases page.

Usage

enumer [flags] -type T [directory]
enumer [flags] -type T files...   # files must be in a single package

-type is required and takes a comma-separated list of type names. Everything else is optional. Output goes to <type>_enumer.go in the source directory, lowercased, unless you pass -output.

Always generated

Encoding flags

Each flag adds the methods for one encoding. Combine as many as you need.

All of them store the enum as its string name. Unmarshaling an unknown name returns an error.

Use -text if the enum is a map key you encode as JSON. Without it, encoding/json writes the numeric value as the key.

Scan accepts string, []byte, or any fmt.Stringer. A nil value leaves the receiver unchanged.

Other flags

Changing the string names

By default the string name is the Go identifier. Three flags adjust it, applied in this order:

1. -trimprefix removes a prefix. Pass a comma-separated list to try several. Names without the prefix are left alone.
2. -transform rewrites the case. See the table below.
3. -addprefix prepends a string.

The result is what String() returns, what TString() accepts, and what every encoding uses.

Transforms

Given a constant named MyTypeValue:

Word splitting only works from CamelCase. snake_upper, kebab_upper, dot_upper, first_upper, and first_lower are accepted as aliases of the hyphenated names.

Line comments

With -linecomment, a constant's trailing comment replaces its name. Constants without one keep their identifier.

const (
	Monday Day = iota // lunes
	Tuesday
	Friday // viernes
)

Monday.String() returns lunes, Tuesday.String() returns Tuesday.

Typed errors

With -typederrors, TString(), Validate() and the unmarshal methods return an error that matches enumerrs.ErrValueInvalid under errors.Is. The message still names the bad input.

import "github.com/dmarkham/enumer/enumerrs"

p, err := PillString("Vitamin")
if errors.Is(err, enumerrs.ErrValueInvalid) {
	// "Vitamin does not belong to Pill values"
}

This makes github.com/dmarkham/enumer a runtime dependency of your module, since the generated code imports enumerrs.

Examples

Snake-case JSON for an API:

enumer -type=Status -json -transform=snake

Strip a Go-style prefix and store in a database:

enumer -type=Color -trimprefix=Color -sql -text

Several types at once with a custom file name:

enumer -type=Pill,Day -output=enums_gen.go

History

Enumer started as a fork of Rob Pike's stringer, was extended by Álvaro López Espinosa, and continues here. jsonenums inspired the JSON support.