Lua C modules: confused about including members - c

Question

I am trying to register a Lua C module that I need to use like this.
local harfbuzz = require 'harfbuzz'
-- initialize blob
local blob = harfbuzz.Blob.new(…)
print(blob:length())
My understanding is that I should create a new table and add a metatable to it with the methods, and then add that table as a member Blob to the top-level lib table.
Here is the relevant snippet of code in my C file. I am not very sure what to include in the register_blob function. I tried a few things and they did not work.
static const struct luaL_Reg blob_methods[] = {
{ "length", blob_length },
{"__gc", blob_destroy },
{ NULL, NULL },
};
static const struct luaL_Reg blob_functions[] = {
{ "new", blob_new },
{ NULL, NULL }
};
static const struct luaL_Reg lib_table [] = {
{"version", get_harfbuzz_version},
{NULL, NULL}
};
int register_blob(lua_State *L) {
// QUESTION: What should I include here
}
int luaopen_luaharfbuzz (lua_State *L) {
lua_newtable(L);
register_blob(L);
luaL_setfuncs(L, lib_table, 0);
return 1;
}

Answer 1

What register_blob does really depends on what new_blob needs to do. The two feed into one another.
Given your use case, new_blob needs to create new objects, and those new objects have metatable members equal to your blob_methods table. So, what new_blob needs to do is:
Create a table/userdata to be returned.
Assign that table/userdata a metatable built from the contents of blob_methods table.
Do whatever other initialization work is needed on the object.
Return the object.
So what your register_blob code needs to do is build the metatable that you intend to use in step 2, then store it somewhere that new_blob can easily access it. But also somewhere that noone else can. Or at least, noone outside of C code.
Lua being well designed, it has a place for storing exactly this kind of data. It's called the Lua registry table. The registry acts like a global table. But it can only be access from C; Lua code can't touch it (well, unless you use the debug library. Or pass the registry table to Lua).
The idiomatic way (as I understand it) that the registry is used is that every C module stakes out its own table index in the registry. So your luaopen_luaharfbuzz function would create a table and store that into a key in the registry. The key would probably some string, likely named after your module. And you put all your private stuff into that table.
So your register_blob function would:
Create the table that will be used as the metatable for blob objects.
Use luaL_setfuncs to set the blob_methods into the newly created table.
Get the harfbuzz table from the registry.
Put the newly created table into a known key in the harfbuzz table from the registry.
That way, new_blob knows exactly where to go to get the metatable to use.