Lua::API - interface to Lua's embedding API
Lua is a simple, expressive, extension programming language that is easily embeddable. Lua::API provides Perl bindings to Lua's C-based embedding API. It allows Perl routines to be called from Lua as if they were written in C, and allows Perl routines to directly manipulate the Lua interpreter and its environment. It presents a very low-level interface (essentially equivalent to the C interface), so is aimed at developers who need that sort of access.
Lua::API is not the first place to turn to if you need a simple, more Perl-ish interface; for that, try Inline::Lua, which takes a much higher level approach and masks most of the underlying complexity in communicating between Lua and Perl. Unfortunately by hiding the complexity, this approach also prevents full operability. For Inline::Lua this is a necessary tradeoff, but it does mean that you cannot create as tight an integration with Lua.
The Lua C API is based upon the following structures:
lua_State is by far the most important, as it represents an instance of the Lua interpreter. Currently
lua_Debug are supported as the Perl classes Lua::API::State, Lua::API::Buffer, and Lua::API::Debug. The functionality provided by the
luaL_Reg object is provided in a more Perlish fashion by Lua::API and it is thus not exposed.
The Lua C API also defines the following function interfaces:
lua_Writer. At present, only
lua_CFunction is supported. Any routine using the other interfaces is not supported.
The Lua C API consists of two sets of functions: the base set (via lua.h and lualib.h) and the auxiliary set (via lauxlib.h). Functions manipulating
lua_State occur in both sets, while functions manipulating
lua_Debug occur only in the base set and functions manipulating
lua_Buffer appear only in the auxiliary set.
In Lua::API the C function names are stripped of their prefixes (
luaL_), and made methods of Lua::API::State, Lua::API::Debug and Lua::API::Buffer classes, as appropriate. Unfortunately, after stripping prefixes there are several name collisions between the base and auxiliary functions; these are discussed below.
Wherever the Lua API calls for a
lua_CFunction or a
lua_Hook, a reference to a Perl function should be used.
Lua::API uses trampoline functions to call the Perl functions. In most cases it is possible to transparently pass to the trampoline function information about which Perl function to call. In some cases, it is not.
Hooks are supported transparently.
Perl functions which are passed to Lua via these methods are supported by creating a C closure around the trampoline function and providing the Perl function as an upvalue for the closure. This should be transparent to the caller.
These are supported transparently.
To support these, Lua::API adds an extra upvalue containing the Perl function to the closure (e.g. if the caller pushes
n upvalues on the stack, this will be the
n+1 upvalue). Unfortunately, this means that the
getinfo() method will report one more upvalue than the caller has pushed onto the stack.
lua.h defines a number of constants. They are available in the
Lua::API namespace, with the
LUA_ prefix removed (e.g.
Lua::API::REGISTRYINDEX). They are not exported (either implicitly or by request).
Lua's version of Perl's
error. In order to ensure that Perl's stack handling isn't mucked about with when
error is called, a call to Lua::API::State::error is implemented as a call to
die which throws an exception of class
Lua::API::State::Error. When returning to Lua, an exceptions are converted into a true call to
lua_error. This should be transparent to the user.
die from within code invoked by Lua are treated as calls call to
The implementation (and the format of the errors) will probably change as Lua::API matures.
Some of the Lua auxiliary API routines throw errors using
lua_error(). In order to protect Perl's runtime environment, these are wrapped and then called using Lua's protected call facility. Any errors are translated into Perl exceptions of class
Lua::API::State::Error; the actual Lua error object is left on the Lua stack. This results in an extra layer in the call stack, when
lua_error() is called.
Because the Perl interface closely tracks the C interface, the Lua API documentation serves for both. The type of the first argument in the C function determines to which Perl class its companion Perl method belongs. For example, if the first argument is a
lua_State *, it is a method of the
There are some slight differences, however, which are noted here.
The Lua API provides two constructors,
luaL_newstate. They differ in that
lua_newstate requires a memory allocator while
luaL_newstate uses Lua's default allocator. Specification of a memory allocator is currently not supported in Lua::API. The constructor may be called as
$L = Lua::API::State->new; $L = Lua::API::State->open; $L = Lua::API::State->newstate;
Lua uses the
lua_close function to destroy a
lua_State object. This is automatically called when a Lua::API::State object passes out of scope. Tt may also be explicitly invoked:
These functions are emulated in Perl (as the
vpushfstring methods) using Perl's
sprintf function, which looks to have a superset of the Lua routines' functionality.
These two functions are combined into the
error method with the following Perl to C mapping:
$L->error; -> lua_error( L ); $L->error( $fmt, ... ); -> luaL_error( L, fmt, ... );
In the latter case it uses the emulated version of
lua_register registers a single Perl function with Lua.
luaL_register opens a library. These two functions are combined into the
register method, with the following Perl to C mapping:
$L->register( $name, $f ); -> lua_register( L, name, f ); $L->register( \%l ); -> luaL_register( L, "", l ) $L->register( $libname, \%l ); -> luaL_register( L, libname, l )
%l argument is a hash whose keys are the names of the functions and whose values are references to Perl functions.
These two routines are combined into the
checkstack method with the following Perl to C mapping:
$L->checkstack($extra); -> lua_checkstack( L, extra ); $L->checkstack($sz, $msg ); -> luaL_checkstack( L, sz, msg );
These two routines have the same number of arguments with differing second arguments:
lua_getmetatable takes a numerical argument, while
luaL_getmetatable takes a string. They are combined into the
getmetatable method, which attempts to discern between them. The individual routines are also available under their C names.
These two routines have the same calling conventions so it is not possible to disambiguate the calls. The Lua::API
typename method corresponds to
lua_typename. Both routines are also available under their C names.
Lua::API::Debug objects are created using the
$dbg = Lua::API::Debug->new;
The public attributes of the object ( e.g.
name, etc.) are available via methods of the same name. It is not possible to change those attributes from the Perl interface. (My reading of the Lua API is that these should be read-only).
There is no documented method for destroying a
lua_Debug object, so while the Perl object cleans up after itself, it may leave Lua allocated memory behind.
Lua::API::Buffer objects are created using the
$buf = Lua::API::Debug->new;
There are no publically accessible attributes for this object.
lua_Debug, there is no documented method for destroying a
lua_Buffer object, so while the Perl object cleans up after itself it may leave Lua allocated memory behind.
The examples directory in the Lua::API distribution contains a translation of the lua.c front-end (distributed with Lua 5.1.4) into Perl.
Lua::API was designed and tested with Lua 5.1.4.
Diab Jerius, <email@example.com>
Copyright 2010, Smithsonian Astrophysical Observatory
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.