[ANN] llua Higher-level C API for Lua

[steve donovan <steve.j.donovan@...>]

Hi all,

There has been discussion recently about what extra goodies people
would like to see in the C API, and so an experimental pre-release of
llua [0] seems appropriate.  It's much like higher-level Lua bindings
like luar [1] and LuaJava [2] - there are objects which represent Lua
references, and they may be operated on directly, supporting the usual
operations of indexing, calling and so forth.

A related project is Selene [3], which exploits the very expressive
syntactical sugar that C++ allows.  For C, we use the available
mechanisms, such as varargs with argument type specifiers:

    llua_t *G = llua_global(L);
    llua_t *res = llua_gets(G,"print");
    llua_callf(res,"ssi","one","two",42,"");

These references are llib [4] objects, which are themselves
reference-counted and have cleanup functions, so that unref(G) will
remove the Lua reference as well as free the object.

Multiple return values are handled in a similar way to input arguments:

    llua_t *strfind = llua_gets(G,"string.find");
    int i1,i2;
    llua_callf(strfind,"ssi","hello dolly","doll",1,"ii",&i1,&i2);
    printf("i1 %d i2 %d\n",i1,i2);

Simplified ways to evaluate code and access table values:

    llua_t *res = llua_eval(L,"return {a = 'one', b = 'two', c=66}","r");
    char *av, *bv;
    int cv;
    double dv = 23.5;
    llua_gets_v(res,
        "a","s",&av,
        "b","s",&bv,
        "c","i",&cv,
        "d","?f",&dv, // no error if not defined, use default!
    NULL);
    printf("got a='%s' b='%s' c=%d d=%f\n",av,bv,cv,dv);
    //--> got a='one' b='two' c=66 d=23.500000

There is some cost to this goodness, of course.  Using references is
going to be a bit slower than explicit stack operations, but the idea
here is to make it easier for relatively _casual_ use of the Lua API,
or in places which are not speed critical.  On 32-bit Linux, my test
programs are about 22Kb, so make it maybe an extra 14Kb overhead for
statically linking in llua.

The other cost is that as with any C API,  your foot is clearly marked
with a target ;)

llua has been tested for Lua 5.2 and 5.1, on Windows and Linux.  It
currently compiles against the C99 standard, since life is too short
sometimes.  With a project of this nature, it's not always clear how
far to go, and what common patterns to support - which is why I
decided for an early release.

steve d.


[0] https://github.com/stevedonovan/llua
[1] https://github.com/stevedonovan/luar
[2] https://github.com/jasonsantos/luajava
[3] http://lua-users.org/lists/lua-l/2014-02/msg00077.html
[4] https://github.com/stevedonovan/llib