github.com/glycerine/zebrapack@v4.1.1-0.20181107023619-e955d028f9bf+incompatible/zebra/zebra.go

/*
package zebra specifies the ZebraPack serialization format.
Instead of an IDL file, the ZebraPack schema is described
using the same Go source file that holds the Go structs
you wish to serialize. The Go file schema is then compiled
by running `zebrapack` into msgpack2 (with optional JSON)
in a format we'll call `compiled-schema` format. If
one is not starting in Go, simply write a standalone Go
file that describes your types. See the examples
in `../testdata/my.go`.

The `compiled-schema` is thus type checked upon generation,
and other languages need not parse Go (only msgpack2
or JSON) in order the read and use the compiled
schema to undertand the types on the wire. The
types below desribe those found in
the compiled ZebraPack schema files.

The methods that you see below in the godoc are
the autogenerated methods from running
`zebrapack -msg -file zebra.go` on this file itself.
They provide an API for reading and writing
compiled ZebraPack schema.
*/
package zebra

// in the generate command, we use -msgp so that
// we serialize the ZebraPack schema itself
// as simple msgpack2, rather than in ZebraPack format.

//go:generate zebrapack -msgp

const zebraSchemaId64 = 0x1a5a94bd49624

// Zkind describes the detailed type of the field.
// Since it also stores the fixed size of a array type,
// it needs to be large. When serialized as msgpack2,
// it will be compressed.
//
// Implentation note: primitives must correspond
// to gen/Primitive, as we will cast/convert them directly.
//
type Zkind uint64

const (

	// primitives.
	// Implementation note: must correspond to gen/Primitive.
	Invalid    Zkind = 0
	Bytes      Zkind = 1 // []byte
	String     Zkind = 2
	Float32    Zkind = 3
	Float64    Zkind = 4
	Complex64  Zkind = 5
	Complex128 Zkind = 6
	Uint       Zkind = 7 // 32 or 64 bit; as in Go, matches native word
	Uint8      Zkind = 8
	Uint16     Zkind = 9
	Uint32     Zkind = 10
	Uint64     Zkind = 11
	Byte       Zkind = 12
	Int        Zkind = 13 // as in Go, matches native word size.
	Int8       Zkind = 14
	Int16      Zkind = 15
	Int32      Zkind = 16
	Int64      Zkind = 17
	Bool       Zkind = 18
	Intf       Zkind = 19 // interface{}, the empty interface.
	Time       Zkind = 20 // time.Time
	Ext        Zkind = 21 // extension

	// IDENT means an unrecognized identifier;
	// it typically means a named struct type.
	// The Str field in the Ztype will hold the
	// name of the struct.
	IDENT Zkind = 22

	// compound types
	// implementation note: should correspond to gen/Elem.
	BaseElemCat Zkind = 23
	MapCat      Zkind = 24
	StructCat   Zkind = 25
	SliceCat    Zkind = 26
	ArrayCat    Zkind = 27
	PointerCat  Zkind = 28

	IDENTiface Zkind = 29 // an identifier that is an inteface (known b/c of struct tag 'iface')
)

// Ztype describes any type, be it a BaseElem,
// Map, Struct, Slice, Array, or Pointer.
type Ztype struct {

	// Kind gives the exact type for primitives,
	// and the category for compound types.
	Kind Zkind `zid:"0"`

	// Str holds the struct name when Kind == 22 (IDENT) or 29 (IDENTiface).
	// Otherwise it typically reflects Kind directly
	// which is useful for human readability.
	Str string `msg:",omitempty" zid:"1"`

	// Domain holds the key type for maps. For
	// pointers and slices it holds the element type.
	// For arrays, it holds the fixed size.
	// Domain is null when Kind is a primitive.
	Domain *Ztype `msg:",omitempty" zid:"2"`

	// Range holds the value type for maps.
	// For arrays (always a fixed size), Range holds
	// the element type.  Otherwise Range is
	// typically null.
	Range *Ztype `msg:",omitempty" zid:"3"`
}

// Schema is the top level container in ZebraPack.
// It all starts here.
type Schema struct {

	// SourcePath gives the path to the original Go
	// source file that was parsed to produce this
	// compiled schema.
	SourcePath string `msg:",omitempty" zid:"0"`

	// SourcePackage notes the original package presented
	// by the SourcePath file.
	SourcePackage string `msg:",omitempty" zid:"1"`

	// ZebraSchemaId is a randomly chosen but stable
	// 53-bit positive integer identifier (see
	// zebrapack -genid) that can be used to distinguish schemas.
	ZebraSchemaId int64 `msg:",omitempty" zid:"2"`

	// Structs holds the collection of the main data
	// descriptor, the Struct. The key is identical
	// to Struct.StructName.
	//
	// This a map rather than a slice in order to:
	// a) insure there are no duplicate struct names; and
	// b) make decoding easy and fast.
	Structs map[string]*Struct `msg:",omitempty" zid:"3"`

	// Imports archives the imports in the SourcePath
	// to make it possible to understand other package
	// type references.
	Imports []string `msg:",omitempty" zid:"4"`
}

// Struct represents a single message or struct.
type Struct struct {
	// StructName is the typename of the struct in Go.
	StructName string `msg:",omitempty" zid:"0"`

	// Fields hold the individual Field descriptors.
	Fields []Field `msg:",omitempty" zid:"1"`
}

// Field represents fields within a struct.
type Field struct {

	// Zid is the zebrapack id.
	//
	// Zid numbering detects update collisions
	// when two developers simultaneously add two
	// new fields. Zid numbering allows sane
	// forward/backward data evolution, like protobufs
	// and Cap'nProto.
	//
	// Zid follows Cap'nProto numbering semantics:
	// start at numbering at 0, and strictly/always
	// increase numbers monotically.
	//
	// No gaps and no duplicate Zid are allowed.
	//
	// Duplicate numbers are how collisions (between two
	// developers adding two distinct new fields independently
	// but at the same time) are detected.
	//
	// Therefore this ironclad rule: never delete a field or Zid number,
	// just mark it as deprecated with the `deprecated:"true"`
	// tag. Change its Go type to struct{} as soon as
	// possible so that it becomes skipped; then the Go
	// compiler can help you detect and prevent unwanted use.
	//
	Zid int64 `zid:"0"`

	// the name of the field in the Go schema/source file.
	FieldGoName string `zid:"1"`

	// optional wire-name designated by a
	// `msg:"tagname"` tag on the struct field.
	FieldTagName string `msg:",omitempty" zid:"2"`

	// =======================
	// type info
	// =======================

	// human readable/Go type description
	FieldTypeStr string `msg:",omitempty" zid:"3"`

	// the broad category of this type. empty if Skip is true
	FieldCategory Zkind `msg:",omitempty" zid:"4"`

	// avail if FieldCategory == BaseElemCat
	FieldPrimitive Zkind `msg:",omitempty" zid:"5"`

	// the machine-parse-able type tree
	FieldFullType *Ztype `msg:",omitempty" zid:"6"`

	// =======================
	// field tag details:
	// =======================

	// if OmitEmpty then we don't serialize
	// the field if it has its zero-value.
	OmitEmpty bool `msg:",omitempty" zid:"7"`

	// Skip means either type struct{} or
	// other unserializable type;
	// or marked  as `msg:"-"`. In any case,
	// if Skip is true: do not serialize
	// this field when writing, and ignore it
	// when reading.
	Skip bool `msg:",omitempty" zid:"8"`

	// Deprecated means tagged with `deprecated:"true"`,
	// or `msg:",deprecated"`.
	// Compilers/libraries should discourage and warn
	// users away from writing to such fields, while
	// not making it impossible to either read or write
	// the field.
	Deprecated bool `msg:",omitempty" zid:"9"`

	// ShowZero means display the field even if
	// it has the zero value. Showzero has no impact
	// on what is transmitted on the wire. Zero
	// valued fields are never transmitted.
	ShowZero bool `msg:",omitempty" zid:"10"`
}