README for lua_cmsgpack.c
===
Lua-cmsgpack is a MessagePack (http://msgpack.org) implementation and bindings for
Lua 5.1 in a self contained C file without external dependencies.
This library is open source software licensed under the BSD two-clause license.
The library is currently considered in BETA STAGE for lack of extensive testing.
INSTALLATION
---
make
sudo make install
If you embed Lua and all modules into your C project, just add the
lua_cmsgpack.c file and call the following function after creating the Lua
interpreter:
luaopen_cmsgpack(L);
USAGE
---
The exported API is very simple, consisting in two functions:
* msgpack = cmsgpack.pack(lua_object)
* lua_object = cmsgpack.unpack(msgpack)
However because of the nature of Lua numerical and table type a few behavior
of the library must be well understood to avoid problems:
* A table is converted into a MessagePack array type only if *all* the keys are
composed of incrementing integers starting at 1 end ending at N, without holes,
without additional non numerical keys. All the other tables are converted into
maps.
* An empty table is always converted into a MessagePack array, the rationale is that empty lists are much more common than empty maps (usually used to represent objects with fields).
* A Lua number is converted into an integer type if floor(number) == number, otherwise it is converted into the MessagePack float or double value.
* When a Lua number is converted to float or double, the former is preferred if there is no loss of precision compared to the double representation.
* When a MessagePack big integer (64 bit) is converted to a Lua number it is possible that the resulting number will not represent the original number but just an approximation. This is unavoidable because the Lua numerical type is usually a double precision floating point type.
NESTED TABLES
---
Nested tables are handled correctly up to LUACMSGPACK_MAX_NESTING levels of
nesting (that is set to 9 by default).
Every table that is nested at a greater level than the maxium is encoded
as MessagePack nil value and throw a exception.
It is worth to note that in Lua it is possible to create tables that mutually
refer to each other, creating a cycle. For example:
a = {x=nil,y=5}
b = {x=a}
a['x'] = b
This condition will throw a exception.
CREDITS
---
This library was written by Salvatore Sanfilippo for Redis, but is maintained as a separated project by the author.
Some of the test vectors in "test.lua" are obtained from the Javascript MessagePack-JS library (https://github.com/cuzic/MessagePack-JS).