examples

Examples

Simple Example

The following demonstrates a summary of the code that is generated using a simple config. See the following example/s for more information.

Using this simple YAML configuration file (stored in config.yaml for example):

enums:
  - package: Some Go Package
    type: An Example Enum Type
    values:
      - This is the first value
      - this.is.another.value
      - andA.third_one

Despite the inconsistent naming/casing of the values, and the fact that the package and type are not valid Go identifiers, the following Go code is generated (summarized & commented for clarity).

Running goenums ./config.yaml ./ will generate the following enum definition in ./some_go_package/an_example_enum_type.go:

package some_go_package

import "fmt"

// This file is generated by goenums; DO NOT EDIT

// AnExampleEnumType wraps an enum value of type anExampleEnumType to enforce type safety.
type AnExampleEnumType struct {
	anExampleEnumType
}

// anExampleEnumType is the underlying type of AnExampleEnumType and should not be used directly.
type anExampleEnumType int

// String returns the string representation of the enum value
func (a anExampleEnumType) String() string

// ParseAnExampleEnumType attempts to parse the given value into AnExampleEnumType.
// It supports string, fmt.Stringer, int, int64, and int32.
// If the value is not a valid AnExampleEnumType or the value is not a supported type, it will return the enums unknown value (unknownAnExampleEnumType).
func ParseAnExampleEnumType(a any) AnExampleEnumType

// IsValid returns true if the enum value is valid.
// The unknown value (unknownAnExampleEnumType) is not considered valid.
func (a anExampleEnumType) IsValid() bool

// AnExampleEnumTypeContainer contains all possible values of type AnExampleEnumType 
type AnExampleEnumTypeContainer struct {
	UNKNOWN                 AnExampleEnumType
	THIS_IS_THE_FIRST_VALUE AnExampleEnumType
	THIS_IS_ANOTHER_VALUE   AnExampleEnumType
	AND_A_THIRD_ONE         AnExampleEnumType
}

// AnExampleEnumTypes is a global instance of AnExampleEnumTypeContainer that contains all possible values of type AnExampleEnumType.
var AnExampleEnumTypes = AnExampleEnumTypeContainer{
	UNKNOWN:                 AnExampleEnumType{unknownAnExampleEnumType},
	THIS_IS_THE_FIRST_VALUE: AnExampleEnumType{thisIsTheFirstValueAnExampleEnumType},
	THIS_IS_ANOTHER_VALUE:   AnExampleEnumType{thisIsAnotherValueAnExampleEnumType},
	AND_A_THIRD_ONE:         AnExampleEnumType{andAThirdOneAnExampleEnumType},
}

// All returns a slice containing all possible values of type AnExampleEnumType.
func (c AnExampleEnumTypeContainer) All() []AnExampleEnumType

// MarshalJSON returns the JSON representation of the enum value.
func (a *AnExampleEnumType) MarshalJSON() ([]byte, error)

// UnmarshalJSON parses the JSON representation of the enum value.
func (a *AnExampleEnumType) UnmarshalJSON(b []byte) error

For more information regarding implementation details and usage see the following example/s.

In-Depth Example

This directory contains an example project which has multiple enums defined in the same configuration file. For verbosity, the configuration file is written in both JSON and YAML formats:

• enum_config.json
• enum_config.yaml

These files demonstrate how to perform the same configuration in both JSON and YAML formats.

The enums directory contains:

• role.go - The generated code for the Role enum
• role_ext.go - Some manually written code to extend the Role enum with domain specific methods
• account_status.go - The generated code for the AccountStatus enum
• account_status_ext.go - Some manually written code to extend the AccountStatus enum with domain specific methods

The role.go and account_status.go files can be regenerated using any of the following commands (from the projects root directory):

# Using the JSON configuration file
go run ./cmd/goenums/ ./examples/config/enums.json ./examples/enums/

# Using the YAML configuration file
go run ./cmd/goenums/ ./examples/config/enums.yaml ./examples/enums/

# Using the output_path defined in the YAML configuration file
go run ./cmd/goenums/ ./examples/config/enums.yaml

# Using the go:generate directive in the `multiple-enums/main.go` file
go generate ./examples/...

The main.go file contains the go:generate directive to regenerate the role.go and account_status.go files. The role_ext.go and account_status_ext.go files are manually written and are not regenerated.

The main.go file demonstrates how to use the Role and AccountStatus enums outside the auth package.

The extension files (role_ext.go and account_status_ext.go) demonstrate how to extend the enums from within the auth package.