README.md
1MessagePack Code Generator [](https://travis-ci.org/tinylib/msgp)
2=======
3
4This is a code generation tool and serialization library for [MessagePack](http://msgpack.org). You can read more about MessagePack [in the wiki](http://github.com/tinylib/msgp/wiki), or at [msgpack.org](http://msgpack.org).
5
6### Why?
7
8- Use Go as your schema language
9- Performance
10- [JSON interop](http://godoc.org/github.com/tinylib/msgp/msgp#CopyToJSON)
11- [User-defined extensions](http://github.com/tinylib/msgp/wiki/Using-Extensions)
12- Type safety
13- Encoding flexibility
14
15### Quickstart
16
17In a source file, include the following directive:
18
19```go
20//go:generate msgp
21```
22
23The `msgp` command will generate serialization methods for all exported type declarations in the file.
24
25You can [read more about the code generation options here](http://github.com/tinylib/msgp/wiki/Using-the-Code-Generator).
26
27### Use
28
29Field names can be set in much the same way as the `encoding/json` package. For example:
30
31```go
32type Person struct {
33 Name string `msg:"name"`
34 Address string `msg:"address"`
35 Age int `msg:"age"`
36 Hidden string `msg:"-"` // this field is ignored
37 unexported bool // this field is also ignored
38}
39```
40
41By default, the code generator will satisfy `msgp.Sizer`, `msgp.Encodable`, `msgp.Decodable`,
42`msgp.Marshaler`, and `msgp.Unmarshaler`. Carefully-designed applications can use these methods to do
43marshalling/unmarshalling with zero heap allocations.
44
45While `msgp.Marshaler` and `msgp.Unmarshaler` are quite similar to the standard library's
46`json.Marshaler` and `json.Unmarshaler`, `msgp.Encodable` and `msgp.Decodable` are useful for
47stream serialization. (`*msgp.Writer` and `*msgp.Reader` are essentially protocol-aware versions
48of `*bufio.Writer` and `*bufio.Reader`, respectively.)
49
50### Features
51
52 - Extremely fast generated code
53 - Test and benchmark generation
54 - JSON interoperability (see `msgp.CopyToJSON() and msgp.UnmarshalAsJSON()`)
55 - Support for complex type declarations
56 - Native support for Go's `time.Time`, `complex64`, and `complex128` types
57 - Generation of both `[]byte`-oriented and `io.Reader/io.Writer`-oriented methods
58 - Support for arbitrary type system extensions
59 - [Preprocessor directives](http://github.com/tinylib/msgp/wiki/Preprocessor-Directives)
60 - File-based dependency model means fast codegen regardless of source tree size.
61
62Consider the following:
63```go
64const Eight = 8
65type MyInt int
66type Data []byte
67
68type Struct struct {
69 Which map[string]*MyInt `msg:"which"`
70 Other Data `msg:"other"`
71 Nums [Eight]float64 `msg:"nums"`
72}
73```
74As long as the declarations of `MyInt` and `Data` are in the same file as `Struct`, the parser will determine that the type information for `MyInt` and `Data` can be passed into the definition of `Struct` before its methods are generated.
75
76#### Extensions
77
78MessagePack supports defining your own types through "extensions," which are just a tuple of
79the data "type" (`int8`) and the raw binary. You [can see a worked example in the wiki.](http://github.com/tinylib/msgp/wiki/Using-Extensions)
80
81### Status
82
83Mostly stable, in that no breaking changes have been made to the `/msgp` library in more than a year. Newer versions
84of the code may generate different code than older versions for performance reasons. I (@philhofer) am aware of a
85number of stability-critical commercial applications that use this code with good results. But, caveat emptor.
86
87You can read more about how `msgp` maps MessagePack types onto Go types [in the wiki](http://github.com/tinylib/msgp/wiki).
88
89Here some of the known limitations/restrictions:
90
91- Identifiers from outside the processed source file are assumed (optimistically) to satisfy the generator's interfaces. If this isn't the case, your code will fail to compile.
92- Like most serializers, `chan` and `func` fields are ignored, as well as non-exported fields.
93- Encoding of `interface{}` is limited to built-ins or types that have explicit encoding methods.
94- _Maps must have `string` keys._ This is intentional (as it preserves JSON interop.) Although non-string map keys are not forbidden by the MessagePack standard, many serializers impose this restriction. (It also means *any* well-formed `struct` can be de-serialized into a `map[string]interface{}`.) The only exception to this rule is that the deserializers will allow you to read map keys encoded as `bin` types, due to the fact that some legacy encodings permitted this. (However, those values will still be cast to Go `string`s, and they will be converted to `str` types when re-encoded. It is the responsibility of the user to ensure that map keys are UTF-8 safe in this case.) The same rules hold true for JSON translation.
95
96If the output compiles, then there's a pretty good chance things are fine. (Plus, we generate tests for you.) *Please, please, please* file an issue if you think the generator is writing broken code.
97
98### Performance
99
100If you like benchmarks, see [here](http://bravenewgeek.com/so-you-wanna-go-fast/) and [here](https://github.com/alecthomas/go_serialization_benchmarks).
101
102As one might expect, the generated methods that deal with `[]byte` are faster for small objects, but the `io.Reader/Writer` methods are generally more memory-efficient (and, at some point, faster) for large (> 2KB) objects.
103
){kind=link}