github.com/philpearl/plenc@v0.0.15/README.md (about)

     1  
     2  # plenc
     3  
     4  [![GoDoc](https://godoc.org/github.com/philpearl/plenc?status.svg)](https://godoc.org/github.com/philpearl/plenc) 
     5  
     6  plenc is a serialisation library based around protobuf. It uses a very similar encoding to protobuf, but it does not use .proto files or the protobuf data definition language. Instead Go structs are used to define how messages are encoded.
     7  
     8  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.
     9  
    10  Tags look like the following.
    11  
    12  ```go
    13  type mystruct struct {
    14  	A  int     `plenc:"1"`
    15  	B  string  `plenc:"-"` // This field is not encoded
    16  	C  float64 `plenc:"2"`
    17  	// The values of this field are interned. This reduces allocations if
    18  	// there are a limited set of distinct values used.
    19  	D  string  `plenc:"3,intern"`
    20  }
    21  ```
    22  
    23  The `plenctag` tool will add tags to structs for you.
    24  
    25  plenc only encodes fields that are exported - ones where the field name begins with a capital letter.
    26  
    27  Once you've added plenc tags to your structs then encoding and decoding looks very like the JSON standard library. The one difference is that the Marshal function allows you to append encoded data to an existing slice.
    28  
    29  ```go
    30  var in mystruct 
    31  data, err := plenc.Marshal(data[:0], &in)
    32  if err != nil {
    33  	return err
    34  }
    35  
    36  var out mystruct
    37  if err := plenc.Unmarshal(data, &out); err != nil {
    38  	return err
    39  }
    40  ```
    41  
    42  ## Why do this?
    43  
    44  The idea behind plenc is to unlock the performance of protobuf for folk who don't like the Go structs generated by the protobuf compiler and don't want the hassle of creating .proto files. It is for people who want to retrofit better serialisation to a system that's started with JSON.
    45  
    46  Here's a rough benchmark to show the kind of gains you could get using plenc.
    47  
    48  ```
    49  BenchmarkCycle/plenc-16    1369533     881 ns/op    1400 B/op     38 allocs/op
    50  BenchmarkCycle/json-16      214154    5620 ns/op    5211 B/op    120 allocs/op
    51  ```
    52  
    53  ## Is this protobuf?
    54  No, as it stands it is not quite protobuf. It is largely protobuf and has a soft aim to at least be able to read standard protobuf, but there are differences.
    55  
    56  The big difference is that plenc uses its own encoding for slices of types that are implemented with WTLength. Plenc introduces a new wire-type for these - WTSlice (3). The Tag byte is followed by a unsigned varint containing the number of elements in the slice, then each element is encoded with its length as an unsigned varint then the element encoding. This encoding means the receiver easily knows the length of the slice and can allocate it in a single operation.
    57  
    58  You can encode slices with the standard protobuf encoding by using a Plenc object and setting the ProtoCompatibleSlices option. With this option set plenc will use the standard protobuf encoding for slices.
    59  
    60  Plenc is able to read most protobuf data encoded with simple types and standard encodings. It isn't currently able to read proto encoded maps, for example. 
    61  
    62  Also using fixed32 and fixed64 encodings for integer types is not currently supported. I think we could support that via an option on the plenc tag that would select a different codec.
    63  
    64  ## Slices
    65  Neither plenc nor protobuf distinuguish between empty and nil slices. 
    66  If you write an empty slice it will read back as a nil slice.
    67  
    68  Slices of pointers to floats are not allowed.
    69  
    70  Nils within slices of pointers are not supported. 
    71  Nils in slices of pointer to integers will be omitted. 
    72  Nils in slices of pointers to structs will be converted to empty structs.