forked from mirror/enumer
Add docs
This commit is contained in:
Alvaro Lopez Espinosa
parent
13c6b5bfe2
commit
a7e0f72c42
167
stringer.go
167
stringer.go
|
|
@ -4,64 +4,147 @@
|
||||||
|
|
||||||
// +build go1.5
|
// +build go1.5
|
||||||
|
|
||||||
// Stringer is a tool to automate the creation of methods that satisfy the fmt.Stringer
|
//# Enumer [](https://goreportcard.com/report/github.com/alvaroloes/enumer) 
|
||||||
// interface. Given the name of a (signed or unsigned) integer type T that has constants
|
//Enumer is a tool to generate Go code that adds useful methods to Go enums (constants with a specific type).
|
||||||
// defined, stringer will create a new self-contained Go source file implementing
|
//It started as a fork of [Rob Pike’s Stringer tool](https://godoc.org/golang.org/x/tools/cmd/stringer).
|
||||||
// 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.
|
|
||||||
//
|
//
|
||||||
// Stringer works best with constants that are consecutive values such as created using iota,
|
//## Generated functions and methods
|
||||||
// but creates good code regardless. In the future it might also provide custom support for
|
//When Enumer is applied to a type, it will generate:
|
||||||
// constant sets that are bit patterns.
|
|
||||||
//
|
//
|
||||||
// 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 `<Type>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 `<Type>Values()`: returns a slice with all the values of the enum
|
||||||
|
//* Method `IsA<Type>()`: 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 (
|
//const (
|
||||||
// Placebo Pill = iota
|
// Placebo Pill = iota
|
||||||
// Aspirin
|
// Aspirin
|
||||||
// Ibuprofen
|
// Ibuprofen
|
||||||
// Paracetamol
|
// Paracetamol
|
||||||
// Acetaminophen = 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,
|
//func (i Pill) IsAPill() bool {
|
||||||
// containing a definition of
|
// //...
|
||||||
|
//}
|
||||||
//
|
//
|
||||||
// func (Pill) String() string
|
//func (i Pill) MarshalJSON() ([]byte, error) {
|
||||||
|
// //...
|
||||||
|
//}
|
||||||
//
|
//
|
||||||
// That method will translate the value of a Pill constant to the string representation
|
//func (i *Pill) UnmarshalJSON(data []byte) error {
|
||||||
// of the respective constant name, so that the call fmt.Print(painkiller.Aspirin) will
|
// //...
|
||||||
// print the string "Aspirin".
|
//}
|
||||||
|
//```
|
||||||
|
//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
|
//// Check if a value belongs to the Pill enum values
|
||||||
// be used (in the example, Acetaminophen will print as "Paracetamol").
|
//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.
|
//// Marshal/unmarshal to/from json strings, either directly or automatically when
|
||||||
// Otherwise, the arguments must name a single directory holding a Go package
|
//// the enum is a field of a struct
|
||||||
// or a set of Go source files that represent a single Go package.
|
//pillJSON := Aspirin.MarshalJSON()
|
||||||
|
//// Now pillJSON == `"Aspirin"`
|
||||||
|
//```
|
||||||
//
|
//
|
||||||
// The -type flag accepts a comma-separated list of types so a single run can
|
//The generated code is exactly the same as the Stringer tool plus the mentioned additions, so you can use
|
||||||
// generate methods for multiple types. The default output file is t_string.go,
|
//**Enumer** where you are already using **Stringer** without any code change.
|
||||||
// where t is the lower-cased name of the first type listed. It can be overridden
|
|
||||||
// with the -output flag.
|
|
||||||
//
|
//
|
||||||
// ------
|
//## Transforming the string representation of the enum value
|
||||||
// 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
|
//By default, Enumer uses the same name of the enum value for generating the string representation (usually CamelCase in Go).
|
||||||
// golint warnings. The patched version simply leaves the '_' out
|
//
|
||||||
|
//```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
|
package main
|
||||||
|
|
||||||
import (
|
import (
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue