Documentation ¶
Overview ¶
Package plenc provides an efficient serialisation protocol based on protobuf, but without requiring .proto files or awkward autogenerated structs. Your structs are the basis for the serialisation.
plenc needs you to annotate your structs with a plenc tag on each field. The tag either indicates that the field should not be encoded, or provides a persistent index number that's used for that field in the encoding. The indexes within a struct must all be unique and should not be changed. You may remove fields, but you should not re-use the index number of a removed field. You should not change the type of a field. You can change field names as these are not used in the encoding.
Tags look like the following.
type mystruct struct { A int `plenc:"1"` B string `plenc:"-"` // This field is not encoded C float64 `plenc:"2"` // The values of this field are interned. This reduces allocations if // there are a limited set of distinct values used. D string `plenc:"3,intern"` }
The plenctag tool will add tags to structs for you.
plenc only encodes fields that are exported - ones where the field name begins with a capital letter.
Once your structs have plenc tags, encoding and decoding data is very much like the standard JSON library using Marshal and Unmarshal calls. The one difference is that the Marshal function allows you to append encoded data to an existing slice.
Example ¶
package main import ( "fmt" "github.com/philpearl/plenc" ) func main() { type Hat struct { Type string `plenc:"1"` Size float32 `plenc:"2"` } type Person struct { Name string `plenc:"1"` Age int `plenc:"2"` Hats []Hat `plenc:"3"` } var me = Person{ Name: "Lucy", Age: 25, Hats: []Hat{ {Type: "Fedora", Size: 6}, {Type: "floppy", Size: 5.5}, }, } data, err := plenc.Marshal(nil, &me) if err != nil { fmt.Println(err) return } fmt.Printf("%X\n", data) var out Person if err := plenc.Unmarshal(data, &out); err != nil { fmt.Println(err) return } fmt.Printf("%#v\n", out) }
Output: 0A044C75637910321B020D0A064665646F7261150000C0400D0A06666C6F707079150000B040 plenc_test.Person{Name:"Lucy", Age:25, Hats:[]plenc_test.Hat{plenc_test.Hat{Type:"Fedora", Size:6}, plenc_test.Hat{Type:"floppy", Size:5.5}}}
Index ¶
- func CodecForType(typ reflect.Type) (plenccodec.Codec, error)
- func CodecForTypeWithTag(typ reflect.Type, tag string) (plenccodec.Codec, error)
- func Marshal(data []byte, value interface{}) ([]byte, error)
- func RegisterCodec(typ reflect.Type, c plenccodec.Codec)
- func RegisterCodecWithTag(typ reflect.Type, tag string, c plenccodec.Codec)
- func Unmarshal(data []byte, value interface{}) error
- type Plenc
- func (p *Plenc) CodecForType(typ reflect.Type) (plenccodec.Codec, error)
- func (p *Plenc) CodecForTypeRegistry(registry plenccodec.CodecRegistry, typ reflect.Type, tag string) (plenccodec.Codec, error)
- func (p *Plenc) CodecForTypeWithTag(typ reflect.Type, tag string) (plenccodec.Codec, error)
- func (p *Plenc) Marshal(data []byte, value interface{}) ([]byte, error)
- func (p *Plenc) RegisterCodec(typ reflect.Type, c plenccodec.Codec)
- func (p *Plenc) RegisterCodecWithTag(typ reflect.Type, tag string, c plenccodec.Codec)
- func (p *Plenc) RegisterDefaultCodecs()
- func (p *Plenc) Unmarshal(data []byte, value interface{}) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CodecForType ¶
func CodecForType(typ reflect.Type) (plenccodec.Codec, error)
CodecForType returns a codec for the requested type. It should only be needed when constructing a codec based on an existing plenc codec
func CodecForTypeWithTag ¶ added in v0.0.12
CodecForTypeWithTag returns a codec for the requested type and tag. See RegisterCodecWithTag.
func RegisterCodec ¶
func RegisterCodec(typ reflect.Type, c plenccodec.Codec)
RegisterCodec registers a codec with plenc so it can be used for marshaling and unmarshaling. If you write a custom codec then you need to register it before it can be used.
func RegisterCodecWithTag ¶ added in v0.0.12
func RegisterCodecWithTag(typ reflect.Type, tag string, c plenccodec.Codec)
RegisterCodecWithTag is like RegisterCodec, but it registers the codec to be used only when the given tag is specified in the plenc struct tag
For example:
type MyStruct struct { A int `plenc:"1"` B int `plenc:"2,flat"` }
The default codecs include a flat codec for ints. This does not use the ZigZag encoding as is more efficient when you know the values are positive.
Types ¶
type Plenc ¶
type Plenc struct { // Plenc's original time handling was not compatible with protobuf's // google.protobuf.Timestamp. Set this to true to enable a proto compatible // time codec. Set it before calling RegisterDefaultCodecs. ProtoCompatibleTime bool // ProtoCompatibleArrays controls how plenc handles slices and arrays of // data. When set to true Plenc writes arrays that are compatible with // protobuf. If not true it uses a format that allows arrays to be read more // efficiently. Set it before calling RegisterDefaultCodecs. ProtoCompatibleArrays bool // contains filtered or unexported fields }
Plenc is an instance of the plenc encoding and decoding system. It contains a registry of plenc codecs. Use it if you need fine-grain control on plenc's behaviour.
var p plenc.Plenc p.RegisterDefaultCodecs() data, err := p.Marshal(nil, mystruct)
func (*Plenc) CodecForType ¶ added in v0.0.4
CodecForType finds an existing codec for a type or constructs a codec. It calls CodecForTypeRegistry using the internal registry on p
func (*Plenc) CodecForTypeRegistry ¶ added in v0.0.5
func (p *Plenc) CodecForTypeRegistry(registry plenccodec.CodecRegistry, typ reflect.Type, tag string) (plenccodec.Codec, error)
CodecForTypeRegistry builds a new codec for the requested type, consulting registry for any existing codecs needed
func (*Plenc) CodecForTypeWithTag ¶ added in v0.0.12
func (*Plenc) RegisterCodec ¶
func (p *Plenc) RegisterCodec(typ reflect.Type, c plenccodec.Codec)
func (*Plenc) RegisterCodecWithTag ¶ added in v0.0.12
func (*Plenc) RegisterDefaultCodecs ¶
func (p *Plenc) RegisterDefaultCodecs()
RegisterDefaultCodecs sets up the default codecs for plenc. It is called automatically for the default plenc instance, but if you create your own instance of Plenc you should call this before using it.
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
plenctag
plenctag adds plenc tags to your structs
|
plenctag adds plenc tags to your structs |
Package null contains plenc codecs for the types in github.com/unravelin/null.
|
Package null contains plenc codecs for the types in github.com/unravelin/null. |
Package plenccodec provides the core Codecs for plenc.
|
Package plenccodec provides the core Codecs for plenc. |
Package plenccore describes the wire protocol used by plenc.
|
Package plenccore describes the wire protocol used by plenc. |