1# Codec 2 3High Performance, Feature-Rich Idiomatic Go codec/encoding library for 4binc, msgpack, cbor, json. 5 6Supported Serialization formats are: 7 8 - msgpack: https://github.com/msgpack/msgpack 9 - binc: http://github.com/ugorji/binc 10 - cbor: http://cbor.io http://tools.ietf.org/html/rfc7049 11 - json: http://json.org http://tools.ietf.org/html/rfc7159 12 - simple: 13 14To install: 15 16 go get github.com/ugorji/go/codec 17 18This package understands the `unsafe` tag, to allow using unsafe semantics: 19 20 - When decoding into a struct, you need to read the field name as a string 21 so you can find the struct field it is mapped to. 22 Using `unsafe` will bypass the allocation and copying overhead of `[]byte->string` conversion. 23 24To use it, you must pass the `unsafe` tag during install: 25 26``` 27go install -tags=unsafe github.com/ugorji/go/codec 28``` 29 30Online documentation: http://godoc.org/github.com/ugorji/go/codec 31Detailed Usage/How-to Primer: http://ugorji.net/blog/go-codec-primer 32 33The idiomatic Go support is as seen in other encoding packages in 34the standard library (ie json, xml, gob, etc). 35 36Rich Feature Set includes: 37 38 - Simple but extremely powerful and feature-rich API 39 - Very High Performance. 40 Our extensive benchmarks show us outperforming Gob, Json, Bson, etc by 2-4X. 41 - Multiple conversions: 42 Package coerces types where appropriate 43 e.g. decode an int in the stream into a float, etc. 44 - Corner Cases: 45 Overflows, nil maps/slices, nil values in streams are handled correctly 46 - Standard field renaming via tags 47 - Support for omitting empty fields during an encoding 48 - Encoding from any value and decoding into pointer to any value 49 (struct, slice, map, primitives, pointers, interface{}, etc) 50 - Extensions to support efficient encoding/decoding of any named types 51 - Support encoding.(Binary|Text)(M|Unm)arshaler interfaces 52 - Decoding without a schema (into a interface{}). 53 Includes Options to configure what specific map or slice type to use 54 when decoding an encoded list or map into a nil interface{} 55 - Encode a struct as an array, and decode struct from an array in the data stream 56 - Comprehensive support for anonymous fields 57 - Fast (no-reflection) encoding/decoding of common maps and slices 58 - Code-generation for faster performance. 59 - Support binary (e.g. messagepack, cbor) and text (e.g. json) formats 60 - Support indefinite-length formats to enable true streaming 61 (for formats which support it e.g. json, cbor) 62 - Support canonical encoding, where a value is ALWAYS encoded as same sequence of bytes. 63 This mostly applies to maps, where iteration order is non-deterministic. 64 - NIL in data stream decoded as zero value 65 - Never silently skip data when decoding. 66 User decides whether to return an error or silently skip data when keys or indexes 67 in the data stream do not map to fields in the struct. 68 - Encode/Decode from/to chan types (for iterative streaming support) 69 - Drop-in replacement for encoding/json. `json:` key in struct tag supported. 70 - Provides a RPC Server and Client Codec for net/rpc communication protocol. 71 - Handle unique idiosyncrasies of codecs e.g. 72 - For messagepack, configure how ambiguities in handling raw bytes are resolved 73 - For messagepack, provide rpc server/client codec to support 74 msgpack-rpc protocol defined at: 75 https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md 76 77## Extension Support 78 79Users can register a function to handle the encoding or decoding of 80their custom types. 81 82There are no restrictions on what the custom type can be. Some examples: 83 84 type BisSet []int 85 type BitSet64 uint64 86 type UUID string 87 type MyStructWithUnexportedFields struct { a int; b bool; c []int; } 88 type GifImage struct { ... } 89 90As an illustration, MyStructWithUnexportedFields would normally be 91encoded as an empty map because it has no exported fields, while UUID 92would be encoded as a string. However, with extension support, you can 93encode any of these however you like. 94 95## RPC 96 97RPC Client and Server Codecs are implemented, so the codecs can be used 98with the standard net/rpc package. 99 100## Usage 101 102Typical usage model: 103 104 // create and configure Handle 105 var ( 106 bh codec.BincHandle 107 mh codec.MsgpackHandle 108 ch codec.CborHandle 109 ) 110 111 mh.MapType = reflect.TypeOf(map[string]interface{}(nil)) 112 113 // configure extensions 114 // e.g. for msgpack, define functions and enable Time support for tag 1 115 // mh.SetExt(reflect.TypeOf(time.Time{}), 1, myExt) 116 117 // create and use decoder/encoder 118 var ( 119 r io.Reader 120 w io.Writer 121 b []byte 122 h = &bh // or mh to use msgpack 123 ) 124 125 dec = codec.NewDecoder(r, h) 126 dec = codec.NewDecoderBytes(b, h) 127 err = dec.Decode(&v) 128 129 enc = codec.NewEncoder(w, h) 130 enc = codec.NewEncoderBytes(&b, h) 131 err = enc.Encode(v) 132 133 //RPC Server 134 go func() { 135 for { 136 conn, err := listener.Accept() 137 rpcCodec := codec.GoRpc.ServerCodec(conn, h) 138 //OR rpcCodec := codec.MsgpackSpecRpc.ServerCodec(conn, h) 139 rpc.ServeCodec(rpcCodec) 140 } 141 }() 142 143 //RPC Communication (client side) 144 conn, err = net.Dial("tcp", "localhost:5555") 145 rpcCodec := codec.GoRpc.ClientCodec(conn, h) 146 //OR rpcCodec := codec.MsgpackSpecRpc.ClientCodec(conn, h) 147 client := rpc.NewClientWithCodec(rpcCodec) 148 149