codecgen

README

codecgen tool

Generate is given a list of *.go files to parse, and an output file (fout), codecgen will create an output file file.go which contains codec.Selfer implementations for the named types found in the files parsed.

Using codecgen is very straightforward.

Download and install the tool

go get -u github.com/ugorji/go/codec/codecgen

Run the tool on your files

The command line format is:

codecgen [options] (-o outfile) (infile ...)

% codecgen -?
Usage of codecgen:
  -c="github.com/ugorji/go/codec": codec path
  -o="": out file
  -d="": random identifier for use in generated code (help reduce changes when files are regenerated)
  -nx=false: do not support extensions (use when you know no extensions are used)
  -r=".*": regex for type name to match
  -nr="": regex for type name to exclude
  -rt="": tags for go run
  -st="codec,json": struct tag keys to introspect
  -t="": build tag to put in file
  -u=false: Use unsafe, e.g. to avoid unnecessary allocation on []byte->string
  -x=false: keep temp file

% codecgen -o values_codecgen.go values.go values2.go moretypedefs.go

Limitations

codecgen caveats:

• Canonical option.
  If Canonical=true, codecgen'ed code will delegate encoding maps to reflection-based code.
  This is due to the runtime work needed to marshal a map in canonical mode.
• CheckCircularRef option.
  When encoding a struct, a circular reference can lead to a stack overflow.
  If CheckCircularRef=true, codecgen'ed code will delegate encoding structs to reflection-based code.
• MissingFielder implementation.
  If a type implements MissingFielder, a Selfer is not generated (with a warning message). Statically reproducing the runtime work needed to extract the missing fields and marshal them along with the struct fields, while handling the Canonical=true special case, was onerous to implement.

More Information

Please see the blog article for more information on how to use the tool.

Documentation

Overview

codecgen generates static implementations of the encoder and decoder functions for a given type, bypassing reflection, and giving some performance benefits in terms of wall and cpu time, and memory usage.

Benchmarks (as of Dec 2018) show that codecgen gives about

• for binary formats (cbor, etc): 25% on encoding and 30% on decoding to/from []byte
• for text formats (json, etc): 15% on encoding and 25% on decoding to/from []byte

Note that (as of Dec 2018) codecgen completely ignores

• MissingFielder interface (if you types implements it, codecgen ignores that)
• decode option PreferArrayOverSlice (we cannot dynamically create non-static arrays without reflection)

In explicit package terms: codecgen generates codec.Selfer implementations for a set of types.