gen

Overview ¶

Package gen implements an enumeration generator.

Enumerations are described by a configuration. Each enumeration defines a type name and one or more enumerator values.

Type Structure ¶

The generated type is a struct containing an unexported small integer index to the string representation of the enumerator. Enumerators of the type can be compared for equality by value, and can be used as map keys. The zero value represents an unknown (invalid) enumerator; the Valid method reports whether an enumerator is valid (i.e., non-zero).

The String method returns a string representation for each enumerator, which defaults to the enumerator's base name. The Enum method returns the name of the enumeration type.

Enumerations generated by this package all satisfy this interface:

type EnumType interface {
   Enum() string   // return the enumeration type name
   Index() int     // return the integer index of the enumerator
   String() string // return the string representation of an enumerator
   Valid() bool    // report whether the receiver is a valid nonzero enumerator
}

Callers wishing to accept arbitrary enumerations may define this interface. It is not exported by the gen package to discourage inappropriate dependency on the code generator.

Configuration ¶

The gen.Config type defines a set of enumerations to generate in a single package. The general structure of a config in YAML is:

package: "name"        # the name of the output package (required)

enum:                  # a list of enumeration types to generate

  - type: "Name"       # the type name for this enum
    prefix: "x"        # (optional) prefix to append to each enumerator name
    zero: "Bad"        # (optional) name of zero enumerator

    doc: "text"        # (optional) documentation comment for the enum type
    val-doc: "text"    # (optional) aggregate documentation for the values

    constructor: true  # construct a New* function to convert strings to enumerators
    flag-value: true   # implement the flag.Value interface on this enum
    text-marshal: true # implement the TextMarshaler/Unmarshaler interfaces on this enum

    values:
      - name: A        # the name of the first enumerator (required)
        doc: "text"    # (optional) documentation for this enumerator
        text: "aaa"    # (optional) string text for the enumerator
        index: 25      # (optional) integer index for the enumerator

      - name: B        # ... additional enumerators
      - name: C

  - type: "Other"
    values:
      - name: X
      - name: Y

package main

import (
	"log"
	"os"

	"github.com/creachadair/enumgen/gen"
)

const input = `package example
/*enumgen:type Example

# package example inferred from the declaration above.
# The type name assigned by the enumgen: comment.

doc: Example is an example enumeration.
values:
  - name: Good
    doc: upsides
  - name: Bad
    doc: downsides
  - name: Ugly
    doc: what it says on the tin
*/
`

func main() {
	cfg, err := gen.ConfigFromSource("example.go", []byte(input))
	if err != nil {
		log.Fatalf("Parse: %v", err)
	}
	if err := cfg.Generate(os.Stdout); err != nil {
		log.Fatalf("Generate: %v", err)
	}
}

Output:

// Code generated by enumgen. DO NOT EDIT.

package example

// Example is an example enumeration.
type Example struct{ _Example uint8 }

// Enum returns the name of the enumeration type for Example.
func (Example) Enum() string { return "Example" }

// String returns the string representation of Example v.
func (v Example) String() string { return _str_Example[v._Example] }

// Valid reports whether v is a valid non-zero Example value.
func (v Example) Valid() bool { return v._Example > 0 && int(v._Example) < len(_str_Example) }

// Index returns the integer index of Example v.
func (v Example) Index() int { return int(v._Example) }

var (
	_str_Example = []string{"<invalid>", "Good", "Bad", "Ugly"}

	Good = Example{1} // upsides
	Bad  = Example{2} // downsides
	Ugly = Example{3} // what it says on the tin
)