From 15ed84bd499b3ecdba9f431f2d24696a313227e4 Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Thu, 12 Aug 2021 21:10:13 +0200 Subject: String buffers, part 4a: Add metatable serialization dictionary. Sponsored by fmad.io. --- doc/ext_buffer.html | 45 ++++++++++++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 17 deletions(-) (limited to 'doc') diff --git a/doc/ext_buffer.html b/doc/ext_buffer.html index 2443fc90..63c2efe3 100644 --- a/doc/ext_buffer.html +++ b/doc/ext_buffer.html @@ -127,7 +127,7 @@ space.

Buffers operate like a FIFO (first-in first-out) data structure. Data can be appended (written) to the end of the buffer and consumed (read) -from the front of the buffer. These operations can be freely mixed. +from the front of the buffer. These operations may be freely mixed.

The buffer space that holds the characters is managed automatically @@ -199,7 +199,7 @@ may be reused.

buf = buf:free()

The buffer space of the buffer object is freed. The object itself -remains intact, empty and it may be reused. +remains intact, empty and may be reused.

Note: you normally don't need to use this method. The garbage collector @@ -404,8 +404,8 @@ speed is mostly constrained by object creation cost.

The serializer handles most Lua types, common FFI number types and -nested structures. Functions, thread objects, other FFI cdata, full -userdata and associated metatables cannot be serialized (yet). +nested structures. Functions, thread objects, other FFI cdata and full +userdata cannot be serialized (yet).

The encoder serializes nested structures as trees. Multiple references @@ -461,21 +461,31 @@ commonly occur as table keys of objects you are serializing. These keys are compactly encoded as indexes during serialization. A well chosen dictionary saves space and improves serialization performance. +

  • +metatable is a Lua table holding a dictionary of metatables +for the table objects you are serializing. +

    • -dict needs to be an array of strings, starting at index 1 and -without holes (no nil inbetween). The table is anchored in the -buffer object and internally modified into a two-way index (don't do -this yourself, just pass a plain array). The table must not be modified -after it has been passed to buffer.new(). +dict needs to be an array of strings and metatable needs +to be an array of tables. Both starting at index 1 and without holes (no +nil inbetween). The tables are anchored in the buffer object and +internally modified into a two-way index (don't do this yourself, just pass +a plain array). The tables must not be modified after they have been passed +to buffer.new(). +

    +

    +The dict and metatable tables used by the encoder and +decoder must be the same. Put the most common entries at the front. Extend +at the end to ensure backwards-compatibility — older encodings can +then still be read. You may also set some indexes to false to +explicitly drop backwards-compatibility. Old encodings that use these +indexes will throw an error when decoded.

    -The dict tables used by the encoder and decoder must be the -same. Put the most common entries at the front. Extend at the end to -ensure backwards-compatibility — older encodings can then still be -read. You may also set some indexes to false to explicitly drop -backwards-compatibility. Old encodings that use these indexes will throw -an error when decoded. +Metatables that are not found in the metatable dictionary are +ignored when encoding. Decoding returns a table with a nil +metatable.

    Note: parsing and preparation of the options table is somewhat @@ -564,7 +574,7 @@ suffix. 

     object    → nil | false | true
           | null | lightud32 | lightud64
-          | int | num | tab
+          | int | num | tab | tab_mt
           | int64 | uint64 | complex
           | string
 
@@ -585,13 +595,14 @@ tab       → 0x08                                   // Empty table
           | 0x0b a.U a*object h.U h*{object object}      // Mixed
           | 0x0c a.U (a-1)*object                // 1-based array
           | 0x0d a.U (a-1)*object h.U h*{object object}  // Mixed
+tab_mt    → 0x0e (index-1).U tab          // Metatable dict entry
 
 int64     → 0x10 int.L                             // FFI int64_t
 uint64    → 0x11 uint.L                           // FFI uint64_t
 complex   → 0x12 re.L im.L                         // FFI complex
 
 string    → (0x20+len).U len*char.B
-          | 0x0f (index-1).U                        // Dict entry
+          | 0x0f (index-1).U                 // String dict entry
 
 .B = 8 bit
 .I = 32 bit little-endian
-- 
cgit v1.2.3-55-g6feb