diff --git a/stringer.go b/stringer.go index dcd29f6..0a6717b 100644 --- a/stringer.go +++ b/stringer.go @@ -4,64 +4,147 @@ // +build go1.5 -// Stringer is a tool to automate the creation of methods that satisfy the fmt.Stringer -// interface. Given the name of a (signed or unsigned) integer type T that has constants -// defined, stringer will create a new self-contained Go source file implementing -// func (t T) String() string -// The file is created in the same package and directory as the package that defines T. -// It has helpful defaults designed for use with go generate. +//# Enumer [![Go Report Card](https://goreportcard.com/badge/github.com/alvaroloes/enumer)](https://goreportcard.com/report/github.com/alvaroloes/enumer) ![cover.run go](https://cover.run/go/github.com/alvaroloes/enumer.svg?tag=golang-1.10) +//Enumer is a tool to generate Go code that adds useful methods to Go enums (constants with a specific type). +//It started as a fork of [Rob Pike’s Stringer tool](https://godoc.org/golang.org/x/tools/cmd/stringer). // -// Stringer works best with constants that are consecutive values such as created using iota, -// but creates good code regardless. In the future it might also provide custom support for -// constant sets that are bit patterns. +//## Generated functions and methods +//When Enumer is applied to a type, it will generate: // -// For example, given this snippet, +//* The following basic methods/functions: // -// package painkiller +//* Method `String()`: returns the string representation of the enum value. This makes the enum conform +//the `Stringer` interface, so whenever you print an enum value, you'll get the string name instead of a number. +//* Function `String(s string)`: returns the enum value from its string representation. This is useful +//when you need to read enum values from command line arguments, from a configuration file, or +//from a REST API request... In short, from those places where using the real enum value (an integer) would +//be almost meaningless or hard to trace or use by a human. +//* Function `Values()`: returns a slice with all the values of the enum +//* Method `IsA()`: returns true only if the current value is among the values of the enum. Useful for validations. +//* When the flag `json` is provided, two additional methods will be generated, `MarshalJSON()` and `UnmarshalJSON()`. These make +//the enum conform to the `json.Marshaler` and `json.Unmarshaler` interfaces. Very useful to use it in JSON APIs. +//* When the flag `text` is provided, two additional methods will be generated, `MarshalText()` and `UnmarshalText()`. These make +//the enum conform to the `encoding.TextMarshaler` and `encoding.TextUnmarshaler` interfaces. +//**Note:** If you use your enum values as keys in a map and you encode the map as _JSON_, you need this flag set to true to properly +//convert the map keys to json (strings). If not, the numeric values will be used instead +//* When the flag `yaml` is provided, two additional methods will be generated, `MarshalYAML()` and `UnmarshalYAML()`. These make +//the enum conform to the `gopkg.in/yaml.v2.Marshaler` and `gopkg.in/yaml.v2.Unmarshaler` interfaces. +//* When the flag `sql` is provided, the methods for implementing the Scanner and Valuer interfaces will be also generated. +//Useful when storing the enum in a database. // -// type Pill int +//For example, if we have an enum type called `Pill`, +//```go +//type Pill int // -// const ( -// Placebo Pill = iota -// Aspirin -// Ibuprofen -// Paracetamol -// Acetaminophen = Paracetamol -// ) +//const ( +// Placebo Pill = iota +// Aspirin +// Ibuprofen +// Paracetamol +// Acetaminophen = Paracetamol +//) +//``` +//executing `enumer -type=Pill -json` will generate a new file with four basic method and two extra for JSON: +//```go +//func (i Pill) String() string { +// //... +//} // -// running this command +//func PillString(s string) (Pill, error) { +// //... +//} // -// stringer -type=Pill +//func PillValues() []Pill { +// //... +//} // -// in the same directory will create the file pill_string.go, in package painkiller, -// containing a definition of +//func (i Pill) IsAPill() bool { +// //... +//} // -// func (Pill) String() string +//func (i Pill) MarshalJSON() ([]byte, error) { +// //... +//} // -// That method will translate the value of a Pill constant to the string representation -// of the respective constant name, so that the call fmt.Print(painkiller.Aspirin) will -// print the string "Aspirin". +//func (i *Pill) UnmarshalJSON(data []byte) error { +// //... +//} +//``` +//From now on, we can: +//```go +//// Convert any Pill value to string +//var aspirinString string = Aspirin.String() +//// (or use it in any place where a Stringer is accepted) +//fmt.Println("I need ", Paracetamol) // Will print "I need Paracetamol" // -// Typically this process would be run using go generate, like this: +//// Convert a string with the enum name to the corresponding enum value +//pill, err := PillString("Ibuprofen") +//if err != nil { +// fmt.Println("Unrecognized pill: ", err) +// return +//} +//// Now pill == Ibuprofen // -// //go:generate stringer -type=Pill +//// Get all the values of the string +//allPills := PillValues() +//fmt.Println(allPills) // Will print [Placebo Aspirin Ibuprofen Paracetamol] // -// If multiple constants have the same value, the lexically first matching name will -// be used (in the example, Acetaminophen will print as "Paracetamol"). +//// Check if a value belongs to the Pill enum values +//var notAPill Pill = 42 +//if (notAPill.IsAPill()) { +// fmt.Println(notAPill, "is not a value of the Pill enum") +//} // -// With no arguments, it processes the package in the current directory. -// Otherwise, the arguments must name a single directory holding a Go package -// or a set of Go source files that represent a single Go package. +//// Marshal/unmarshal to/from json strings, either directly or automatically when +//// the enum is a field of a struct +//pillJSON := Aspirin.MarshalJSON() +//// Now pillJSON == `"Aspirin"` +//``` // -// The -type flag accepts a comma-separated list of types so a single run can -// generate methods for multiple types. The default output file is t_string.go, -// where t is the lower-cased name of the first type listed. It can be overridden -// with the -output flag. +//The generated code is exactly the same as the Stringer tool plus the mentioned additions, so you can use +//**Enumer** where you are already using **Stringer** without any code change. // -// ------ -// This is a patched versin of the original stringer. The original generates source code -// using '_' (underscore) as part of generated golang identifiers. This creates a number of -// golint warnings. The patched version simply leaves the '_' out +//## Transforming the string representation of the enum value +// +//By default, Enumer uses the same name of the enum value for generating the string representation (usually CamelCase in Go). +// +//```go +//type MyType int +// +// ... +// +//name := MyTypeValue.String() // name => "MyTypeValue" +//``` +// +//Sometimes you need to use some other string representation format than CamelCase (i.e. in JSON). +// +//To transform it from CamelCase to snake_case or kebab-case, you can use the `transform` flag. +// +//For example, the command `enumer -type=MyType -json -transform=snake` would generate the following string representation: +// +//```go +//name := MyTypeValue.String() // name => "my_type_value" +//``` +//**Note**: The transformation only works form CamelCase to snake_case or kebab-case, not the other way around. +// +//## How to use +//The usage of Enumer is the same as Stringer, so you can refer to the [Stringer docs](https://godoc.org/golang.org/x/tools/cmd/stringer) +//for more information. +// +//There are four boolean flags: `json`, `text`, `yaml` and `sql`. You can use any combination of them (i.e. `enumer -type=Pill -json -text`), +// +// +//For enum string representation transformation the `transform` and `trimprefix` flags +//were added (i.e. `enumer -type=MyType -json -transform=snake`). +//Possible transform values are `snake` and `kebab` for transformation to snake_case and kebab-case accordingly. +//The default value for `transform` flag is `noop` which means no transformation will be performed. +// +//If a prefix is provided via the `trimprefix` flag, it will be trimmed from the start of each name (before +//it is transformed). If a name doesn't have the prefix it will be passed unchanged. +// +//## Inspiring projects +//* [Stringer](https://godoc.org/golang.org/x/tools/cmd/stringer) +//* [jsonenums](https://github.com/campoy/jsonenums) package main import (