mirror of https://github.com/gvx/bitser.git synced 2024-11-11 01:44:21 +00:00

Robin Wellner 3e3a238eaa Create USAGE.md

2017-01-08 16:28:59 +01:00

4.6 KiB

Raw Blame History

Basic usage
Serializing class instances
Advanced usage
Reference

Basic usage

local bitser = require 'bitser'

-- some_thing can be almost any lua value
local binary_data = bitser.dumps(some_thing)

-- binary_data is a string containing some serialized value
local copy_of_some_thing = bitser.loads(binary_data)

Bitser can't dump values of type function, userdata or thread, or anything that contains one of those. If you need to, look into bitser.register.

Serializing class instances

(I need to finish this section.)

Supported class libraries

MiddleClass
SECL
hump.class
Slither
Moonscript classes

Advanced usage

(I need to finish this section.)

Reference

dumps

local string = bitser.dumps(value)

Basic serialization of value into a Lua string.

dumpLoveFile

bitser.dumpLoveFile(file_name, value)

Serializes value and writes the result to file_name more efficiently than serializing to a string and writing that string to a file. Only useful if you're running LÖVE.

loads

local value = bitser.loads(string)

Deserializes value from string.

loadData

local value = bitser.loadData(light_userdata, size)

Deserializes value from raw data. You probably won't need to use this function ever.

loadLoveFile

local value = bitser.loadLoveFile(file_name)

Reads from file_name and deserializes value more efficiently than reading the file and then deserializing that string. Only useful if you're running LÖVE.

register

bitser.register(name, resource)

Registers the value resource with the name name, which has to be a unique string. Registering static resources like images, functions, classes and huge strings, makes sure bitser doesn't attempt to serialize them, but only stores a named reference to them.

registerClass

bitser.registerClass(class)
bitser.registerClass(name, class)
bitser.registerClass(name, class, classkey, deserializer)

Registers the class class, so that bitser can correctly serialize and deserialize instances of class.

Note that if you want to serialize the class itself, you'll need to register the class as a resource.

Most of the time the first variant is enough, but some class libraries don't store the class name on the class object itself, in which case you'll need to use the second variant.

Class names also have to be unique, so if you use multiple classes with the same name, you'll need to use the second variant as well to give them different names.

The arguments classkey and deserializer exist so you can hook in unsupported class libraries without needing to patch bitser. See the list of supported class libraries

If not nil, the argument classkey should be a string such that rawget(obj, classkey) == class for any obj whose type is class. This is done so that key is skipped for serialization.

If not nil, the argument deserializer should be a function such that deserializer(obj, class) returns a valid instance of class with the properties of obj. deserializer is allowed to mutate obj.

unregister

bitser.unregister(name)

Deregisters the previously registered value with the name name.

unregisterClass

bitser.unregisterClass(name)

Deregisters the previously registered class with the name name. Note that this works by name and not value, which is useful in a context where you don't have a reference to the class you want to unregister.

reserveBuffer

bitser.reserveBuffer(num_bytes)

Makes sure the buffer used for reading and writing serialized data is at least num_bytes large. You probably don't need to ever use this function.

clearBuffer

bitser.clearBuffer()

Frees up the buffer used for reading and writing serialized data for garbage collection. You'll rarely need to use this function, except if you needed a huge buffer before and now only need a small buffer (or are done (de)serializing altogether). Most of the time, using this function will decrease performance needlessly.

4.6 KiB Raw Blame History