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 one
81 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 lua_error().
105 In order to protect Perl's runtime environment, these are wrapped and
106 then called using Lua's protected call facility. Any errors are
107 translated into Perl exceptions of class "Lua::API::State::Error"; the
108 actual Lua error object is left on the Lua stack. This results in an
109 extra layer in the call stack, when lua_error() is called.
110 Using Lua::API
112 Because the Perl interface closely tracks the C interface, the Lua API
113 documentation serves for both. The type of the first argument in the C
114 function determines to which Perl class its companion Perl method
115 belongs. For example, if the first argument is a "lua_State *", it is
116 a method of the "Lua::API::State" class.
117 There are some slight differences, however, which are noted here.
119 Lua::API::State
121 Constructors
123 The Lua API provides two constructors, "lua_newstate" and
125 "luaL_newstate". They differ in that "lua_newstate" requires a memory
126 allocator while "luaL_newstate" uses Lua's default allocator.
127 Specification of a memory allocator is currently not supported in
128 Lua::API. The constructor may be called as
129 $L = Lua::API::State->new;
131 $L = Lua::API::State->open;
132 $L = Lua::API::State->newstate;
133 Destructors
135 Lua uses the "lua_close" function to destroy a "lua_State" object.
137 This is automatically called when a Lua::API::State object passes out
138 of scope. Tt may also be explicitly invoked:
139 $L->close;
141 Special handling of certain functions
143 "lua_pushfstring", "lua_vpushfstring"
145 These functions are emulated in Perl (as the "pushfstring" and
146 "vpushfstring" methods) using Perl's "sprintf" function, which
147 looks to have a superset of the Lua routines' functionality.
148 "lua_error", "luaL_error"
150 These two functions are combined into the "error" method with the
151 following Perl to C mapping:
152 $L->error; -> lua_error( L );
154 $L->error( $fmt, ... ); -> luaL_error( L, fmt, ... );
155 In the latter case it uses the emulated version of
157 "lua_pushvfstring".
158 "lua_register", "luaL_register"
160 "lua_register" registers a single Perl function with Lua.
161 "luaL_register" opens a library. These two functions are combined
162 into the "register" method, with the following Perl to C mapping:
163 $L->register( $name, $f ); -> lua_register( L, name, f );
165 $L->register( \%l ); -> luaL_register( L, "", l )
166 $L->register( $libname, \%l ); -> luaL_register( L, libname, l )
167 The %l argument is a hash whose keys are the names of the functions
169 and whose values are references to Perl functions.
170 "lua_checkstack", "luaL_checkstack"
172 These two routines are combined into the "checkstack" method with
173 the following Perl to C mapping:
174 $L->checkstack($extra); -> lua_checkstack( L, extra );
176 $L->checkstack($sz, $msg ); -> luaL_checkstack( L, sz, msg );
177 "lua_getmetatable", "luaL_getmetatable"
179 These two routines have the same number of arguments with differing
180 second arguments: "lua_getmetatable" takes a numerical argument,
181 while "luaL_getmetatable" takes a string. They are combined into
182 the "getmetatable" method, which attempts to discern between them.
183 The individual routines are also available under their C names.
184 "lua_typename", "luaL_typename"
186 These two routines have the same calling conventions so it is not
187 possible to disambiguate the calls. The Lua::API "typename" method
188 corresponds to "lua_typename". Both routines are also available
189 under their C names.
190 Lua::API::Debug
192 Constructor
194 Lua::API::Debug objects are created using the "new" method:
196 $dbg = Lua::API::Debug->new;
198 Attributes
200 The public attributes of the object ( e.g. "event", "name", etc.) are
202 available via methods of the same name. It is not possible to change
203 those attributes from the Perl interface. (My reading of the Lua API
204 is that these should be read-only).
205 Destructor
207 There is no documented method for destroying a "lua_Debug" object, so
209 while the Perl object cleans up after itself, it may leave Lua
210 allocated memory behind.
211 Lua::API::Buffer
213 Constructor
215 Lua::API::Buffer objects are created using the "new" method:
217 $buf = Lua::API::Debug->new;
219 Attributes
221 There are no publically accessible attributes for this object.
223 Destructor
225 As with "lua_Debug", there is no documented method for destroying a
227 "lua_Buffer" object, so while the Perl object cleans up after itself it
228 may leave Lua allocated memory behind.
229
231 The examples directory in the Lua::API distribution contains a
232 translation of the lua.c front-end (distributed with Lua 5.1.4) into
233 Perl.
234
236 Lua::API was designed and tested with Lua 5.1.4.
237
239 <http:lua.org>, Inline::Lua
240
242 Diab Jerius, <djerius@cpan.org>
243
245 Copyright 2010, Smithsonian Astrophysical Observatory
246 This program is free software: you can redistribute it and/or modify it
248 under the terms of the GNU General Public License as published by the
249 Free Software Foundation, either version 3 of the License, or (at your
250 option) any later version.
251 This program is distributed in the hope that it will be useful, but
253 WITHOUT ANY WARRANTY; without even the implied warranty of
254 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
255 General Public License for more details.
256 You should have received a copy of the GNU General Public License along
258 with this program. If not, see <http://www.gnu.org/licenses/>.
259perl v5.38.0 2023-07-20 Lua::API(3)