msgpackgen

MessagePack Code Generator for Go

msgpackgen provides a code generation tool and serialization library for MessagePack.

• 🚀 Extremely Fast
• ♻️ Easy Maintenance
• 💯 Compliant with specifications
• 🦺 No use unsafe

Quickstart

Create go.mod file, if you still have not created.

# example
go mod init github.com/user/awesome

In a source file(ex. main.go), include one go generate directive. For most modules:

package main

//go:generate go run github.com/shamaton/msgpackgen

If you installed msgpackgen as a binary:

package main

//go:generate msgpackgen

If you added it with go get -tool:

package main

//go:generate go tool github.com/shamaton/msgpackgen

And run the following command in your shell:

go generate ./...

It will generate one .go file for serialization, default is msgpack.msgpackgen.go. The generated file defines Marshal, MarshalAsMap, MarshalAsArray, Unmarshal, UnmarshalAsMap, and UnmarshalAsArray in the same package as your generated types.

Marshal and Unmarshal look like this:

    v := Struct{}
    b, err := Marshal(v)
    if err != nil {
        panic(err)
    }

    var vv Struct
    err = Unmarshal(b, &vv)
    if err != nil {
        panic(err)
    }

Generated package-level functions handle generated types directly. Without -strict, unrecognized types fall back to the runtime implementation. With -strict, generated APIs return msgpack.ErrUndefinedType for unrecognized types.

If you are updating from v0, which used resolver-based APIs, see MIGRATION.md.

Serializer

Supported Types

primitive types:

int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float32, float64, string, bool, byte, rune, complex64, complex128

slice, array: [], [cap]

map: map[key]value

struct: time.Time and structures you defined

time.Time values are encoded and decoded as UTC by default. Location information is not preserved; values with a non-UTC location round-trip as the same instant in UTC.

Tags

Renaming or omitting are available.

• Renaming fields via msgpack:"field_name"
• Omitting fields via msgpack:"-"
• Omitting zero-value fields from map encoding via msgpack:",omitempty" or msgpack:"field_name,omitempty"

For example:

type Example struct {
    ID    int
    Name  string `msgpack:"name,omitempty"`
    Extra string `msgpack:",omitempty"`
}

When encoded as map, zero-value omitempty fields are not written. When encoded as array, all generated fields are written to preserve positional compatibility.

Switch Default Behaviour

Default serialization behaviour is map type. But the performance of array type is better. If you want to switch array type as default, use SetStructAsArray.

Also, you can use MarshalAsArray, UnmarshalAsArray.

Code Generator

Easy maintenance

This tool generates only one .go file. All you have to delete is one generated .go file.

Analyzing

-input-dir needs to be in $GOPATH.

Code is generated by recursively searching directories, but some directories and files are ignored.

• Prefix _ and . directory.
• testdata and vendor directory
• _test.go file

If you use -input-file option, it will work without considering the above conditions.

Compatible with various import rules.

import (
    "example.com/user/a/b"
    d "example.com/user/a/c"
    . "example.com/user/a/e"
)

Not Generated Case

Not generated in the following cases:

// ex. a/example.go
type Example struct {
    // unsupported types
    Interface any
    Uintptr uintptr
    Error error
    Chan chan
    Func func()

    // nested struct is also unsupported
    NestedStruct struct {}

    // because b.Example is not generated
    B b.Example

    // because bytes.Buffer is in outside package
    Buf bytes.Buffer
}

func (e Example) F() {
    // unsupported struct defined in func
    type InFunction struct {}
}

// ex a/b/example.go
type Example struct {
    Interface any
}

Unrecognized Types

Generated package-level APIs return msgpack.ErrUndefinedType when a value is not handled by generated serializers.

By default, public generated APIs catch that error and fall back to github.com/shamaton/msgpackgen/msgpack/fallback. If you use -strict, generated APIs return msgpack.ErrUndefinedType without fallback.

See also msgpackgen -h

Usage of msgpackgen:
  -dry-run
        dry run mode
  -input-dir string
        input directory. input-file cannot be used at the same time (default ".")
  -input-file string
        input a specific file. input-dir cannot be used at the same time
  -output-dir string
        output directory (default ".")
  -output-file string
        name of generated file (default "msgpack.msgpackgen.go")
  -pointer int
        pointer level to consider (default 1)
  -strict
        disable fallback for unrecognized types
  -use-gopath
        use GOPATH instead of go.mod
  -v    verbose diagnostics

Benchmarks

These results are recorded by msgpack_bench. Our package results show in ShamatonGen.

License

This library is under the MIT License. See the LICENSE file for details.