enum

README

Better enums for Go

This library provides automatic enum code generation for Go.

Installation

Install by typing:

go get github.com/apitalist/enum/cmd/enum

Then create a file called tools.go and add the following dependency to make sure `go mod tidy doesn't remove it:

//go:build tools
package yourpackage

import _ "github.com/apitalist/enum"

Usage

First, add your enum:

type MyEnum string

const (
    MyEnumA MyEnum = "a"
    MyEnumB MyEnum = "b"
)

Then add a generate line:

//go:generate go run github.com/apitalist/enum/cmd/enum/ -type MyEnum

This will generate a file called enum_MyEnum.go as well as enum_MyEnum_test.go with the following helpers:

func (m MyEnum) Validate() error {
    // ...
}

func (m *MyEnum) UnmarshalJSON(data []byte) error {
    // Only generated for non-struct enums
}

func MyEnumValues() []MyEnum {
    // ...
}

func MyEnumValueStrings() []string {
    // ...
}

type MyEnums []MyEnum

func (m MyEnums) Validate() error {
    // ...
}

It also supports other enum types:

//go:generate go run github.com/apitalist/enum/cmd/enum/ -type MyEnum
type MyEnum int

const (
    MyEnumA MyEnum = iota
    MyEnumB
    MyEnumC
)

Or safe enums. You may want to implement JSON and text marshalling for these though.

//go:generate go run github.com/apitalist/enum/cmd/enum/ -type MyEnum
type MyEnum struct {
    value string
}

var (
    MyEnumA MyEnum = MyEnum{"a"}
    MyEnumB MyEnum = MyEnum{"b"}
    MyEnumC MyEnum = MyEnum{"c"}
)

Options

You can pass the following options to the enum generator:

Option	Default value	Description
-type	none	Type to generate enum from
-source	.	Source directory
-target	enum_TYPENAME.go	Target file name. The tests will be generated into a file named _test.go
-notests	false	Do not generate tests
-novalidate	false	Do not generate Validate() functions
-novalues	false	Do not generate Values() functions
-nolist	false	Do not generate list types
-nojson	false	Do not generate UnmarshalJSON() function.

Documentation

For API documentation please see pkg.go.dev/github.com/apitalist/enum.

License

APItalist is licensed under the Apache 2.0 license.

Documentation

Index

• type Generator
  • func New() Generator
• type Spec
  • func (s *Spec) Validate() error
• type TemplateScope
  • func (t TemplateScope) Imports(added ...string) []string

Types

type Generator

type Generator interface {
	// Generate generates the enum helpers, as well as test code if desired. If the generation fails, an error is
	// returned.
	Generate(spec Spec) ([]byte, []byte, error)
}

Generator generates helper code for working with enums.

func New

func New() Generator

New creates a new generator.

type Spec

type Spec struct {
	// Type is the type to generate enum helpers for.
	Type string
	// Directory is the source directory for the generation.
	Directory string
	// GenerateTests generates test code for the generated enum code.
	GenerateTests bool
	// GenerateValidate generates a validation function.
	GenerateValidate bool
	// GenerateValues generates a values function.
	GenerateValues bool
	// GenerateListType generates a list type.
	GenerateListType bool
	// GenerateJSON generates a JSON unmarshaller with validation.
	GenerateJSON bool
}

Spec is the configuration for the Generator.

func (*Spec) Validate

func (s *Spec) Validate() error

Validate validates the specification.

type TemplateScope

type TemplateScope struct {
	// Exported is true if the type is exported.
	Exported bool
	// Package is the package name for the type.
	Package string
	// First is the first letter of the type.
	First string
	// LowerFirst is the first letter of the type, lower case.
	LowerFirst string
	// Type is the name of the type being generated.
	Type string
	// Values is a list of values for the enum.
	Values []string
	// ConvertToString is the prefix for converting to string.
	ConvertToString string
	// ConverToStringEnd is the suffix for converting to string.
	ConvertToStringEnd string
	// RawType is the underlying type.
	RawType string
	// Spec is the input spec.
	Spec Spec
	// ConvertImports holds a list of imports used for conversion.
	ConvertImports map[string]struct{}
}

TemplateScope is the data for rendering templates.

func (TemplateScope) Imports

func (t TemplateScope) Imports(added ...string) []string