Lua::API - interface to Lua's embedding API
use Lua::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, lua_Buffer, lua_Debug, and luaL_Reg. lua_State is by far the most important, as it represents an instance of the Lua interpreter. Currently lua_State, lua_Buffer, and 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.
lua_State
lua_Buffer
lua_Debug
luaL_Reg
The Lua C API also defines the following function interfaces: lua_Alloc, lua_CFunction, lua_Reader, lua_Writer. At present, only lua_CFunction is supported. Any routine using the other interfaces is not supported.
lua_Alloc
lua_CFunction
lua_Reader
lua_Writer
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 (lua_, 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.
lua_
luaL_
Wherever the Lua API calls for a lua_CFunction or a lua_Hook, a reference to a Perl function should be used.
lua_Hook
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.
sethook()
Hooks are supported transparently.
register()
pushcfunction()
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.
cpcall()
These are supported transparently.
pushcclosure()
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.
n
n+1
getinfo()
lua.h
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::API
LUA_
Lua::API::REGISTRYINDEX
error
die
Lua's version of Perl's die is 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.
Lua::API::State::Error
lua_error
Calls to die from within code invoked by Lua are treated as calls call to Lua::API::State::error.
Lua::API::State::error
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.
lua_error()
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 Lua::API::State class.
lua_State *
Lua::API::State
There are some slight differences, however, which are noted here.
The Lua API provides two constructors, lua_newstate and 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
lua_newstate
luaL_newstate
$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:
lua_close
$L->close;
lua_pushfstring
lua_vpushfstring
These functions are emulated in Perl (as the pushfstring and vpushfstring methods) using Perl's sprintf function, which looks to have a superset of the Lua routines' functionality.
pushfstring
vpushfstring
sprintf
luaL_error
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_pushvfstring.
lua_pushvfstring
lua_register
luaL_register
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:
register
$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 )
The %l argument is a hash whose keys are the names of the functions and whose values are references to Perl functions.
%l
lua_checkstack
luaL_checkstack
These two routines are combined into the checkstack method with the following Perl to C mapping:
checkstack
$L->checkstack($extra); -> lua_checkstack( L, extra ); $L->checkstack($sz, $msg ); -> luaL_checkstack( L, sz, msg );
lua_getmetatable
luaL_getmetatable
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.
getmetatable
lua_typename
luaL_typename
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.
typename
Lua::API::Debug objects are created using the new method:
new
$dbg = Lua::API::Debug->new;
The public attributes of the object ( e.g. event, 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).
event
name
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 new method:
$buf = Lua::API::Debug->new;
There are no publically accessible attributes for this object.
As with 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.
http:lua.org, Inline::Lua
Diab Jerius, <djerius@cpan.org>
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/.
To install Lua::API, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Lua::API
CPAN shell
perl -MCPAN -e shell install Lua::API
For more information on module installation, please visit the detailed CPAN module installation guide.