Awesome
Since 2016-02-16, Smallfolk is deprecated. I will still fix reported bugs, but for new projects, I recommend bitser if you're using LuaJIT, and binser otherwise.
Smallfolk
Smallfolk is a reasonably fast, robust, richtly-featured table serialization library for Lua. It was specifically written to allow complex data structures to be loaded from unsafe sources for LÖVE games, but can be used anywhere.
You use, distribute and extend Smallfolk under the terms of the MIT license.
Usage
Smallfolk is very simple and easy to use:
local smallfolk = require 'smallfolk'
print(smallfolk.dumps({"Hello", world = true}))
print(smallfolk.loads('{"foo":"bar"}').foo)
-- prints:
-- {"Hello","world":t}
-- bar
Fast
Using Serpent's benchmark code, Smallfolk's serialization speed is comparable to that of Ser (and Ser is 33% faster than Serpent).
It should be noted that deserialization is much slower in Smallfolk than in most other serialization libraries, because it parses the input itself instead of handing it over to Lua. However, if you use LuaJIT this difference is much less, and it is not noticable for small outputs. By default, Smallfolk rejects inputs that are too large, to prevent DOS attacks.
Robust
Sometimes you have strange, non-euclidean geometries in your table constructions. It happens, I don't judge. Smallfolk can deal with that, where some other serialization libraries (or anything that produces JSON) cry "Iä! Iä! Cthulhu fhtagn!" and give up — or worse, silently produce incorrect data.
local smallfolk = require 'smallfolk'
local cthulhu = {{}, {}, {}}
cthulhu.fhtagn = cthulhu
cthulhu[1][cthulhu[2]] = cthulhu[3]
cthulhu[2][cthulhu[1]] = cthulhu[2]
cthulhu[3][cthulhu[3]] = cthulhu
print(smallfolk.dumps(cthulhu))
-- prints:
-- {{{@2:@3}:{@4:@1}},@3,@4,"fhtagn":@1}
Secure
Smallfolk doesn't run arbitrary Lua code, so you can safely use it when you want to read data from an untrusted source.
Compact
Smallfolk creates really small output files compared to something like Ser when it encounters a lot of non-tree-like data, by using numbered references rather than item assignment.
Tested
Check out tests.lua
to see how Smallfolk behaves with all kinds of inputs.
Reference
###smallfolk.dumps(object)
Returns an 8-bit string representation of object
. Throws an error if object
contains any types that cannot be serialised (userdata, functions and threads).
###smallfolk.loads(string[, maxsize=10000])
Returns an object whose representation would be string
. If the length of
string
is larger than maxsize
, no deserialization is attempted and instead
an error is thrown. If string
is not a valid representation of any object,
an error is thrown.