mirror of
https://github.com/gvx/bitser.git
synced 2024-11-24 06:54:20 +00:00
169 lines
4.6 KiB
Markdown
169 lines
4.6 KiB
Markdown
* [Basic usage](#basic-usage)
|
|
* [Serializing class instances](#serializing-class-instances)
|
|
* [Advanced usage](#advanced-usage)
|
|
* [Reference](#reference)
|
|
|
|
# Basic usage
|
|
|
|
```lua
|
|
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`](#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
|
|
|
|
```lua
|
|
local string = bitser.dumps(value)
|
|
```
|
|
|
|
Basic serialization of `value` into a Lua string.
|
|
|
|
See also: [`bitser.loads`](#loads).
|
|
|
|
## dumpLoveFile
|
|
|
|
```lua
|
|
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](https://love2d.org/).
|
|
|
|
See also: [`bitser.loadLoveFile`](#loadlovefile).
|
|
|
|
## loads
|
|
|
|
```lua
|
|
local value = bitser.loads(string)
|
|
```
|
|
|
|
Deserializes `value` from `string`.
|
|
|
|
See also: [`bitser.dumps`](#dumps).
|
|
|
|
## loadData
|
|
|
|
```lua
|
|
local value = bitser.loadData(light_userdata, size)
|
|
```
|
|
|
|
Deserializes `value` from raw data. You probably won't need to use this function ever.
|
|
|
|
## loadLoveFile
|
|
|
|
```lua
|
|
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](https://love2d.org/).
|
|
|
|
See also: [`bitser.dumpLoveFile`](#dumplovefile).
|
|
|
|
## register
|
|
|
|
```lua
|
|
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.
|
|
|
|
See also: [`bitser.unregister`](#unregister).
|
|
|
|
## registerClass
|
|
|
|
```lua
|
|
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](#register).
|
|
|
|
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](#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`.
|
|
|
|
See also: [`bitser.unregisterClass`](#unregisterclass).
|
|
|
|
## unregister
|
|
|
|
```lua
|
|
bitser.unregister(name)
|
|
```
|
|
|
|
Deregisters the previously registered value with the name `name`.
|
|
|
|
See also: [`bitser.register`](#register).
|
|
|
|
## unregisterClass
|
|
|
|
```lua
|
|
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.
|
|
|
|
See also: [`bitser.registerClass`](#registerclass).
|
|
|
|
## reserveBuffer
|
|
|
|
```lua
|
|
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
|
|
|
|
```lua
|
|
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.
|