lizpack

Warning

this project has migrated to codeberg. you can find it at https://codeberg.org/jeffective/lizpack

┌────────────────────────┐
│ │
│ Join us on Codeberg! │
│ │
└────────────────────────┘

A MessagePack Library for Zig

1. Zero allocations.
2. Zero encoding errors.
3. Simple control flow.
4. All messages validated for you.

A simple API:

// encodetrylizpack.encode(T{}, writer, .{})
// decode to stack allocated memoryconstresult: T=trylizpack.decode(T, reader, .{})
// decode to heap allocated memoryconstresult: *T=trylizpack.decodeAlloc(allocator, *T, reader, .{})

Combines with your definition of your message structure:

constCustomerComplaint=struct {
user_id: u64,
status: enum(u8) {
received,
reviewed,
awaiting_response,
finished,
},
};

Default Formats

Zig Type	MessagePack Type
bool	bool
null	nil
u3,u45, i6	integer
?T	nil or T
enum	integer
[N]T	N length array of T
[N:x]T	N+1 length array of T ending in x
[N]u8	str
@Vector(N, T)	N length array of T
struct	map, str: field value
union (enum)	map (single key-value pair)
[]T	N length array of T
[:x]T	N + 1 length array of T ending in x
[]u8	str
[:x]u8	str ending in x
*T	T

Decoding unions is currently not supported.

str is the default MessagePack type for []u8 because it is the smallest for short slices.

Decoding requires a buffer size of at least 1 byte (must be able to peek at least 1 byte). For decoding optionals. This may change in the future if decoding unions is supported.

Unsupported types:

Zig Type	Reason
union (untagged)	Decoding cannot determine active field, and neither can you.
error	I can add this, if someone asks. Perhaps as str?

Note: pointer types require allocation to decode.

Customizing Formats

You can customize how types are formatted in message pack:

Zig Type	Available Encodings
enum	string, int
[]u8,[N]u8, @Vector(N, u8)	string, int, array
struct	map, array
union (enum)	map (single key-value pair), active field
[] struct {key: ..., value: ...}	map, array
[N] struct {key: ..., value: ...}	map, array

See examples for how to do it.

Manual Encoding / Decoding

If you require the finest level of control over how data is encoded and decoded, the lizpack.manual API may suit your use case.

See examples for how to do it.

Examples

conststd=@import("std");
constlizpack=@import("lizpack");
test {
constCustomerComplaint=struct {
user_id: u64,
status: enum(u8) {
received,
reviewed,
awaiting_response,
finished,
},
};
varout: [1000]u8=undefined;
constexpected: CustomerComplaint= .{ .user_id=2345, .status=.reviewed };
constslice: []u8=trylizpack.encode(expected, &out, .{});
trystd.testing.expectEqual(expected, lizpack.decode(@TypeOf(expected), slice, .{}));
}

More examples can be found in examples/.

Installation

To add lizpack to your project as a dependency, run:

zig fetch --save git+https://github.com/kj4tmp/lizpack

Then add the following to your build.zig:

// assuming you have an existing executable called `exe`constlizpack=b.dependency("lizpack", .{
.target=target,
.optimize=optimize,
});
exe.root_module.addImport("lizpack", lizpack.module("lizpack"));

And import the library to begin using it:

constlizpack=@import("lizpack");

Zig Version

Please refer to the minimum_zig_version field of the build.zig.zon.

TODO

• refactor: use of has_sentinel
• refactor: use of std.builtin.Type.Pointer.Sentinel