gen

Documentation

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 string pointer. 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
   String() string // return the string representation of an enumerator
   Valid() bool    // report whether the receiver is a valid 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
    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

• type Config
  • func LoadConfig(path string) (*Config, error)
  • func ParseConfig(r io.Reader) (*Config, error)
  • func (c *Config) Generate(w io.Writer) error
• type Enum
• type Value

Types

type Config

type Config struct {
	Package string  // package name for the generated file (required)
	Enum    []*Enum // enumerations to generate (at least one is required)
}

A Config specifies a collection of enumerations in a single package.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads and parses a YAML configuration from path.

func ParseConfig

func ParseConfig(r io.Reader) (*Config, error)

ParseConfig parses a YAML configuration text from r.

func (*Config) Generate

func (c *Config) Generate(w io.Writer) error

Generate generates the enumerations defined by c into w as Go source text.

If there is an error formatting the generated code, the unformatted code is still written to w before reporting the error. The caller should NOT use the output in case of error. Any error means there is a bug in the generator, and the output is written only to support debugging.

type Enum

type Enum struct {
	Type   string   // enumeration type name (required)
	Values []*Value // the enumeration values (required)

	// If set, this prefix is prepended to each enumerator's variable name.
	// Otherwise, the variable name matches the Name field of the value.
	Prefix string

	// If set, this text is added as a doc comment for the enumeration.
	// Multiple lines are OK. The text should not contain comment markers.
	Doc string

	// If set, a variable is defined for the zero value with this name.
	// Typically a name like "Unknown" or "Invalid" makes sense.
	// Otherwise, no variable is defined for the zero value; the caller can
	// still construct a zero value explicitly if needed.
	Zero string

	// If set, this text is inserted at the top of the var block in the
	// generated code for the enumerator values.
	ValDoc string `yaml:"val-doc"`

	// If true, generate methods to implement flag.Value for the type.
	FlagValue bool `yaml:"flag-value"`

	// If true, implement encoding.TextMarshaler for the type.
	TextMarshal bool `yaml:"text-marshal"`
}

An Enum defines an enumeration type.

The generated type for an enumeration is a struct with an unexported pointer to the string representation of the enumerator. This representation allows cheap pointer comparisons, and users of the type outside the package cannot create new non-zero values of the type. The zero value is explicitly defined as the "unknown" value for an enumeration.

type Value

type Value struct {
	Name string // enumerator name (required)

	// If set, this text is added as a doc comment for the enumerator value.  If
	// it is a single line, it is added as a line comment; otherwise it is
	// placed before the enumerator. The text should not contain comment markers.
	Doc string

	// If set, this text is used as the string representation of the value.
	// Otherwise, the Name field is used.
	Text string
}

A Value defines a single enumerator.