1Lua::API(3) User Contributed Perl Documentation Lua::API(3)
2
6 Lua::API - interface to Lua's embedding API
7
9 use Lua::API;
10
12 Lua is a simple, expressive, extension programming language that is
13 easily embeddable. Lua::API provides Perl bindings to Lua's C-based
14 embedding API. It allows Perl routines to be called from Lua as if
15 they were written in C, and allows Perl routines to directly manipulate
16 the Lua interpreter and its environment. It presents a very low-level
17 interface (essentially equivalent to the C interface), so is aimed at
18 developers who need that sort of access.
19 Lua::API is not the first place to turn to if you need a simple, more
21 Perl-ish interface; for that, try Inline::Lua, which takes a much
22 higher level approach and masks most of the underlying complexity in
23 communicating between Lua and Perl. Unfortunately by hiding the
24 complexity, this approach also prevents full operability. For
25 Inline::Lua this is a necessary tradeoff, but it does mean that you
26 cannot create as tight an integration with Lua.
27 Translating from Lua's C interface to Lua::API
29 The Lua C API is based upon the following structures: "lua_State",
30 "lua_Buffer", "lua_Debug", and "luaL_Reg". "lua_State" is by far the
31 most important, as it represents an instance of the Lua interpreter.
32 Currently "lua_State", "lua_Buffer", and "lua_Debug" are supported as
33 the Perl classes Lua::API::State, Lua::API::Buffer, and
34 Lua::API::Debug. The functionality provided by the "luaL_Reg" object is
35 provided in a more Perlish fashion by Lua::API and it is thus not
36 exposed.
37 The Lua C API also defines the following function interfaces:
39 "lua_Alloc", "lua_CFunction", "lua_Reader", "lua_Writer". At present,
40 only "lua_CFunction" is supported. Any routine using the other
41 interfaces is not supported.
42 The Lua C API consists of two sets of functions: the base set (via
44 lua.h and lualib.h) and the auxiliary set (via lauxlib.h). Functions
45 manipulating "lua_State" occur in both sets, while functions
46 manipulating "lua_Debug" occur only in the base set and functions
47 manipulating "lua_Buffer" appear only in the auxiliary set.
48 In Lua::API the C function names are stripped of their prefixes
50 ("lua_", "luaL_"), and made methods of Lua::API::State, Lua::API::Debug
51 and Lua::API::Buffer classes, as appropriate. Unfortunately, after
52 stripping prefixes there are several name collisions between the base
53 and auxiliary functions; these are discussed below.
54 Perl functions as CFunctions, Closures, and Hooks
56 Wherever the Lua API calls for a "lua_CFunction" or a "lua_Hook", a
57 reference to a Perl function should be used.
58 Lua::API uses trampoline functions to call the Perl functions. In most
60 cases it is possible to transparently pass to the trampoline function
61 information about which Perl function to call. In some cases, it is
62 not.
63 Hooks via "sethook()"
65 Hooks are supported transparently.
66 CFunctions via "register()" and "pushcfunction()"
68 Perl functions which are passed to Lua via these methods are
69 supported by creating a C closure around the trampoline function
70 and providing the Perl function as an upvalue for the closure.
71 This should be transparent to the caller.
72 CFunctions via "cpcall()"
74 These are supported transparently.
75 CFunctions via "pushcclosure()"
77 To support these, Lua::API adds an extra upvalue containing the
78 Perl function to the closure (e.g. if the caller pushes "n"
79 upvalues on the stack, this will be the "n+1" upvalue).
80 Unfortunately, this means that the "getinfo()" method will report
81 one more upvalue than the caller has pushed onto the stack.
82 "lua.h" constants
84 "lua.h" defines a number of constants. They are available in the
85 "Lua::API" namespace, with the "LUA_" prefix removed (e.g.
86 "Lua::API::REGISTRYINDEX"). They are not exported (either implicitly
87 or by request).
88 Lua "error" and Perl "die"
90 Lua's version of Perl's "die" is "error". In order to ensure that
91 Perl's stack handling isn't mucked about with when "error" is called, a
92 call to Lua::API::State::error is implemented as a call to "die" which
93 throws an exception of class "Lua::API::State::Error". When returning
94 to Lua, an exceptions are converted into a true call to "lua_error".
95 This should be transparent to the user.
96 Calls to "die" from within code invoked by Lua are treated as calls
98 call to "Lua::API::State::error".
99 The implementation (and the format of the errors) will probably change
101 as Lua::API matures.
102 Lua API routines which throw errors
104 Some of the Lua auxiliary API routines throw errors using
105 "lua_error()". In order to protect Perl's runtime environment, these
106 are wrapped and then called using Lua's protected call facility. Any
107 errors are translated into Perl exceptions of class
108 "Lua::API::State::Error"; the actual Lua error object is left on the
109 Lua stack. This results in an extra layer in the call stack, when
110 "lua_error()" is called.
111 Using Lua::API
113 Because the Perl interface closely tracks the C interface, the Lua API
114 documentation serves for both. The type of the first argument in the C
115 function determines to which Perl class its companion Perl method
116 belongs. For example, if the first argument is a "lua_State *", it is
117 a method of the "Lua::API::State" class.
118 There are some slight differences, however, which are noted here.
120 Lua::API::State
122 Constructors
124 The Lua API provides two constructors, "lua_newstate" and
126 "luaL_newstate". They differ in that "lua_newstate" requires a memory
127 allocator while "luaL_newstate" uses Lua's default allocator.
128 Specification of a memory allocator is currently not supported in
129 Lua::API. The constructor may be called as
130 $L = Lua::API::State->new;
132 $L = Lua::API::State->open;
133 $L = Lua::API::State->newstate;
134 Destructors
136 Lua uses the "lua_close" function to destroy a "lua_State" object.
138 This is automatically called when a Lua::API::State object passes out
139 of scope. Tt may also be explicitly invoked:
140 $L->close;
142 Special handling of certain functions
144 "lua_pushfstring", "lua_vpushfstring"
146 These functions are emulated in Perl (as the "pushfstring" and
147 "vpushfstring" methods) using Perl's "sprintf" function, which
148 looks to have a superset of the Lua routines' functionality.
149 "lua_error", "luaL_error"
151 These two functions are combined into the "error" method with the
152 following Perl to C mapping:
153 $L->error; -> lua_error( L );
155 $L->error( $fmt, ... ); -> luaL_error( L, fmt, ... );
156 In the latter case it uses the emulated version of
158 "lua_pushvfstring".
159 "lua_register", "luaL_register"
161 "lua_register" registers a single Perl function with Lua.
162 "luaL_register" opens a library. These two functions are combined
163 into the "register" method, with the following Perl to C mapping:
164 $L->register( $name, $f ); -> lua_register( L, name, f );
166 $L->register( \%l ); -> luaL_register( L, "", l )
167 $L->register( $libname, \%l ); -> luaL_register( L, libname, l )
168 The %l argument is a hash whose keys are the names of the functions
170 and whose values are references to Perl functions.
171 "lua_checkstack", "luaL_checkstack"
173 These two routines are combined into the "checkstack" method with
174 the following Perl to C mapping:
175 $L->checkstack($extra); -> lua_checkstack( L, extra );
177 $L->checkstack($sz, $msg ); -> luaL_checkstack( L, sz, msg );
178 "lua_getmetatable", "luaL_getmetatable"
180 These two routines have the same number of arguments with differing
181 second arguments: "lua_getmetatable" takes a numerical argument,
182 while "luaL_getmetatable" takes a string. They are combined into
183 the "getmetatable" method, which attempts to discern between them.
184 The individual routines are also available under their C names.
185 "lua_typename", "luaL_typename"
187 These two routines have the same calling conventions so it is not
188 possible to disambiguate the calls. The Lua::API "typename" method
189 corresponds to "lua_typename". Both routines are also available
190 under their C names.
191 Lua::API::Debug
193 Constructor
195 Lua::API::Debug objects are created using the "new" method:
197 $dbg = Lua::API::Debug->new;
199 Attributes
201 The public attributes of the object ( e.g. "event", "name", etc.) are
203 available via methods of the same name. It is not possible to change
204 those attributes from the Perl interface. (My reading of the Lua API
205 is that these should be read-only).
206 Destructor
208 There is no documented method for destroying a "lua_Debug" object, so
210 while the Perl object cleans up after itself, it may leave Lua
211 allocated memory behind.
212 Lua::API::Buffer
214 Constructor
216 Lua::API::Buffer objects are created using the "new" method:
218 $buf = Lua::API::Debug->new;
220 Attributes
222 There are no publically accessible attributes for this object.
224 Destructor
226 As with "lua_Debug", there is no documented method for destroying a
228 "lua_Buffer" object, so while the Perl object cleans up after itself it
229 may leave Lua allocated memory behind.
230
232 The examples directory in the Lua::API distribution contains a
233 translation of the lua.c front-end (distributed with Lua 5.1.4) into
234 Perl.
235
237 Lua::API was designed and tested with Lua 5.1.4.
238
240 <http:lua.org>, Inline::Lua
241
243 Diab Jerius, <djerius@cpan.org>
244
246 Copyright 2010, Smithsonian Astrophysical Observatory
247 This program is free software: you can redistribute it and/or modify it
249 under the terms of the GNU General Public License as published by the
250 Free Software Foundation, either version 3 of the License, or (at your
251 option) any later version.
252 This program is distributed in the hope that it will be useful, but
254 WITHOUT ANY WARRANTY; without even the implied warranty of
255 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
256 General Public License for more details.
257 You should have received a copy of the GNU General Public License along
259 with this program. If not, see <http://www.gnu.org/licenses/>.
260perl v5.36.0 2022-10-14 Lua::API(3)