From 5f623a8d3166cb49539ff681d83fc70f8b1d0bc0 Mon Sep 17 00:00:00 2001 From: Benjamin Bengfort Date: Tue, 7 Apr 2026 19:55:14 -0500 Subject: [PATCH 1/2] [DOCS] Updated README.md --- README.md | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 103 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 8d68f2c..0e4dfab 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,104 @@ go install go.rtnl.ai/enumify/cmd/enumify@latest This will add the `enumify` command to your `$PATH`. -Next steps: +Next, in the package that you'd like to create an enum for, define a `.go` file as follows: + +```go +//go:generate enumify +type Status uint8 + +// Constants for the Status enum values. +// These values should be discovered by the enumify generator since they use the same +// type as the Status enum, which is the type being generated. +const ( + StatusUnknown Status = iota + StatusPending + StatusRunning + StatusFailed + StatusSuccess + StatusCancelled +) + +// String representations for the Status enum values; the enumify generator will +// discover this since it has the pattern [enum]Names and a []string or [][]string type. +var statusNames []string{ + "unknown", "pending", "running", "failed", "success", "canceled", +} +``` + +Run `go generate ./...` and two files `[file]_gen.go` and `file_gen_test.go` will be generated with a Parser function and all of the interface methods for the enum as well as a test suite for testing the enum wrt the enumify package. + +Enumify uses static parsing to discover the type definitions in your `.go` file. It looks for any `type [Enum] uint8` definition, and determines that is the enum being used. Any constants that are of type `[Enum]` will be extracted as well as the string reprs in a `[enum]Names` variable. + +You can also use a `[][]string` table to capture other enum information. For example: + +```go +//go:generate enumify -names colorTable +type Color uint8 + +const ( + NoColor Color = iota + Red + Blue + Green +) -1. Define enum schema file -2. Create generate command -3. Run go generate ./... -4. Run go mod tidy +var colorTable [][]string{ + {"none", "red", "blue", "green"}, + {"", "#FF0000", "#0000FF", "#00FF00"} +} -Boom - your package is ready to go with enums! +func (c Color) Hex() string { + return colorNames[1][c] +} +``` + +You can call the string representations variable anything you'd like so long as you pass in the `-names` flag with the variable name; otherwise the `[enum]Names` pattern works for both `[]string` and `[][]string` variables. + +> **NOTE**: The generator only works on one file at a time, if you have multiple files with enums in each file; you'll need a `go:generate` directive in each file. However, if you have multiple enums in a single file, you'll only need one `go:generate` directive. + +## CLI Options + +You can pass options to the `go:generate` directive as you would any CLI program. The latest help text is as follows: + +```text +Enumify is a code generation tool for easily creating and managing +typed enumerations with code generation and automated enum tests. + +Usage: add a go directive to a go file file for generation: + + //go:generate enumify [-version] [-help] [opts] + +Then run run the go tool code generation command: + + go generate ./... + +Options: + -case-sensitive + make the enum case sensitive + -names string + variable name that contains the string reprs of the enum values + -no-binary + skip binary interfaces code generation + -no-json + skip JSON interfaces code generation + -no-parser + skip parser code generation + -no-sql + skip SQL interfaces code generation + -no-stringer + skip Stringer interface code generation + -no-tests + skip testing code generation + -no-text + skip text interfaces code generation + -no-yaml + skip YAML interfaces code generation + -space-sensitive + make the enum space sensitive + -version + print the version and exit +``` ## Theory @@ -31,6 +121,13 @@ However, the boilerplate code for implementing `fmt.Stringer`, `json.Marshaler`, Key theory point: the value behind the enum shouldn't matter, just its ordering. The first value (0) should always be the "unknown" or "default" value. You can compare enums but you cannot have them be specific runes or other values. +## References + +The following blog posts and package documentation was invaluable to the implementation of this package: + +- [A taste of Go code generator magic: a quick guide to getting started](https://evilmartians.com/chronicles/a-taste-of-go-code-generator-magic-a-quick-guide-to-getting-started) +- [Jennifer is a code generator for Go.](https://github.com/dave/jennifer) + ## License This project is licensed under the BSD 3-Clause License. See [`LICENSE`](./LICENSE) for details. Please feel free to use Enumify in your own projects and applications. From 2f3f97b41edc0fbc14e17a83bec500033270452b Mon Sep 17 00:00:00 2001 From: Benjamin Bengfort Date: Tue, 7 Apr 2026 20:01:44 -0500 Subject: [PATCH 2/2] code quality --- .github/workflows/tests.yaml | 6 ++++++ README.md | 2 ++ 2 files changed, 8 insertions(+) diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 52a6d96..7603ecc 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -11,6 +11,8 @@ on: jobs: go-lint: name: Go Lint + permissions: + contents: read runs-on: ubuntu-latest steps: - name: Setup Go @@ -29,6 +31,8 @@ jobs: go-test: name: Go Test + permissions: + contents: read runs-on: ubuntu-latest env: GOPATH: ${{ github.workspace }}/go @@ -60,6 +64,8 @@ jobs: build: name: Go Build + permissions: + contents: read runs-on: ubuntu-latest env: GOPATH: ${{ github.workspace }}/go diff --git a/README.md b/README.md index 0e4dfab..5245e36 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Enumify +[![CI Tests](https://github.com/rotationalio/enumify/actions/workflows/tests.yaml/badge.svg)](https://github.com/rotationalio/enumify/actions/workflows/tests.yaml) + **Easily create and manage typed enumerations with code generation and automated enum tests.** We found ourselves generating a lot of boilerplate code for our Enums: particularly for parsing, serialization/deserialization, database storage, and tests. Really we just want to be able to describe an Enum and get all of this code for free! Enumify is the combination of a code generator for the boilerplate code as well as a package for reducing the boilerplate and ensuring that everything works as expected.