1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
3 <!--Converted with LaTeX2HTML 2002-2-1 (1.71)
4 original version by: Nikos Drakos, CBLU, University of Leeds
5 * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6 * with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
10 <TITLE>3 The Lua interface</TITLE>
11 <META NAME="description" CONTENT="3 The Lua interface">
12 <META NAME="keywords" CONTENT="ionnotes">
13 <META NAME="resource-type" CONTENT="document">
14 <META NAME="distribution" CONTENT="global">
16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17 <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
20 <LINK REL="STYLESHEET" HREF="ionnotes.css">
22 <LINK REL="next" HREF="node5.html">
23 <LINK REL="previous" HREF="node3.html">
24 <LINK REL="up" HREF="ionnotes.html">
25 <LINK REL="next" HREF="node5.html">
30 <DIV CLASS="navigation"><!--Navigation Panel-->
33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
47 <B> Next:</B> <A NAME="tex2html116"
48 HREF="node5.html">4 Miscellaneous design notes</A>
49 <B> Up:</B> <A NAME="tex2html110"
50 HREF="ionnotes.html">Ion: Notes for the</A>
51 <B> Previous:</B> <A NAME="tex2html104"
52 HREF="node3.html">2 Object system implementation</A>
53 <B> <A NAME="tex2html112"
54 HREF="node1.html">Contents</A></B>
55 <B> <A NAME="tex2html114"
56 HREF="node8.html">Index</A></B>
59 <!--End of Navigation Panel-->
60 <!--Table of Child-Links-->
61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
63 <UL CLASS="ChildLinks">
64 <LI><A NAME="tex2html117"
65 HREF="node4.html#SECTION00041000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Supported types</A>
66 <LI><A NAME="tex2html118"
67 HREF="node4.html#SECTION00042000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Exporting functions</A>
68 <LI><A NAME="tex2html119"
69 HREF="node4.html#SECTION00043000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Calling Lua functions and code</A>
70 <LI><A NAME="tex2html120"
71 HREF="node4.html#SECTION00044000000000000000"><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Miscellaneous notes</A>
73 <!--End of Table of Child-Links-->
76 <H1><A NAME="SECTION00040000000000000000">
77 <SPAN CLASS="arabic">3</SPAN> The Lua interface</A>
81 This section finally describes the implementation details and how modules
82 should us the Lua interface. First, in section <A HREF="#sec:supptypes">3.1</A>
83 we look at types supported by the interface, how objects are passed to Lua
84 code and how Lua tables should be accessed from Ion and modules. In section
85 <A HREF="#sec:exporting">3.2</A> the methods for exporting functions and how they
86 are called from Lua are explained and in section <A HREF="#sec:calling">3.3</A> the
87 method for calling Lua functions is explained.
91 <H2><A NAME="SECTION00041000000000000000"></A>
92 <A NAME="sec:supptypes"></A>
94 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Supported types
98 The following types are supported in passing parameters between the
99 C side of Ion and Lua:
102 <TABLE CELLPADDING=3 BORDER="1">
103 <TR><TD ALIGN="RIGHT">Identifier
105 <TD ALIGN="LEFT">C type</TD>
106 <TD ALIGN="LEFT">Description</TD>
108 <TR><TD ALIGN="RIGHT">i</TD>
109 <TD ALIGN="LEFT">int</TD>
110 <TD ALIGN="LEFT">Integer</TD>
112 <TR><TD ALIGN="RIGHT">s</TD>
113 <TD ALIGN="LEFT">char*</TD>
114 <TD ALIGN="LEFT">String</TD>
116 <TR><TD ALIGN="RIGHT">S</TD>
117 <TD ALIGN="LEFT">const char*</TD>
118 <TD ALIGN="LEFT">Constant string</TD>
120 <TR><TD ALIGN="RIGHT">d</TD>
121 <TD ALIGN="LEFT">double</TD>
122 <TD ALIGN="LEFT"> </TD>
124 <TR><TD ALIGN="RIGHT">b</TD>
125 <TD ALIGN="LEFT">bool</TD>
126 <TD ALIGN="LEFT"> </TD>
128 <TR><TD ALIGN="RIGHT">t</TD>
129 <TD ALIGN="LEFT">ExtlTab<A NAME="519"></A></TD>
130 <TD ALIGN="LEFT">Reference to Lua table</TD>
132 <TR><TD ALIGN="RIGHT">f</TD>
133 <TD ALIGN="LEFT">ExltFn<A NAME="520"></A></TD>
134 <TD ALIGN="LEFT">Reference to Lua function.</TD>
136 <TR><TD ALIGN="RIGHT">o</TD>
137 <TD ALIGN="LEFT">Any WObj*</TD>
138 <TD ALIGN="LEFT"> </TD>
143 The difference between identifiers 's' and 'S' is that constant
144 strings as return values are not free'd by the level 1 call handler
145 (see below) after passing to Lua (<TT>lua_pushstring</TT> always makes a
146 copy) unlike normal strings. String parameters are always assumed to be
147 the property of the caller and thus implicitly const.
150 Likewise, if a reference to 't' or 'f' is wished to be stored
151 beyond the lifetime of a function receiving such as an argument, a new
152 reference should be created with <TT>extl_ref_table</TT>/<TT>fn</TT>.
153 References can be free'd with
154 <TT>extl_unref_table</TT>/<TT>fn</TT>. References gotten as return values with
155 the <TT>extl_table_get</TT> (how these work should be self-explanatory!)
156 functions are property of the caller and should be unreferenced with the
157 above-mentioned functions when no longer needed.
158 The functions <TT>extl_fn</TT>/<TT>table_none()</TT>
159 return the equivalent of NULL.
162 WObjs are passed to Lua code with WWatch userdatas pointing to
163 them so the objects can be safely deleted although Lua code might still be
164 referencing them. (This is why SWIG or tolua would not have helped in
165 creating the interface: extra wrappers for each function would still
166 have been needed to nicely integrate into Ion's object system. Even in
167 the case that Ion was written in C++ this would be so unless extra bloat
168 adding pointer-like objects were used everywhere instead of pointers.)
169 It may be sometimes necessary check in Lua code that a value known to
170 be an Ion WObj is of certain type. This can be accomplished with
171 <TT>obj_is(obj, "typename")</TT>. <TT>obj_typename(obj)</TT> returns type
176 <H2><A NAME="SECTION00042000000000000000"></A>
177 <A NAME="sec:exporting"></A>
179 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Exporting functions
183 Exported functions (those available to the extension language) are
184 defined by placing <TT>EXTL_EXPORT</TT> before the function implementation
185 in the C source. The script mkexports.pl is then used to automatically
186 generate <SPAN CLASS="textit">exports.c</SPAN> from the source files if
187 <TT>MAKE_EXPORTS=modulename</TT>
188 is specified in the Makefile. All pointers with type beginning with a 'W'
189 are assumed to be pointers to something inheriting WObj. In
190 addition to a table of exported functions and second level call handlers
191 for these, <SPAN CLASS="textit">exports.c</SPAN> will contain two functions
192 <TT>module_register_exports()</TT> and
193 <TT>module_unregister_exports()</TT> that should then be called in module
194 initialisation and deinitialisation code.
197 You've seen the terms level 1 and 2 call handler mentioned above.
199 The Lua support code uses two so called call handlers to convert and check
200 the types of parameters passed from Lua to C and back to Lua. The first
201 one of these call handlers is the same for all exported functions and
202 indeed lua sees all exported as the same C function (the L1 call handler)
203 but with different upvalues passing a structure describing the actual
204 function and the second level call handler. The L1 call handler checks
205 that the parameters received from Lua match a template given as a string
206 of the identifier characters defined above. If everything checks out ok,
207 the parameters are then put in an array of C unions that can contain
208 anyof these known types and the L2 call handler is called.
211 The L2 call handler (which is automatically generated by the mkexports.pl
212 script) for each exported function checks that the passed WObjs
213 are of the more refined type required by the function and then calls the
214 actual function. While the WObj checking could be done in the L1 handler
215 too, the L2 call handlers are needed because we may not know how the target
216 platform passes each parameter type to the called function. Thefore we
217 must let the C compiler generate the code to convert from a simple and
218 known enough parameter passing method (the unions) to the actual
219 parameter passing method. When the called function returns everything
220 is done in reverse order for return values (only one return value is
221 supported by the generated L2 call handlers).
225 <H2><A NAME="SECTION00043000000000000000"></A>
226 <A NAME="sec:calling"></A>
228 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Calling Lua functions and code
233 <TT>extl_call</TT><A NAME="513"></A>,
234 <TT>extl_call_named</TT><A NAME="514"></A>,
235 <TT>extl_dofile</TT><A NAME="515"></A> and
236 <TT>extl_dostring</TT><A NAME="516"></A>
237 call a referenced function (ExtlFn), named function, execute a
238 string and a file, respectively. The rest of the parameters for all these
239 functions are similar. The 'spec' argument is a string of identifier
240 characters (see above) describing the parameters to be passed. These
241 parameters follow after 'rspec'. For dofile and dostring these parameters
242 are passed in the global table arg (same as used for program command
243 lien parameters) and for functions as you might expect. The parameter
244 'rspec' is a similar description of return values. Pointers to variables
245 that should be set to the return values follow after the input values.
246 The return value of all these functions tells if the call and parameter
247 passing succeeded or not.
250 Sometimes it is necessary to block calls to all but a limited set of
251 Ion functions. This can be accomplished with
252 <TT>extl_set_safelist</TT><A NAME="517"></A>.
253 The parameter to this function is a NULL-terminated array of strings
254 and the return value is a similar old safelist.
255 The call <TT>extl_set_safelist(NULL)</TT> removes any safelist and allows
256 calls to all exported functions.
260 <H2><A NAME="SECTION00044000000000000000">
261 <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> Miscellaneous notes</A>
265 Configuration files should be read as before with the function
266 <TT>read_config_for</TT><A NAME="518"></A>
267 except that the list of known options is no longer present.
270 Winprops are now stored in Lua tables and can contain arbitrary
271 properties. The 'proptab' entry in each WClientWin is a reference
272 to a winprop table or <TT>extl_table_none()</TT> if such does not exist
273 and properties may be read with the <TT>extl_table_gets</TT> functions.
274 (It is perfectly legal to pass <TT>extl_table_none()</TT> references to
275 <TT>extl_table_get*</TT>.)
279 <DIV CLASS="navigation"><HR>
280 <!--Navigation Panel-->
281 <A NAME="tex2html115"
283 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
284 <A NAME="tex2html109"
285 HREF="ionnotes.html">
286 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
287 <A NAME="tex2html103"
289 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
290 <A NAME="tex2html111"
292 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
293 <A NAME="tex2html113"
295 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
297 <B> Next:</B> <A NAME="tex2html116"
298 HREF="node5.html">4 Miscellaneous design notes</A>
299 <B> Up:</B> <A NAME="tex2html110"
300 HREF="ionnotes.html">Ion: Notes for the</A>
301 <B> Previous:</B> <A NAME="tex2html104"
302 HREF="node3.html">2 Object system implementation</A>
303 <B> <A NAME="tex2html112"
304 HREF="node1.html">Contents</A></B>
305 <B> <A NAME="tex2html114"
306 HREF="node8.html">Index</A></B> </DIV>
307 <!--End of Navigation Panel-->