jsonenums/README.md

78 lines
2.4 KiB
Markdown
Raw Normal View History

2015-01-29 00:18:46 +01:00
# jsonenums
2015-01-29 11:35:15 +01:00
2015-01-31 12:23:24 +01:00
jsonenums is a tool to automate the creation of methods that satisfy the
2015-02-01 09:37:31 +01:00
`json.Marshaler` and `json.Unmarshaler` interfaces.
2015-01-29 11:35:15 +01:00
Given the name of a (signed or unsigned) integer type T that has constants
2015-02-01 09:37:31 +01:00
defined, jsonenums will create a new self-contained Go source file implementing
2015-01-29 11:35:15 +01:00
```
func (t T) MarshalJSON() ([]byte, error)
func (t *T) UnmarshalJSON([]byte) error
2015-01-29 11:35:15 +01:00
```
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.
2015-01-31 12:23:24 +01:00
jsonenums is a simple implementation of a concept and the code might not be the
2015-01-29 11:35:15 +01:00
most performant or beautiful to read.
For example, given this snippet,
```Go
package painkiller
2015-01-29 11:35:15 +01:00
type Pill int
2015-01-29 11:35:15 +01:00
const (
Placebo Pill = iota
Aspirin
Ibuprofen
Paracetamol
Acetaminophen = Paracetamol
)
2015-01-29 11:35:15 +01:00
```
running this command
```
jsonenums -type=Pill
2015-01-29 11:35:15 +01:00
```
in the same directory will create the file `pill_jsonenums.go`, in package
`painkiller`, containing a definition of
```
func (r Pill) MarshalJSON() ([]byte, error)
func (r *Pill) UnmarshalJSON([]byte) error
2015-01-29 11:35:15 +01:00
```
2015-02-01 09:37:31 +01:00
`MarshalJSON` will translate the value of a `Pill` constant to the `[]byte`
2015-01-29 11:35:15 +01:00
representation of the respective constant name, so that the call
`json.Marshal(painkiller.Aspirin)` will return the bytes `[]byte("\"Aspirin\"")`.
2015-02-01 09:37:31 +01:00
`UnmarshalJSON` performs the opposite operation; given the `[]byte`
representation of a `Pill` constant it will change the receiver to equal the
corresponding constant. So given `[]byte("\"Aspirin\"")` the receiver will
change to `Aspirin` and the returned error will be `nil`.
2015-01-29 11:35:15 +01:00
Typically this process would be run using go generate, like this:
```
//go:generate jsonenums -type=Pill
2015-01-29 11:35:15 +01:00
```
If multiple constants have the same value, the lexically first matching name
will be used (in the example, Acetaminophen will print as "Paracetamol").
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.
The `-type` flag accepts a comma-separated list of types so a single run can
2015-02-01 09:37:31 +01:00
generate methods for multiple types. The default output file is t_jsonenums.go,
where t is the lower-cased name of the first type listed. The suffix can be
overridden with the `-suffix` flag and a prefix may be added with the `-prefix`
flag.
2015-02-01 16:05:25 +01:00
This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.