Bootstrapping the Lua API interface

The file protos contains C prototypes for Lua routines which may throw errors via lua_error(). The Perl interface code for these is generated from templates. All other Perl interfaces are hand crafted.

Lua API routines which can throw errors have to be sandboxed so that the Perl runtime environment isn't corrupted. This is done by creating C wrappers designed to be invoked via Lua's protected call mechanism. If the API routine throws and error it is caught and translated into a Perl exception.

The wrappers are generated in two steps.

utils/pproto parses the C prototypes in protos and generates a YAML database containing the parsed result (protos.yml). It also adds any "hints" to the contained in proto_hints.yml.

utils/genxs reads protos.yml, wrap_xs.tpl, and xs_xs.tpl and generates wrap.h and xs.h, which are included by API.xs. wrap_xs.tpl and xs_xs.tpl are Template::Toolkit formatted code templates. xs.h contains the Perl XS interface code, wrap.h contains the C wrappers for the Lua API routines.

At present the above scripts are invoked manually.