README ¶
Enumerations for Go
- Make simple Go enumerations work well for you using this easy-to-use code generator.
You could use stringer here or a related alterative here. But they both depend on your code compiling cleanly.
Sometimes, the code generation gets in the way because you can't compile without the generated code and you can't generate the code without compiling.
That's where this tool steps in. It has a basic Go source code parser that finds idiomatic
enumerations, as shown below. It runs on any source code that's "clean enough", even if the
source code is still incomplete. Provided your type
is ok and your const
is complete, you'll be fine.
It will not handle C-style comments though, so these must not be present. The normal double-slash is OK.
First, Install
go get github.com/rickb777/enumeration/v2
You should see that the enumeration
binary is now in the bin folder on your GOPATH. Make sure this is
on your PATH so it can be run.
Now, write some Go
For example,
type Day int
const (
Sunday Day = iota
Monday
Tuesday
Wednesday
Thursday
Friday
Partyday
numberOfDays // this constant is not exported but is included in the enumeration
)
this example comes from the Go Language Reference.
Another example, which also includes the optional go:generate
line,
//go:generate enumeration -type Month
type Month uint
const (
January, February, March Month = 1, 2, 3
April, May, June Month = 4, 5, 6
July, August, September Month = 7, 8, 9
October, November, December Month = 10, 11, 12
)
Note that the full language specification is flexible, allowing several alternative equivalent syntaxes for declaring constants. The enumeration
tool only handles the most common two cases, illustrated above.
Above, Month
is based on uint
; the base type does not have to be an int
; any integer or float base type can be used, for example
type Base float32
const (
// Nucleotide Molecular Weights, g/mol
A Base = 331.2
C Base = 307.2
G Base = 347.2
T Base = 322.2
)
There is one other restriction: the type declaration must be before the constants, as it does in all the examples above. White-space should be canonically formatted using gofmt
before using the tool (the results are unpredictable otherwise). (This is because of the limited parser used, for the reasons given earlier.)
Although the default behaviour is to generate strings for each enumeration value which match the constants you declared, you can take full control and override this with your own lookup table. The -using
argument needed:
//go:generate enumeration -type Day -using shortDayNames
type Day int
const (
Sunday Day = iota
Monday
Tuesday
Wednesday
Thursday
Friday
)
var shortDayNames = map[Day]string{
Sunday: "Su",
Monday: "Mo",
Tuesday: "Tu",
Wednesday: "We",
Thursday: "Th",
Friday: "Fr",
}
Just occasionally, you might have several enumerations in the same package and you need to avoid their identifiers clashing. This is easy to control using the -prefix
and -suffix
options. Here's an example using a suffix; prefixes are similar and you can have both if you want.
//go:generate enumeration -lc -type SalesChannel -suffix Sales
type SalesChannel int
const (
_ SalesChannel = iota
OnlineSales // represented as "online"
InstoreSales // represented as "instore"
TelephoneSales // represented as "telephone"
)
Next, Run The Tool
For example:
enumeration -i example/sample1.go -type Base -package example
Options are:
-
-type <name>
- the name of the primary Go type for which code generation is being used.
-
-plural <name>
- the plural equivalent for the name of the primary Go type. This is optional and the default is to use the type name and append letter 's', as is common for many English nouns. For example, with
-type Party
, you might usefully specify-plural Parties
.
- the plural equivalent for the name of the primary Go type. This is optional and the default is to use the type name and append letter 's', as is common for many English nouns. For example, with
-
-prefix <prefix>
- a prefix at the start of every identifier in the enumeration that is not included in the String representation.
-
-suffix <suffix>
- a suffix at the end of every identifier in the enumeration that is not included in the String representation.
-
-i <name>
or-input <name>
- the name of the input Go source file containing the
type
andconst
declarations.
- the name of the input Go source file containing the
-
-o <name>
or-output <name>
- the name of the output Go source file to be written. If omitted,
<type>_enum.go
is used.
- the name of the output Go source file to be written. If omitted,
-
-package <name>
- the name of the Go package. If omitted, the directory of the output file will be used if specified, or the current directory name otherwise.
-
-lc
- convert to lower case the string representations of the enumeration values.
-
-uc
- convert to upper case the string representations of the enumeration values.
-
-unsnake
- convert underscores in identifiers to spaces (e.g.
Hello_world
becomes "Hello world")
- convert underscores in identifiers to spaces (e.g.
-
-using <map-name>
- bring your own lookup table: you declare a
var <map-name> = map[Type]string{ ... }
that gives the required string representations. This gives you full control, if you need it. TheTag()
method returns these strings, whilst theString()
method returns the identifier as a string.
- bring your own lookup table: you declare a
-
-f
- force output generation; if this is not set, the output file is only produced when it is is absent or when it is older than the input file.
-
-v
- verbose info messages
-
-version
- print the version and exit.
The option parser will also infer the source and output file names, so it is also permitted to use
enumeration -type Base
when this matches your needs. This example would try to read from base.go
and write to base_enum.go
.
Generated Go
The generated code complements your type
and const
definitions as follows. Let's assume that you wrote
the Day
type above. You will get:
-
func (d Day) String() string
- Converts Day values to strings and satisfies the well-known
Stringer
interface. The strings are the human-readable names, as written in the list of constants.
- Converts Day values to strings and satisfies the well-known
-
func (d Day) Tag() string
- Returns the same as
String()
by default, but if you provide tags via-using
it returns the corresponding tag instead.
- Returns the same as
-
func (d Day) Ordinal() int
- Converts Day values into their ordinal numbers, i.e. the indexes indicating the order in which you declared the constants, starting from zero. These may happen to be the same as the values you chose, but need not be.
-
func DayOf(o int) Day
- Converts an ordinal to a Day value, if it can. The name of this function depends on the name of your type (
DayOf
in this example). The related type conversionDay(i)
should be used when converting a value instead of an ordinal.
- Converts an ordinal to a Day value, if it can. The name of this function depends on the name of your type (
-
func (d Day) IsValid() bool
- Tests whether a given value is one of the defined
Day
constants. Type conversion allows possibly out-of range values to be created; these can be tested with this method.
- Tests whether a given value is one of the defined
-
func (d Day) Int() int
- Converts Day values into their int values, i.e. just the value of the constant int. This is merely a type conversion to
int
, but conveniently matches theenum.IntEnum
interface, allowing polymorphism. This method is only present when the base type is any integer type.
- Converts Day values into their int values, i.e. just the value of the constant int. This is merely a type conversion to
-
func (d Day) Float() float64
- Converts Day values into their float values, i.e. just the value of the constant float. This is merely a type conversion to
float64
, but conveniently matches theenum.FloatEnum
interface, allowing polymorphism. This method is only present when the base type isfloat32
orfloat64
.
- Converts Day values into their float values, i.e. just the value of the constant float. This is merely a type conversion to
-
func (d *Day) Parse(s string) error
- Converts a string representation to a Day value, if it can, then assigns it to
d
. Ifs
holds an integer, it is treated as an ordinal or number and will result in the corresponding value (unexported fields control this in detail - you can initialise these as you need).
- Converts a string representation to a Day value, if it can, then assigns it to
-
func AsDay(s string) (Day, error)
- Converts a string representation to a Day value, if it can. The name of this function depends on the name of your type (
AsDay
in this example).
- Converts a string representation to a Day value, if it can. The name of this function depends on the name of your type (
-
var AllDays = []Day{ ... }
- Provides all the
Day
values in a single slice. This is particularly useful if you need to iterate over them. Usually, the identifier name depends on the name of your type, but it can be overridden using-plural
.
- Provides all the
-
var AllDayEnums = enum.IntEnums{ ... }
- Provides all the
Day
values in a single slice, held using an interface for polymorphism. The slice type would instead beenum.FloatEnums
if the base type isfloat32
orfloat64
.
- Provides all the
-
var dayMarshalTextRep = enum.Identifier
- Controls whether marshalling to JSON represents the values as the identifier (default), or as the tag, the number or the ordinal.
-
var dayStoreRep = enum.Identifier
- Controls whether writes to a database will use the identifier (default), or as the tag, the number or the ordinal.
-
encoding.TextMarshaler
,encoding.TextUnmarshaler
,json.Marshaler
,json.Unmarshaler
- Provides methods to satisfy these interfaces so that your enumeration can be easily used by JSON, XML and other codecs in the standard Go library. Writes depend on
dayMarshalTextRep
.
- Provides methods to satisfy these interfaces so that your enumeration can be easily used by JSON, XML and other codecs in the standard Go library. Writes depend on
-
sql.Scanner
,driver.Valuer
- Provides methods to satisfy these two interfaces so that your enumeration can be easily used by SQL drivers in the standard Go library. Note that
driver.Valuer
is provided as a template for you to copy if you need it; otherwise the SQL driver will automatically make use of the numeric values of enumerations. Writes depend ondayStoreRep
.
- Provides methods to satisfy these two interfaces so that your enumeration can be easily used by SQL drivers in the standard Go library. Note that
Other Use Options
This tool is compatible with go generate
- more. However, go generate
may not always work if the code is still incomplete and doesn't yet compile, in which case you can try just running enumeration
directly on the command line.
Credits
Thanks are due to others for their earlier work. Notable is the earlier stringer here by Rob Pike or a related alterative here by Matt Sherman.
Documentation ¶
There is no documentation for this package.