mirror of
https://github.com/appgurueu/modlib.git
synced 2024-08-19 21:04:13 +02:00
Bluon documentation
This commit is contained in:
parent
8105ee2419
commit
7dea86fec2
115
Readme.md
115
Readme.md
@ -10,6 +10,121 @@ No dependencies. Licensed under the MIT License. Written by Lars Mueller aka LMD
|
|||||||
|
|
||||||
Mostly self-documenting code. Mod namespace is `modlib` or `_ml`, containing all variables & functions.
|
Mostly self-documenting code. Mod namespace is `modlib` or `_ml`, containing all variables & functions.
|
||||||
|
|
||||||
|
### Bluon
|
||||||
|
|
||||||
|
Binary Lua object notation. **Experimental.** Handling of subnormal numbers (very small floats) may be broken.
|
||||||
|
|
||||||
|
#### `new(def)`
|
||||||
|
|
||||||
|
```lua
|
||||||
|
def = {
|
||||||
|
aux_is_valid = function(object)
|
||||||
|
return is_valid
|
||||||
|
end,
|
||||||
|
aux_len = function(object)
|
||||||
|
return length_in_bytes
|
||||||
|
end,
|
||||||
|
-- read type byte, stream providing :read(count), map of references -> id
|
||||||
|
aux_read = function(type, stream, references)
|
||||||
|
... = stream:read(...)
|
||||||
|
return object
|
||||||
|
end,
|
||||||
|
-- object to be written, stream providing :write(text), list of references
|
||||||
|
aux_write = function(object, stream, references)
|
||||||
|
stream:write(...)
|
||||||
|
end
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `:is_valid(object)`
|
||||||
|
|
||||||
|
Returns whether the given object can be represented by the instance as boolean.
|
||||||
|
|
||||||
|
#### `:len(object)`
|
||||||
|
|
||||||
|
Returns the expected length of the object if serialized by the current instance in bytes.
|
||||||
|
|
||||||
|
#### `:write(object, stream)`
|
||||||
|
|
||||||
|
Writes the object to a stream supporting `:write(text)`. Throws an error if invalid.
|
||||||
|
|
||||||
|
#### `:read(stream)`
|
||||||
|
|
||||||
|
Reads a single bluon object from a stream supporting `:read(count)`. Throws an error if invalid bluon.
|
||||||
|
|
||||||
|
Checking whether the stream has been fully consumed by doing `assert(not stream:read(1))` is left up to the user.
|
||||||
|
|
||||||
|
#### Format
|
||||||
|
|
||||||
|
* `nil`: nothing (`""`)
|
||||||
|
* `false`: 0
|
||||||
|
* `true`: 1
|
||||||
|
* Numbers:
|
||||||
|
* Constants: 0, nan, +inf, -inf
|
||||||
|
* Integers: Little endian `U8`, `U16`, `U32`, `U64`, `-U8`, `-U16`, `-U32`, `-U64`
|
||||||
|
* Floats: Little endian `F32`, `F64`
|
||||||
|
* Strings:
|
||||||
|
* Constant: `""`
|
||||||
|
* Length as unsigned integer: `T8`, `T16`, `T32`, `T64`
|
||||||
|
* Tables:
|
||||||
|
* List and map part count as unsigned integers
|
||||||
|
* `L0`, `L8`, `L16`, `L32`, `L64` times `M0`, `M8`, `M16`, `M32`, `M64`
|
||||||
|
* Reference:
|
||||||
|
* Reference ID as unsigned integer: `R8`, `R16`, `R32`, `R64`
|
||||||
|
* Reserved types:
|
||||||
|
* Everything <= 55 => 200 free types
|
||||||
|
|
||||||
|
#### Features
|
||||||
|
|
||||||
|
* Embeddable: Written in pure Lua
|
||||||
|
* Storage efficient: No duplication of strings or reference-equal tables
|
||||||
|
* Flexible: Can serialize circular references and strings containing null
|
||||||
|
|
||||||
|
#### Simple example
|
||||||
|
|
||||||
|
```lua
|
||||||
|
local object = ...
|
||||||
|
-- Write to file
|
||||||
|
local file = io.open(..., "w")
|
||||||
|
modlib.bluon:write(object, file)
|
||||||
|
file:close()
|
||||||
|
-- Write to text
|
||||||
|
local rope = modlib.table.rope{}
|
||||||
|
modlib.bluon:write(object, rope)
|
||||||
|
text = rope:to_text()
|
||||||
|
-- Read from text
|
||||||
|
local inputstream = modlib.text.inputstream"\1"
|
||||||
|
assert(modlib.bluon:read(object, rope) == true)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Advanced example
|
||||||
|
|
||||||
|
```lua
|
||||||
|
-- Serializes all userdata to a constant string:
|
||||||
|
local custom_bluon = bluon.new{
|
||||||
|
aux_is_valid = function(object)
|
||||||
|
return type(object) == "userdata"
|
||||||
|
end,
|
||||||
|
aux_len = function(object)
|
||||||
|
return 1 + ("userdata"):len())
|
||||||
|
end,
|
||||||
|
aux_read = function(type, stream, references)
|
||||||
|
assert(type == 100, "unsupported type")
|
||||||
|
assert(stream:read(("userdata"):len()) == "userdata")
|
||||||
|
return userdata()
|
||||||
|
end,
|
||||||
|
-- object to be written, stream providing :write(text), list of references
|
||||||
|
aux_write = function(object, stream, references)
|
||||||
|
assert(type(object) == "userdata")
|
||||||
|
stream:write"\100userdata"
|
||||||
|
end
|
||||||
|
}
|
||||||
|
-- Write to text
|
||||||
|
local rope = modlib.table.rope{}
|
||||||
|
custom_bluon:write(userdata(), rope)
|
||||||
|
assert(rope:to_text() == "\100userdata")
|
||||||
|
```
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
### Legacy
|
### Legacy
|
||||||
|
Loading…
Reference in New Issue
Block a user