Aegisub/vendor/luabins/README.md

luabins — Lua Binary Serialization Library

Allows to save tuples of primitive Lua types into binary chunks and to load saved data back.

On serialization

Luabins works with

• nil
• boolean
• number
• string
• table (see below)

Luabins refuses to save

• function
• thread
• userdata

Luabins intentionally does not save or check any meta-information (versions, endianness etc.) along with data. If needed, it is to be handled elsewhere.

Table serialization

1. Metatatables are ignored.

2. Table nesting depth should be no more than LUABINS_MAXTABLENESTING.

3. On table save references are not honored. Each encountered reference becomes independent object on load:

   local t = { 42 }
   { t, t }
   

   becomes

   { { 42 }, { 42 } }
   

   that is, three separate tables instead of two.

Lua API

• luabins.save(...)

  Saves arguments into a binary string.

  • On success returns that string.
  • On failure returns nil and error message.

  Example:

  local str = assert(luabins.save(1, "two", { "three", 4 }))
  

• luabins.load(string)

  Loads a list of values from a binary string.

  • On success returns true and loaded values.
  • On failure returns nil and error message.

  Example:

  If you do not know in advance what data is stored inside a binary string, you may put results into a table:

  local values = { luabins.load(data) }
  assert(values[1], values[2])
  

  If you know how to handle stored values (for example you're sure they were generated following some established protocol), you may want to use something like this function to check luabins.load() result:

  function eat_true(t, ...)
      assert(t, ...)
      return ...
  end
  
  my_value_handler(eat_true(luabins.load(data)))
  

C API

• int luabins_save(lua_State * L, int index_from, int index_to)

  Save Lua values from given state at given stack index range. Lua value is left untouched. Note that empty range is not an error. You may save from 0 to LUABINS_MAXTUPLE values. Note only real non-negative indices work.

  • On success returns 0, pushes saved data as a string on the top of stack.
  • On failure returns non-zero, pushes error message on the top of the stack.

• int luabins_load(lua_State * L, const unsigned char * data, size_t len, int *count)

  Load Lua values from given byte chunk.

  • On success returns 0, pushes loaded values on stack. Sets count to the number of values pushed. Note that to have zero loaded items is a valid scenario.
  • On failure returns non-zero, pushes error message on the top of the stack.

Luabins is still an experimental volatile software. Please see source code for more documentation.

See the copyright information in the file named COPYRIGHT.