Aegisub/vendor/luabins
Thomas Goyne 9492192b73 Switch back to building Lua as C
In preparation for switching to LuaJIT, which doesn't support PUC Lua's
thing of using C++ exceptions for lua_error.

Requires replacing all uses of lua_error (and things calling lua_error)
with custom versions that throw an exception instead and adding an
exception -> lua error wrapper at all C++ -> Lua boundaries.
2014-04-27 10:37:23 -07:00
..
etc Integrate luabins into Aegisub's build system 2014-04-24 23:01:27 +02:00
include Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
lib Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
obj Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
rockspec Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
src Switch back to building Lua as C 2014-04-27 10:37:23 -07:00
test Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
tmp Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
AUTHORS Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
BENCHMARK Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
COPYRIGHT Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
HISTORY Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
Makefile Switch back to building Lua as C 2014-04-27 10:37:23 -07:00
README.md Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00
TODO Import luabins 831869cdc8c5e7579804e6472a2dc6cbe0b2672b 2014-04-24 23:00:41 +02:00

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.