zebra

package
v4.1.1-0...-e955d02 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 7, 2018 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

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.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoStructNameFound = fmt.Errorf("error: no -1:struct-name field:value found in zebrapack struct")

ErrNoStructNameFound is returned by ZebraToMsgp2 when it cannot locate the embedded struct name string.

Functions

This section is empty.

Types

type Field 

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"`

	// 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"`

	// 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"`
}

Field represents fields within a struct.

func (*Field) DecodeMsg 

func (z *Field) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (*Field) EncodeMsg 

func (z *Field) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Field) MarshalMsg 

func (z *Field) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Field) Msgsize 

func (z *Field) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Field) UnmarshalMsg 

func (z *Field) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

func (*Field) UnmarshalMsgWithCfg 

func (z *Field) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Field) ZebraDecodeMsg 

func (z *Field) ZebraDecodeMsg(dc *msgp.Reader) (err error)

ZebraDecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (*Field) ZebraEncodeMsg 

func (z *Field) ZebraEncodeMsg(en *msgp.Writer) (err error)

ZebraEncodeMsg implements msgp.Encodable

func (*Field) ZebraMarshalMsg 

func (z *Field) ZebraMarshalMsg(b []byte) (o []byte, err error)

ZebraMarshalMsg implements msgp.Marshaler

func (*Field) ZebraMsgsize 

func (z *Field) ZebraMsgsize() (s int)

ZebraMsgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Field) ZebraUnmarshalMsg 

func (z *Field) ZebraUnmarshalMsg(bts []byte) (o []byte, err error)

ZebraUnmarshalMsg implements msgp.Unmarshaler

func (*Field) ZebraUnmarshalMsgWithCfg 

func (z *Field) ZebraUnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Field) ZebrafieldsNotEmpty 

func (z *Field) ZebrafieldsNotEmpty(isempty []bool) uint32

ZebrafieldsNotEmpty supports omitempty tags

type FileZebra_zebra_go 

type FileZebra_zebra_go struct{}

FileZebra_zebra_go holds ZebraPack schema from file 'zebra/zebra.go'

func (FileZebra_zebra_go) ZebraZebraSchemaInJsonCompact 

func (FileZebra_zebra_go) ZebraZebraSchemaInJsonCompact() []byte

ZebraZebraSchemaInJsonCompact provides the ZebraPack Schema in compact JSON format, length 4441 bytes

func (FileZebra_zebra_go) ZebraZebraSchemaInJsonPretty 

func (FileZebra_zebra_go) ZebraZebraSchemaInJsonPretty() []byte

ZebraZebraSchemaInJsonPretty provides the ZebraPack Schema in pretty JSON format, length 11643 bytes

func (FileZebra_zebra_go) ZebraZebraSchemaInMsgpack2Format 

func (FileZebra_zebra_go) ZebraZebraSchemaInMsgpack2Format() []byte

ZebraZebraSchemaInMsgpack2Format provides the ZebraPack Schema in msgpack2 format, length 3448 bytes

type Schema 

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"`
}

Schema is the top level container in ZebraPack. It all starts here.

func (*Schema) DecodeMsg 

func (z *Schema) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (*Schema) EncodeMsg 

func (z *Schema) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Schema) MarshalMsg 

func (z *Schema) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Schema) Msgsize 

func (z *Schema) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Schema) UnmarshalMsg 

func (z *Schema) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

func (*Schema) UnmarshalMsgWithCfg 

func (z *Schema) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Schema) WriteToGo 

func (s *Schema) WriteToGo(w io.Writer, path string, pkg string) (err error)

WriteToGo writes the zebrapack schema to w as a Go source file.

func (*Schema) ZebraDecodeMsg 

func (z *Schema) ZebraDecodeMsg(dc *msgp.Reader) (err error)

ZebraDecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (*Schema) ZebraEncodeMsg 

func (z *Schema) ZebraEncodeMsg(en *msgp.Writer) (err error)

ZebraEncodeMsg implements msgp.Encodable

func (*Schema) ZebraMarshalMsg 

func (z *Schema) ZebraMarshalMsg(b []byte) (o []byte, err error)

ZebraMarshalMsg implements msgp.Marshaler

func (*Schema) ZebraMsgsize 

func (z *Schema) ZebraMsgsize() (s int)

ZebraMsgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Schema) ZebraToMsgp2 

func (sch *Schema) ZebraToMsgp2(bts []byte, ignoreMissingStructName bool) (out []byte, left []byte, err error)

func (*Schema) ZebraUnmarshalMsg 

func (z *Schema) ZebraUnmarshalMsg(bts []byte) (o []byte, err error)

ZebraUnmarshalMsg implements msgp.Unmarshaler

func (*Schema) ZebraUnmarshalMsgWithCfg 

func (z *Schema) ZebraUnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Schema) ZebrafieldsNotEmpty 

func (z *Schema) ZebrafieldsNotEmpty(isempty []bool) uint32

ZebrafieldsNotEmpty supports omitempty tags

type 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"`
}

Struct represents a single message or struct.

func (*Struct) DecodeMsg 

func (z *Struct) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (*Struct) EncodeMsg 

func (z *Struct) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Struct) MarshalMsg 

func (z *Struct) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Struct) Msgsize 

func (z *Struct) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Struct) UnmarshalMsg 

func (z *Struct) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

func (*Struct) UnmarshalMsgWithCfg 

func (z *Struct) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Struct) WriteToGo 

func (s *Struct) WriteToGo(w io.Writer) (err error)

func (*Struct) ZebraDecodeMsg 

func (z *Struct) ZebraDecodeMsg(dc *msgp.Reader) (err error)

ZebraDecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (*Struct) ZebraEncodeMsg 

func (z *Struct) ZebraEncodeMsg(en *msgp.Writer) (err error)

ZebraEncodeMsg implements msgp.Encodable

func (*Struct) ZebraMarshalMsg 

func (z *Struct) ZebraMarshalMsg(b []byte) (o []byte, err error)

ZebraMarshalMsg implements msgp.Marshaler

func (*Struct) ZebraMsgsize 

func (z *Struct) ZebraMsgsize() (s int)

ZebraMsgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Struct) ZebraUnmarshalMsg 

func (z *Struct) ZebraUnmarshalMsg(bts []byte) (o []byte, err error)

ZebraUnmarshalMsg implements msgp.Unmarshaler

func (*Struct) ZebraUnmarshalMsgWithCfg 

func (z *Struct) ZebraUnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Struct) ZebrafieldsNotEmpty 

func (z *Struct) ZebrafieldsNotEmpty(isempty []bool) uint32

ZebrafieldsNotEmpty supports omitempty tags

type Zkind 

type Zkind uint64

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. 

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')
)

func ZkindFromString 

func ZkindFromString(s string) Zkind

func (*Zkind) DecodeMsg 

func (z *Zkind) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (Zkind) EncodeMsg 

func (z Zkind) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (Zkind) MarshalMsg 

func (z Zkind) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (Zkind) Msgsize 

func (z Zkind) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (Zkind) String 

func (i Zkind) String() string

func (*Zkind) UnmarshalMsg 

func (z *Zkind) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

func (*Zkind) UnmarshalMsgWithCfg 

func (z *Zkind) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Zkind) ZebraDecodeMsg 

func (z *Zkind) ZebraDecodeMsg(dc *msgp.Reader) (err error)

ZebraDecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (Zkind) ZebraEncodeMsg 

func (z Zkind) ZebraEncodeMsg(en *msgp.Writer) (err error)

ZebraEncodeMsg implements msgp.Encodable

func (Zkind) ZebraMarshalMsg 

func (z Zkind) ZebraMarshalMsg(b []byte) (o []byte, err error)

ZebraMarshalMsg implements msgp.Marshaler

func (Zkind) ZebraMsgsize 

func (z Zkind) ZebraMsgsize() (s int)

ZebraMsgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Zkind) ZebraUnmarshalMsg 

func (z *Zkind) ZebraUnmarshalMsg(bts []byte) (o []byte, err error)

ZebraUnmarshalMsg implements msgp.Unmarshaler

func (*Zkind) ZebraUnmarshalMsgWithCfg 

func (z *Zkind) ZebraUnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

type Ztype 

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"`
}

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

func (*Ztype) DecodeMsg 

func (z *Ztype) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (*Ztype) EncodeMsg 

func (z *Ztype) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Ztype) MarshalMsg 

func (z *Ztype) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*Ztype) Msgsize 

func (z *Ztype) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Ztype) UnmarshalMsg 

func (z *Ztype) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

func (*Ztype) UnmarshalMsgWithCfg 

func (z *Ztype) UnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Ztype) ZebraDecodeMsg 

func (z *Ztype) ZebraDecodeMsg(dc *msgp.Reader) (err error)

ZebraDecodeMsg implements msgp.Decodable We treat empty fields as if we read a Nil from the wire.

func (*Ztype) ZebraEncodeMsg 

func (z *Ztype) ZebraEncodeMsg(en *msgp.Writer) (err error)

ZebraEncodeMsg implements msgp.Encodable

func (*Ztype) ZebraMarshalMsg 

func (z *Ztype) ZebraMarshalMsg(b []byte) (o []byte, err error)

ZebraMarshalMsg implements msgp.Marshaler

func (*Ztype) ZebraMsgsize 

func (z *Ztype) ZebraMsgsize() (s int)

ZebraMsgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Ztype) ZebraUnmarshalMsg 

func (z *Ztype) ZebraUnmarshalMsg(bts []byte) (o []byte, err error)

ZebraUnmarshalMsg implements msgp.Unmarshaler

func (*Ztype) ZebraUnmarshalMsgWithCfg 

func (z *Ztype) ZebraUnmarshalMsgWithCfg(bts []byte, cfg *msgp.RuntimeConfig) (o []byte, err error)

func (*Ztype) ZebrafieldsNotEmpty 

func (z *Ztype) ZebrafieldsNotEmpty(isempty []bool) uint32

ZebrafieldsNotEmpty supports omitempty tags

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.