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. Values of the type can be compared for equality by value. 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)

	Prefix string // prefix for enumerator names
	Doc    string // documentation for the enumeration type
	Zero   string // define a zero enumerator with this name
	ValDoc string `yaml:"val-doc"` // aggregate documentation for the values
}

An Enum defines an enumeration type.

type Value

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

	Doc  string // documentation for the enumerator
	Text string // string text for the enumerator
}

A Value defines a single enumerator.