| blob | 6c4a6cd356b2defdeb7debc1bfe66f76dbc10a3c |
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4 <head>
12 </head>
13 <body>
28 <tr class="field"><th class="docinfo-name">License:</th><td class="field-body"><p class="first">Permission is hereby granted, free of charge, to any person obtaining a
30 to deal in the Software without restriction, including without limitation
31 the rights to use, copy, modify, merge, publish, distribute, sublicense,
32 and/or sell copies of the Software, and to permit persons to whom the
33 Software is furnished to do so, subject to the following conditions:</p>
34 <p>The above copyright notice and this permission notice shall be included
35 in all copies or substantial portions of the Software.</p>
37 ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
38 TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
39 PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
40 SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
41 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
42 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
43 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
44 OR OTHER DEALINGS IN THE SOFTWARE.</p>
45 </td>
46 </tr>
47 </tbody>
48 </table>
49 <p>Note: This library is currently in public beta phase. This documentation
50 should be considered beta as well. Please report any grammatical
51 corrections/spelling corrections.</p>
55 <li><a class="reference" href="#introduction" id="id44" name="id44">1 Introduction</a></li>
56 <li><a class="reference" href="#features" id="id45" name="id45">2 Features</a></li>
57 <li><a class="reference" href="#portability" id="id46" name="id46">3 Portability</a></li>
58 <li><a class="reference" href="#building-luabind" id="id47" name="id47">4 Building luabind</a></li>
59 <li><a class="reference" href="#basic-usage" id="id48" name="id48">5 Basic usage</a><ul class="auto-toc">
60 <li><a class="reference" href="#hello-world" id="id49" name="id49">5.1 Hello world</a></li>
61 </ul>
62 </li>
64 <li><a class="reference" href="#binding-functions-to-lua" id="id51" name="id51">7 Binding functions to Lua</a><ul class="auto-toc">
65 <li><a class="reference" href="#overloaded-functions" id="id52" name="id52">7.1 Overloaded functions</a></li>
66 <li><a class="reference" href="#signature-matching" id="id53" name="id53">7.2 Signature matching</a></li>
67 <li><a class="reference" href="#calling-lua-functions" id="id54" name="id54">7.3 Calling Lua functions</a></li>
68 <li><a class="reference" href="#using-lua-threads" id="id55" name="id55">7.4 Using Lua threads</a></li>
69 </ul>
70 </li>
71 <li><a class="reference" href="#binding-classes-to-lua" id="id56" name="id56">8 Binding classes to Lua</a><ul class="auto-toc">
72 <li><a class="reference" href="#overloaded-member-functions" id="id57" name="id57">8.1 Overloaded member functions</a></li>
73 <li><a class="reference" href="#properties" id="id58" name="id58">8.2 Properties</a></li>
75 <li><a class="reference" href="#operators" id="id60" name="id60">8.4 Operators</a></li>
76 <li><a class="reference" href="#nested-scopes-and-static-functions" id="id61" name="id61">8.5 Nested scopes and static functions</a></li>
77 <li><a class="reference" href="#derived-classes" id="id62" name="id62">8.6 Derived classes</a></li>
78 <li><a class="reference" href="#smart-pointers" id="id63" name="id63">8.7 Smart pointers</a></li>
79 <li><a class="reference" href="#splitting-class-registrations" id="id64" name="id64">8.8 Splitting class registrations</a></li>
80 </ul>
81 </li>
82 <li><a class="reference" href="#object" id="id65" name="id65">9 Object</a><ul class="auto-toc">
83 <li><a class="reference" href="#iterators" id="id66" name="id66">9.1 Iterators</a></li>
84 <li><a class="reference" href="#related-functions" id="id67" name="id67">9.2 Related functions</a></li>
85 </ul>
86 </li>
87 <li><a class="reference" href="#defining-classes-in-lua" id="id68" name="id68">10 Defining classes in Lua</a><ul class="auto-toc">
88 <li><a class="reference" href="#deriving-in-lua" id="id69" name="id69">10.1 Deriving in lua</a></li>
89 <li><a class="reference" href="#overloading-operators" id="id70" name="id70">10.2 Overloading operators</a></li>
90 <li><a class="reference" href="#finalizers" id="id71" name="id71">10.3 Finalizers</a></li>
91 <li><a class="reference" href="#slicing" id="id72" name="id72">10.4 Slicing</a></li>
92 </ul>
93 </li>
94 <li><a class="reference" href="#exceptions" id="id73" name="id73">11 Exceptions</a></li>
95 <li><a class="reference" href="#policies" id="id74" name="id74">12 Policies</a><ul class="auto-toc">
96 <li><a class="reference" href="#adopt" id="id75" name="id75">12.1 adopt</a></li>
97 <li><a class="reference" href="#dependency" id="id76" name="id76">12.2 dependency</a></li>
98 <li><a class="reference" href="#out-value" id="id77" name="id77">12.3 out_value</a></li>
99 <li><a class="reference" href="#pure-out-value" id="id78" name="id78">12.4 pure_out_value</a></li>
100 <li><a class="reference" href="#return-reference-to" id="id79" name="id79">12.5 return_reference_to</a></li>
102 <li><a class="reference" href="#discard-result" id="id81" name="id81">12.7 discard_result</a></li>
103 <li><a class="reference" href="#return-stl-iterator" id="id82" name="id82">12.8 return_stl_iterator</a></li>
105 <li><a class="reference" href="#yield" id="id84" name="id84">12.10 yield</a></li>
106 </ul>
107 </li>
108 <li><a class="reference" href="#splitting-up-the-registration" id="id85" name="id85">13 Splitting up the registration</a></li>
109 <li><a class="reference" href="#configuration" id="id86" name="id86">14 Configuration</a><ul class="auto-toc">
110 <li><a class="reference" href="#build-options" id="id87" name="id87">14.1 Build options</a></li>
111 </ul>
112 </li>
113 <li><a class="reference" href="#implementation-notes" id="id88" name="id88">15 Implementation notes</a></li>
114 <li><a class="reference" href="#error-messages" id="id89" name="id89">16 Error messages</a></li>
116 <li><a class="reference" href="#known-issues" id="id91" name="id91">18 Known issues</a></li>
117 <li><a class="reference" href="#acknowledgments" id="id92" name="id92">19 Acknowledgments</a></li>
118 </ul>
119 </div>
122 <p>Luabind is a library that helps you create bindings between C++ and Lua. It has
123 the ability to expose functions and classes, written in C++, to Lua. It will
124 also supply the functionality to define classes in Lua and let them derive from
125 other Lua classes or C++ classes. Lua classes can override virtual functions
126 from their C++ base classes. It is written towards Lua 5.0, and does not work
128 <p>It is implemented utilizing template meta programming. That means that you
129 don't need an extra preprocess pass to compile your project (it is done by the
130 compiler). It also means you don't (usually) have to know the exact signature
131 of each function you register, since the library will generate code depending
132 on the compile-time type of the function (which includes the signature). The
133 main drawback of this approach is that the compilation time will increase for
134 the file that does the registration, it is therefore recommended that you
135 register everything in the same cpp-file.</p>
136 <p>Luabind is released under the terms of the <a class="reference" href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</p>
137 <p>We are very interested in hearing about projects that use luabind, please let
138 us know about your project.</p>
139 <p>The main channel for help and feedback is the <a class="reference" href="https://lists.sourceforge.net/lists/listinfo/luabind-user">luabind mailing list</a>.
140 There's also an IRC channel <tt class="docutils literal"><span class="pre">#luabind</span></tt> on irc.freenode.net.</p>
141 </div>
145 <blockquote>
161 </ul>
162 </blockquote>
163 </div>
167 <blockquote>
180 </ul>
181 </blockquote>
183 <blockquote>
186 </ul>
187 </blockquote>
189 means that const member functions are treated as non-const member
190 functions.</p>
191 <p>If you have tried luabind with a compiler not listed here, let us know
192 your result with it.</p>
193 </div>
196 <p>To keep down the compilation-time luabind is built as a library. This means you
197 have to either build it and link against it, or include its source files in
198 your project. You also have to make sure the luabind directory is somewhere in
199 your compiler's include path. It requires <a class="reference" href="http://www.boost.org">Boost</a> 1.32.0 or 1.33.0 to be
200 installed (only boost headers). It also requires that Lua is installed.</p>
201 <p>The official way of building luabind is with <a class="reference" href="http://www.boost.org/tools/build/v2/index_v2.html">Boost.Build V2</a>. To properly build
202 luabind with Boost.Build you need to set two environment variables:</p>
207 <dd>Point this to your Lua directory. The build system will assume that the
208 include and library files are located in <tt class="docutils literal"><span class="pre">$(LUA_PATH)/include/</span></tt> and
210 </dl>
211 <p>For backward compatibility, there is also a makefile in the root-directory that
212 will build the library and the test programs. If you are using a UNIX-system (or
213 cygwin) they will make it easy to build luabind as a static library. If you are
214 using Visual Studio it may be easier to include the files in the src directory
215 in your project.</p>
216 <p>When building luabind you have several options that may streamline the library
217 to better suit your needs. It is extremely important that your application has
218 the same settings as the library was built with. The available options are
220 <p>If you want to change the settings to differ from the default, it's recommended
221 that you define the settings on the command line of all your files (in the
222 project settings in visual studio).</p>
223 </div>
226 <p>To use luabind, you must include <tt class="docutils literal"><span class="pre">lua.h</span></tt> and luabind's main header file:</p>
229 {
231 }
234 </pre>
235 <p>This includes support for both registering classes and functions. If you just
236 want to have support for functions or classes you can include
237 <tt class="docutils literal"><span class="pre">luabind/function.hpp</span></tt> and <tt class="docutils literal"><span class="pre">luabind/class.hpp</span></tt> separately:</p>
241 </pre>
242 <p>The first thing you need to do is to call <tt class="docutils literal"><span class="pre">luabind::open(lua_State*)</span></tt> which
243 will register the functions to create classes from Lua, and initialize some
244 state-global structures used by luabind. If you don't call this function you
245 will hit asserts later in the library. There is no corresponding close function
246 because once a class has been registered in Lua, there really isn't any good
247 way to remove it. Partly because any remaining instances of that class relies
248 on the class being there. Everything will be cleaned up when the state is
249 closed though.</p>
250 <!-- Isn't this wrong? Don't we include lua.h using lua_include.hpp ? -->
251 <p>Luabind's headers will never include <tt class="docutils literal"><span class="pre">lua.h</span></tt> directly, but through
252 <tt class="docutils literal"><span class="pre"><luabind/lua_include.hpp></span></tt>. If you for some reason need to include another
253 Lua header, you can modify this file.</p>
260 void greet()
261 {
263 }
266 {
267 using namespace luabind;
269 open(L);
271 module(L)
272 [
274 ];
276 return 0;
277 }
278 </pre>
281 > loadlib('hello_world.dll', 'init')()
282 > greet()
283 Hello world!
284 >
285 </pre>
286 </div>
287 </div>
290 <p>Everything that gets registered in Lua is registered in a namespace (Lua
291 tables) or in the global scope (called module). All registrations must be
292 surrounded by its scope. To define a module, the <tt class="docutils literal"><span class="pre">luabind::module</span></tt> class is
293 used. It is used like this:</p>
295 module(L)
296 [
297 // declarations
298 ];
299 </pre>
300 <p>This will register all declared functions or classes in the global namespace in
301 Lua. If you want to have a namespace for your module (like the standard
302 libraries) you can give a name to the constructor, like this:</p>
305 [
306 // declarations
307 ];
308 </pre>
310 <p>If you want nested namespace's you can use the <tt class="docutils literal"><span class="pre">luabind::namespace_</span></tt> class. It
311 works exactly as <tt class="docutils literal"><span class="pre">luabind::module</span></tt> except that it doesn't take a lua_State*
312 in it's constructor. An example of its usage could look like this:</p>
315 [
316 // declarations
319 [
320 // library-private declarations
321 ]
322 ];
323 </pre>
326 module(L)
327 [
329 [
330 // declarations
331 ]
333 ];
334 </pre>
337 [
338 // declarations
339 ];
340 </pre>
343 module(L)
344 [
350 ];
351 </pre>
352 <p>More about the actual declarations in the <a class="reference" href="#binding-functions-to-lua">Binding functions to Lua</a> and
354 <p>A word of caution, if you are in really bad need for performance, putting your
355 functions in tables will increase the lookup time.</p>
356 </div>
359 <p>To bind functions to Lua you use the function <tt class="docutils literal"><span class="pre">luabind::def()</span></tt>. It has the
360 following synopsis:</p>
363 void def(const char* name, F f, const Policies&);
364 </pre>
368 <li>The Policies parameter is used to describe how parameters and return values
369 are treated by the function, this is an optional parameter. More on this in
371 </ul>
372 <p>An example usage could be if you want to register the function <tt class="docutils literal"><span class="pre">float</span>
375 module(L)
376 [
378 ];
379 </pre>
382 <p>If you have more than one function with the same name, and want to register
383 them in Lua, you have to explicitly give the signature. This is to let C++ know
384 which function you refer to. For example, if you have two functions, <tt class="docutils literal"><span class="pre">int</span>
385 <span class="pre">f(const</span> <span class="pre">char*)</span></tt> and <tt class="docutils literal"><span class="pre">void</span> <span class="pre">f(int)</span></tt>.</p>
387 module(L)
388 [
391 ];
392 </pre>
393 </div>
396 <p>luabind will generate code that checks the Lua stack to see if the values there
397 can match your functions' signatures. It will handle implicit typecasts between
398 derived classes, and it will prefer matches with the least number of implicit
399 casts. In a function call, if the function is overloaded and there's no
400 overload that match the parameters better than the other, you have an
401 ambiguity. This will spawn a run-time error, stating that the function call is
402 ambiguous. A simple example of this is to register one function that takes an
403 int and one that takes a float. Since Lua doesn't distinguish between floats and
404 integers, both will always match.</p>
405 <p>Since all overloads are tested, it will always find the best match (not the
406 first match). This also means that it can handle situations where the only
407 difference in the signature is that one member function is const and the other
408 isn't.</p>
412 return value policy. More on this in the <a class="reference" href="#policies">Policies</a> section.</p>
413 </div>
416 struct A
417 {
418 void f();
419 void f() const;
420 };
422 const A* create_a();
424 struct B: A {};
425 struct C: B {};
427 void g(A*);
428 void g(B*);
429 </pre>
432 a1 = create_a()
433 a1:f() -- the const version is called
435 a2 = A()
436 a2:f() -- the non-const version is called
438 a = A()
439 b = B()
440 c = C()
442 g(a) -- calls g(A*)
443 g(b) -- calls g(B*)
444 g(c) -- calls g(B*)
445 </pre>
446 </div>
449 <p>To call a Lua function, you can either use <tt class="docutils literal"><span class="pre">call_function()</span></tt> or
453 Ret call_function(lua_State* L, const char* name, ...)
455 Ret call_function(object const& obj, ...)
456 </pre>
457 <p>There are two overloads of the <tt class="docutils literal"><span class="pre">call_function</span></tt> function, one that calls
458 a function given its name, and one that takes an object that should be a Lua
459 value that can be called as a function.</p>
460 <p>The overload that takes a name can only call global Lua functions. The ...
461 represents a variable number of parameters that are sent to the Lua
462 function. This function call may throw <tt class="docutils literal"><span class="pre">luabind::error</span></tt> if the function
463 call fails.</p>
464 <p>The return value isn't actually Ret (the template parameter), but a proxy
465 object that will do the function call. This enables you to give policies to the
466 call. You do this with the operator[]. You give the policies within the
467 brackets, like this:</p>
470 L
472 , new complex_class()
473 )[ adopt(_1) ];
474 </pre>
475 <p>If you want to pass a parameter as a reference, you have to wrap it with the
480 </pre>
481 <p>If you want to use a custom error handler for the function call, see
482 <tt class="docutils literal"><span class="pre">set_pcall_callback</span></tt> under <a class="reference" href="#configuration">Configuration</a>.</p>
483 </div>
486 <p>To start a Lua thread, you have to call <tt class="docutils literal"><span class="pre">lua_resume()</span></tt>, this means that you
487 cannot use the previous function <tt class="docutils literal"><span class="pre">call_function()</span></tt> to start a thread. You have
488 to use</p>
491 Ret resume_function(lua_State* L, const char* name, ...)
493 Ret resume_function(object const& obj, ...)
494 </pre>
498 Ret resume(lua_State* L, ...)
499 </pre>
500 <p>The first time you start the thread, you have to give it a function to execute. i.e. you
501 have to use <tt class="docutils literal"><span class="pre">resume_function</span></tt>, when the Lua function yields, it will return the first
502 value passed in to <tt class="docutils literal"><span class="pre">lua_yield()</span></tt>. When you want to continue the execution, you just call
503 <tt class="docutils literal"><span class="pre">resume()</span></tt> on your <tt class="docutils literal"><span class="pre">lua_State</span></tt>, since it's already executing a function, you don't pass
504 it one. The parameters to <tt class="docutils literal"><span class="pre">resume()</span></tt> will be returned by <tt class="docutils literal"><span class="pre">yield()</span></tt> on the Lua side.</p>
505 <p>For yielding C++-functions (without the support of passing data back and forth between the
506 Lua side and the c++ side), you can use the <a class="reference" href="#yield">yield</a> policy.</p>
507 <p>With the overload of <tt class="docutils literal"><span class="pre">resume_function</span></tt> that takes an <a class="reference" href="#object">object</a>, it is important that the
508 object was constructed with the thread as its <tt class="docutils literal"><span class="pre">lua_State*</span></tt>. Like this:</p>
510 lua_State* thread = lua_newthread(L);
512 resume_function(fun);
513 </pre>
514 </div>
515 </div>
518 <p>To register classes you use a class called <tt class="docutils literal"><span class="pre">class_</span></tt>. Its name is supposed to
519 resemble the C++ keyword, to make it look more intuitive. It has an overloaded
520 member function <tt class="docutils literal"><span class="pre">def()</span></tt> that is used to register member functions, operators,
521 constructors, enums and properties on the class. It will return its
522 this-pointer, to let you register more members directly.</p>
525 class testclass
526 {
527 public:
528 testclass(const std::string& s): m_string(s) {}
531 private:
532 std::string m_string;
533 };
534 </pre>
535 <p>To register it with a Lua environment, write as follows (assuming you are using
536 namespace luabind):</p>
538 module(L)
539 [
543 ];
544 </pre>
545 <p>This will register the class with the name testclass and constructor that takes
546 a string as argument and one member function with the name <tt class="docutils literal"><span class="pre">print_string</span></tt>.</p>
549 > a = testclass('a string')
550 > a:print_string()
551 a string
552 </pre>
553 <p>It is also possible to register free functions as member functions. The
554 requirement on the function is that it takes a pointer, const pointer,
555 reference or const reference to the class type as the first parameter. The rest
556 of the parameters are the ones that are visible in Lua, while the object
557 pointer is given as the first parameter. If we have the following C++ code:</p>
559 struct A
560 {
561 int a;
562 };
564 int plus(A* o, int v) { return o->a + v; }
565 </pre>
566 <p>You can register <tt class="docutils literal"><span class="pre">plus()</span></tt> as if it was a member function of A like this:</p>
570 </pre>
571 <p><tt class="docutils literal"><span class="pre">plus()</span></tt> can now be called as a member function on A with one parameter, int.
572 If the object pointer parameter is const, the function will act as if it was a
573 const member function (it can be called on const objects).</p>
575 <h2><a name="overloaded-member-functions">8.1 Overloaded member functions</a></h2>
576 <p>When binding more than one overloads of a member function, or just binding
577 one overload of an overloaded member function, you have to disambiguate
578 the member function pointer you pass to <tt class="docutils literal"><span class="pre">def</span></tt>. To do this, you can use an
579 ordinary C-style cast, to cast it to the right overload. To do this, you have
580 to know how to express member function types in C++, here's a short tutorial
581 (for more info, refer to your favourite book on C++).</p>
584 <em>return-value</em> (<em>class-name</em>::*)(<em>arg1-type</em>, <em>arg2-type</em>, <em>...</em>)
585 </pre>
588 struct A
589 {
590 void f(int);
591 void f(int, int);
592 };
593 </pre>
597 </pre>
598 <p>This selects the first overload of the function <tt class="docutils literal"><span class="pre">f</span></tt> to bind. The second
599 overload is not bound.</p>
600 </div>
603 <p>To register a global data member with a class is easily done. Consider the
604 following class:</p>
606 struct A
607 {
608 int a;
609 };
610 </pre>
613 module(L)
614 [
617 ];
618 </pre>
619 <p>This gives read and write access to the member variable <tt class="docutils literal"><span class="pre">A::a</span></tt>. It is also
620 possible to register attributes with read-only access:</p>
622 module(L)
623 [
626 ];
627 </pre>
628 <p>When binding members that are a non-primitive type, the auto generated getter
629 function will return a reference to it. This is to allow chained .-operators.
630 For example, when having a struct containing another struct. Like this:</p>
632 struct A { int m; };
633 struct B { A a; };
634 </pre>
635 <p>When binding <tt class="docutils literal"><span class="pre">B</span></tt> to lua, the following expression code should work:</p>
637 b = B()
638 b.a.m = 1
639 assert(b.a.m == 1)
640 </pre>
641 <p>This requires the first lookup (on <tt class="docutils literal"><span class="pre">a</span></tt>) to return a reference to <tt class="docutils literal"><span class="pre">A</span></tt>, and
642 not a copy. In that case, luabind will automatically use the dependency policy
643 to make the return value dependent on the object in which it is stored. So, if
644 the returned reference lives longer than all references to the object (b in
645 this case) it will keep the object alive, to avoid being a dangling pointer.</p>
646 <p>You can also register getter and setter functions and make them look as if they
647 were a public data member. Consider the following class:</p>
649 class A
650 {
651 public:
652 void set_a(int x) { a = x; }
653 int get_a() const { return a; }
655 private:
656 int a;
657 };
658 </pre>
663 </pre>
664 <p>This way the <tt class="docutils literal"><span class="pre">get_a()</span></tt> and <tt class="docutils literal"><span class="pre">set_a()</span></tt> functions will be called instead of
665 just writing to the data member. If you want to make it read only you can just
666 omit the last parameter. Please note that the get function <strong>has to be
668 </div>
671 <p>If your class contains enumerated constants (enums), you can register them as
672 well to make them available in Lua. Note that they will not be type safe, all
673 enums are integers in Lua, and all functions that takes an enum, will accept
674 any integer. You register them like this:</p>
676 module(L)
677 [
680 [
684 ]
685 ];
686 </pre>
687 <p>In Lua they are accessed like any data member, except that they are read-only
688 and reached on the class itself rather than on an instance of the class.</p>
691 > print(A.my_enum)
692 4
693 > print(A.another_enum)
694 6
695 </pre>
696 </div>
699 <p>To bind operators you have to include <tt class="docutils literal"><span class="pre"><luabind/operator.hpp></span></tt>.</p>
700 <p>The mechanism for registering operators on your class is pretty simple. You use
701 a global name <tt class="docutils literal"><span class="pre">luabind::self</span></tt> to refer to the class itself and then you just
702 write the operator expression inside the <tt class="docutils literal"><span class="pre">def()</span></tt> call. This class:</p>
704 struct vec
705 {
706 vec operator+(int s);
707 };
708 </pre>
711 module(L)
712 [
715 ];
716 </pre>
717 <p>This will work regardless if your plus operator is defined inside your class or
718 as a free function.</p>
719 <p>If your operator is const (or, when defined as a free function, takes a const
720 reference to the class itself) you have to use <tt class="docutils literal"><span class="pre">const_self</span></tt> instead of
723 module(L)
724 [
727 ];
728 </pre>
731 + - * / == < <=
732 </pre>
733 <p>This means, no in-place operators. The equality operator (<tt class="docutils literal"><span class="pre">==</span></tt>) has a little
734 hitch; it will not be called if the references are equal. This means that the
735 <tt class="docutils literal"><span class="pre">==</span></tt> operator has to do pretty much what's it's expected to do.</p>
736 <p>Lua does not support operators such as <tt class="docutils literal"><span class="pre">!=</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt> or <tt class="docutils literal"><span class="pre">>=</span></tt>. That's why you
737 can only register the operators listed above. When you invoke one of the
738 mentioned operators, lua will define it in terms of one of the avaliable
739 operators.</p>
740 <p>In the above example the other operand type is instantiated by writing
741 <tt class="docutils literal"><span class="pre">int()</span></tt>. If the operand type is a complex type that cannot easily be
742 instantiated you can wrap the type in a class called <tt class="docutils literal"><span class="pre">other<></span></tt>. For example:</p>
743 <p>To register this class, we don't want to instantiate a string just to register
744 the operator.</p>
746 struct vec
747 {
748 vec operator+(std::string);
749 };
750 </pre>
751 <p>Instead we use the <tt class="docutils literal"><span class="pre">other<></span></tt> wrapper like this:</p>
753 module(L)
754 [
757 ];
758 </pre>
761 module(L)
762 [
765 ];
766 </pre>
767 <p>There's one special operator. In Lua it's called <tt class="docutils literal"><span class="pre">__tostring</span></tt>, it's not
768 really an operator. It is used for converting objects to strings in a standard
769 way in Lua. If you register this functionality, you will be able to use the lua
770 standard function <tt class="docutils literal"><span class="pre">tostring()</span></tt> for converting you object to a string.</p>
771 <p>To implement this operator in C++ you should supply an <tt class="docutils literal"><span class="pre">operator<<</span></tt> for
772 std::ostream. Like this example:</p>
774 class number {};
777 ...
779 module(L)
780 [
783 ];
784 </pre>
785 </div>
787 <h2><a name="nested-scopes-and-static-functions">8.5 Nested scopes and static functions</a></h2>
788 <p>It is possible to add nested scopes to a class. This is useful when you need
789 to wrap a nested class, or a static function.</p>
792 .def(constructor<>()
793 <strong>.scope
794 [
797 ]</strong>;
798 </pre>
799 <p>In this example, <tt class="docutils literal"><span class="pre">f</span></tt> will behave like a static member function of the class
800 <tt class="docutils literal"><span class="pre">foo</span></tt>, and the class <tt class="docutils literal"><span class="pre">nested</span></tt> will behave like a nested class of <tt class="docutils literal"><span class="pre">foo</span></tt>.</p>
802 </div>
805 <p>If you want to register classes that derives from other classes, you can
806 specify a template parameter <tt class="docutils literal"><span class="pre">bases<></span></tt> to the <tt class="docutils literal"><span class="pre">class_</span></tt> instantiation. The
807 following hierarchy:</p>
809 struct A {};
810 struct B : A {};
811 </pre>
814 module(L)
815 [
818 ];
819 </pre>
820 <p>If you have multiple inheritance you can specify more than one base. If B would
821 also derive from a class C, it would be registered like this:</p>
823 module(L)
824 [
826 ];
827 </pre>
828 <p>Note that you can omit <tt class="docutils literal"><span class="pre">bases<></span></tt> when using single inheritance.</p>
832 be able to implicitly cast pointers between the types.</p>
833 </div>
834 </div>
837 <p>When you register a class you can tell luabind that all instances of that class
838 should be held by some kind of smart pointer (boost::shared_ptr for instance).
839 You do this by giving the holder type as an extra template parameter to
840 the <tt class="docutils literal"><span class="pre">class_</span></tt> you are constructing, like this:</p>
842 module(L)
843 [
845 ];
846 </pre>
847 <p>You also have to supply two functions for your smart pointer. One that returns
849 in this case). And one function that extracts the raw pointer from the smart
850 pointer. The first function is needed because luabind has to allow the
851 non-const -> conversion when passing values from Lua to C++. The second
852 function is needed when Lua calls member functions on held types, the this
853 pointer must be a raw pointer, it is also needed to allow the smart_pointer ->
854 raw_pointer conversion from Lua to C++. They look like this:</p>
856 namespace luabind {
860 {
861 return p.get();
862 }
867 {
868 return 0;
869 }
870 }
871 </pre>
872 <p>The second function will only be used to get a compile time mapping
873 of <tt class="docutils literal"><span class="pre">boost::shared_ptr<A></span></tt> to its const version,
874 <tt class="docutils literal"><span class="pre">boost::shared_ptr<const</span> <span class="pre">A></span></tt>. It will never be called, so the
875 return value doesn't matter (only the return type).</p>
880 <colgroup>
883 </colgroup>
887 </tr>
888 </thead>
892 </tr>
895 </tr>
897 <td><tt class="docutils literal"><span class="pre">A</span> <span class="pre">const*</span></tt></td>
898 </tr>
900 <td><tt class="docutils literal"><span class="pre">B</span> <span class="pre">const*</span></tt></td>
901 </tr>
904 </tr>
906 <td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
907 </tr>
908 <tr><td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
909 <td><tt class="docutils literal"><span class="pre">A</span> <span class="pre">const*</span></tt></td>
910 </tr>
911 <tr><td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
912 <td><tt class="docutils literal"><span class="pre">B</span> <span class="pre">const*</span></tt></td>
913 </tr>
914 <tr><td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
915 <td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
916 </tr>
917 </tbody>
918 </table>
919 </div>
923 <colgroup>
926 </colgroup>
930 </tr>
931 </thead>
935 </tr>
936 <tr><td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
937 <td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
938 </tr>
939 <tr><td><tt class="docutils literal"><span class="pre">holder_type<A></span> <span class="pre">const&</span></tt></td>
941 </tr>
942 <tr><td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span> <span class="pre">const&</span></tt></td>
943 <td><tt class="docutils literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
944 </tr>
945 </tbody>
946 </table>
947 </div>
948 <p>When using a holder type, it can be useful to know if the pointer is valid
949 (i.e. not null). For example when using std::auto_ptr, the holder will be
950 invalidated when passed as a parameter to a function. For this purpose there
951 is a member of all object instances in luabind: <tt class="docutils literal"><span class="pre">__ok</span></tt>.</p>
953 struct X {};
956 module(L)
957 [
959 .def(constructor<>()),
962 ];
963 </pre>
966 > a = X()
967 > f(a)
968 > print a.__ok
969 false
970 </pre>
971 <p>When registering a hierarchy of classes, where all instances are to be held
972 by a smart pointer, all the classes should have the baseclass' holder type.
973 Like this:</p>
975 module(L)
976 [
978 .def(constructor<>()),
980 .def(constructor<>())
981 ];
982 </pre>
983 <p>Internally, luabind will do the necessary conversions on the raw pointers, which
984 are first extracted from the holder type.</p>
985 </div>
987 <h2><a name="splitting-class-registrations">8.8 Splitting class registrations</a></h2>
988 <p>In some situations it may be desirable to split a registration of a class
989 across different compilation units. Partly to save rebuild time when changing
990 in one part of the binding, and in some cases compiler limits may force you
991 to split it. To do this is very simple. Consider the following sample code:</p>
994 {
995 x.def(/*...*/);
996 }
999 {
1000 x.def(/*...*/);
1001 }
1003 void register_(lua_State* L)
1004 {
1007 register_part1(x);
1008 register_part2(x);
1010 module(L) [ x ];
1011 }
1012 </pre>
1013 <p>Here, the class <tt class="docutils literal"><span class="pre">X</span></tt> is registered in two steps. The two functions
1014 <tt class="docutils literal"><span class="pre">register_part1</span></tt> and <tt class="docutils literal"><span class="pre">register_part2</span></tt> may be put in separate compilation
1015 units.</p>
1016 <p>To separate the module registration and the classes to be registered, see
1017 <a class="reference" href="#splitting-up-the-registration">Splitting up the registration</a>.</p>
1018 </div>
1019 </div>
1022 <p>Since functions have to be able to take Lua values (of variable type) we need a
1023 wrapper around them. This wrapper is called <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. If the
1024 function you register takes an object, it will match any Lua value. To use it,
1025 you need to include <tt class="docutils literal"><span class="pre"><luabind/object.hpp></span></tt>.</p>
1029 class object
1030 {
1031 public:
1033 object(lua_State*, T const& value);
1034 object(from_stack const&);
1035 object(object const&);
1036 object();
1038 ~object();
1040 lua_State* interpreter() const;
1041 void push() const;
1042 bool is_valid() const;
1052 bool operator==(object const&) const;
1057 bool operator!=(object const&) const;
1062 void swap(object&);
1072 /* ... */
1073 };
1074 </pre>
1075 </div>
1076 <p>When you have a Lua object, you can assign it a new value with the assignment
1077 operator (=). When you do this, the <tt class="docutils literal"><span class="pre">default_policy</span></tt> will be used to make the
1078 conversion from C++ value to Lua. If your <tt class="docutils literal"><span class="pre">luabind::object</span></tt> is a table you
1079 can access its members through the operator[] or the <a class="reference" href="#iterators">Iterators</a>. The value
1080 returned from the operator[] is a proxy object that can be used both for
1081 reading and writing values into the table (using operator=). Note that it is
1082 impossible to know if a Lua value is indexable or not (lua_gettable doesn't
1083 fail, it succeeds or crashes). This means that if you're trying to index
1084 something that cannot be indexed, you're on your own. Lua will call its
1085 <tt class="docutils literal"><span class="pre">panic()</span></tt> function (you can define your own panic function using
1086 <tt class="docutils literal"><span class="pre">lua_setpanicf</span></tt>). There are also free functions that can be used for
1087 indexing the table, see <a class="reference" href="#related-functions">Related functions</a>.</p>
1088 <p>The constructor that takes a <tt class="docutils literal"><span class="pre">from_stack</span></tt> object is used when you want to
1089 initialize the object with a value from the lua stack. The <tt class="docutils literal"><span class="pre">from_stack</span></tt>
1090 type has the following constructor:</p>
1092 from_stack(lua_State* L, int index);
1093 </pre>
1094 <p>The index is an ordinary lua stack index, negative values are indexed from the
1095 top of the stack. You use it like this:</p>
1097 object o(from_stack(L, -1));
1098 </pre>
1099 <p>This will create the object <tt class="docutils literal"><span class="pre">o</span></tt> and copy the value from the top of the lua stack.</p>
1100 <p>The <tt class="docutils literal"><span class="pre">interpreter()</span></tt> function returns the Lua state where this object is stored.
1101 If you want to manipulate the object with Lua functions directly you can push
1102 it onto the Lua stack by calling <tt class="docutils literal"><span class="pre">push()</span></tt>.</p>
1104 <p>The <tt class="docutils literal"><span class="pre">is_valid()</span></tt> function tells you whether the object has been initialized
1105 or not. When created with its default constructor, objects are invalid. To make
1106 an object valid, you can assign it a value. If you want to invalidate an object
1107 you can simply assign it an invalid object.</p>
1108 <!-- So what? implementation detail, leave out of docs
1109 isn't really an implicit cast to bool, but an implicit cast
1110 to a member pointer, since member pointers don't have any arithmetic operators
1111 on them (which can cause hard to find errors). The functionality of the cast
1112 operator -->
1113 <p>The <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">safe_bool_type()</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">is_valid()</span></tt>. This means
1114 that these snippets are equivalent:</p>
1116 object o;
1117 // ...
1118 if (o)
1119 {
1120 // ...
1121 }
1123 ...
1125 object o;
1126 // ...
1127 if (o.is_valid())
1128 {
1129 // ...
1130 }
1131 </pre>
1132 <p>The application operator will call the value as if it was a function. You can
1133 give it any number of parameters (currently the <tt class="docutils literal"><span class="pre">default_policy</span></tt> will be used
1134 for the conversion). The returned object refers to the return value (currently
1135 only one return value is supported). This operator may throw <tt class="docutils literal"><span class="pre">luabind::error</span></tt>
1136 if the function call fails. If you want to specify policies to your function
1137 call, you can use index-operator (operator[]) on the function call, and give
1138 the policies within the [ and ]. Like this:</p>
1140 my_function_object(
1141 2
1142 , 8
1143 , new my_complex_structure(6)
1144 ) [ adopt(_3) ];
1145 </pre>
1146 <p>This tells luabind to make Lua adopt the ownership and responsibility for the
1147 pointer passed in to the lua-function.</p>
1148 <p>It's important that all instances of object have been destructed by the time
1149 the Lua state is closed. The object will keep a pointer to the lua state and
1150 release its Lua object in its destructor.</p>
1153 void my_function(object const& table)
1154 {
1155 if (type(table) == LUA_TTABLE)
1156 {
1161 }
1162 }
1163 </pre>
1164 <p>If you take a <tt class="docutils literal"><span class="pre">luabind::object</span></tt> as a parameter to a function, any Lua value
1165 will match that parameter. That's why we have to make sure it's a table before
1166 we index into it.</p>
1169 <p>There are two kinds of iterators. The normal iterator that will use the metamethod
1170 of the object (if there is any) when the value is retrieved. This iterator is simply
1171 called <tt class="docutils literal"><span class="pre">luabind::iterator</span></tt>. The other iterator is called <tt class="docutils literal"><span class="pre">luabind::raw_iterator</span></tt>
1172 and will bypass the metamethod and give the true contents of the table. They have
1173 identical interfaces, which implements the <a class="reference" href="http://www.sgi.com/tech/stl/ForwardIterator.html">ForwardIterator</a> concept. Apart from
1174 the members of standard iterators, they have the following members and constructors:</p>
1176 class iterator
1177 {
1178 iterator();
1179 iterator(object const&);
1181 object key() const;
1184 };
1185 </pre>
1186 <p>The constructor that takes a <tt class="docutils literal"><span class="pre">luabind::object</span></tt> is actually a template that can be
1187 used with object. Passing an object as the parameter to the iterator will
1188 construct the iterator to refer to the first element in the object.</p>
1189 <p>The default constructor will initialize the iterator to the one-past-end
1190 iterator. This is used to test for the end of the sequence.</p>
1191 <p>The value type of the iterator is an implementation defined proxy type which
1192 supports the same operations as <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. Which means that in most
1193 cases you can just treat it as an ordinary object. The difference is that any
1194 assignments to this proxy will result in the value being inserted at the
1195 iterators position, in the table.</p>
1196 <p>The <tt class="docutils literal"><span class="pre">key()</span></tt> member returns the key used by the iterator when indexing the
1197 associated Lua table.</p>
1201 {
1202 *i = 1;
1203 }
1204 </pre>
1205 <p>The iterator named <tt class="docutils literal"><span class="pre">end</span></tt> will be constructed using the default constructor
1206 and hence refer to the end of the sequence. This example will simply iterate
1207 over the entries in the global table <tt class="docutils literal"><span class="pre">a</span></tt> and set all its values to 1.</p>
1208 </div>
1213 int type(object const&);
1214 </pre>
1215 <p>This function will return the lua type index of the given object.
1216 i.e. <tt class="docutils literal"><span class="pre">LUA_TNIL</span></tt>, <tt class="docutils literal"><span class="pre">LUA_TNUMBER</span></tt> etc.</p>
1226 </pre>
1227 <p>These functions are used for indexing into tables. <tt class="docutils literal"><span class="pre">settable</span></tt> and <tt class="docutils literal"><span class="pre">gettable</span></tt>
1228 translates into calls to <tt class="docutils literal"><span class="pre">lua_settable</span></tt> and <tt class="docutils literal"><span class="pre">lua_gettable</span></tt> respectively. Which
1229 means that you could just as well use the index operator of the object.</p>
1230 <p><tt class="docutils literal"><span class="pre">rawset</span></tt> and <tt class="docutils literal"><span class="pre">rawget</span></tt> will translate into calls to <tt class="docutils literal"><span class="pre">lua_rawset</span></tt> and
1231 <tt class="docutils literal"><span class="pre">lua_rawget</span></tt> respectively. So they will bypass any metamethod and give you the
1232 true value of the table entry.</p>
1243 </pre>
1244 <p>The <tt class="docutils literal"><span class="pre">object_cast</span></tt> function casts the value of an object to a C++ value.
1245 You can supply a policy to handle the conversion from lua to C++. If the cast
1246 cannot be made a <tt class="docutils literal"><span class="pre">cast_failed</span></tt> exception will be thrown. If you have
1247 defined LUABIND_NO_ERROR_CHECKING (see configuration) no checking will occur,
1248 and if the cast is invalid the application may very well crash. The nothrow
1249 versions will return an uninitialized <tt class="docutils literal"><span class="pre">boost::optional<T></span></tt> object, to
1250 indicate that the cast could not be performed.</p>
1251 <p>The function signatures of all of the above functions are really templates
1252 for the object parameter, but the intention is that you should only pass
1253 objects in there, that's why it's left out of the documentation.</p>
1255 object globals(lua_State*);
1256 object registry(lua_State*);
1257 </pre>
1258 <p>These functions return the global environment table and the registry table respectively.</p>
1260 object newtable(lua_State*);
1261 </pre>
1263 </div>
1264 </div>
1267 <p>In addition to binding C++ functions and classes with Lua, luabind also provide
1268 an OO-system in Lua.</p>
1270 class 'lua_testclass'
1272 function lua_testclass:__init(name)
1273 self.name = name
1274 end
1276 function lua_testclass:print()
1277 print(self.name)
1278 end
1280 a = lua_testclass('example')
1281 a:print()
1282 </pre>
1285 class 'derived' (lua_testclass)
1287 function derived:__init() super('derived name')
1288 end
1290 function derived:print()
1291 print('Derived:print() -> ')
1292 lua_testclass.print(self)
1293 end
1294 </pre>
1295 <p>Here the <tt class="docutils literal"><span class="pre">super</span></tt> keyword is used in the constructor to initialize the base
1296 class. The user is required to call <tt class="docutils literal"><span class="pre">super</span></tt> first in the constructor.</p>
1297 <p>As you can see in this example, you can call the base class member functions.
1298 You can find all member functions in the base class, but you will have to give
1299 the this-pointer (<tt class="docutils literal"><span class="pre">self</span></tt>) as first argument.</p>
1302 <p>It is also possible to derive Lua classes from C++ classes, and override
1303 virtual functions with Lua functions. To do this we have to create a wrapper
1304 class for our C++ base class. This is the class that will hold the Lua object
1305 when we instantiate a Lua class.</p>
1307 class base
1308 {
1309 public:
1310 base(const char* s)
1313 virtual void f(int a)
1315 };
1317 struct base_wrapper : base, luabind::wrap_base
1318 {
1319 base_wrapper(const char* s)
1320 : base(s)
1321 {}
1323 virtual void f(int a)
1324 {
1326 }
1328 static void default_f(base* ptr, int a)
1329 {
1330 return ptr->base::f(a);
1331 }
1332 };
1334 ...
1336 module(L)
1337 [
1341 ];
1342 </pre>
1346 to member functions, instead of using the member function <tt class="docutils literal"><span class="pre">call()</span></tt>
1347 you call a free function <tt class="docutils literal"><span class="pre">call_member()</span></tt> and pass the this-pointer
1348 as first parameter.</p>
1349 </div>
1350 <p>Note that if you have both base classes and a base class wrapper, you must give
1351 both bases and the base class wrapper type as template parameter to
1352 <tt class="docutils literal"><span class="pre">class_</span></tt> (as done in the example above). The order in which you specify
1353 them is not important. You must also register both the static version and the
1354 virtual version of the function from the wrapper, this is necessary in order
1355 to allow luabind to use both dynamic and static dispatch when calling the function.</p>
1359 is identical to the virtual function. The fact that one of them is a free
1360 function and the other a member function doesn't matter, but the parameters
1361 as seen from lua must match. It would not have worked if the static function
1362 took a <tt class="docutils literal"><span class="pre">base_wrapper*</span></tt> as its first argument, since the virtual function
1363 takes a <tt class="docutils literal"><span class="pre">base*</span></tt> as its first argument (its this pointer). There's currently
1364 no check in luabind to make sure the signatures match.</p>
1365 </div>
1366 <p>If we didn't have a class wrapper, it would not be possible to pass a Lua class
1367 back to C++. Since the entry points of the virtual functions would still point
1368 to the C++ base class, and not to the functions defined in Lua. That's why we
1369 need one function that calls the base class' real function (used if the lua
1370 class doesn't redefine it) and one virtual function that dispatches the call
1371 into luabind, to allow it to select if a Lua function should be called, or if
1372 the original function should be called. If you don't intend to derive from a
1373 C++ class, or if it doesn't have any virtual member functions, you can register
1374 it without a class wrapper.</p>
1375 <p>You don't need to have a class wrapper in order to derive from a class, but if
1376 it has virtual functions you may have silent errors.</p>
1377 <!-- Unnecessary? The rule of thumb is:
1378 If your class has virtual functions, create a wrapper type, if it doesn't
1379 don't create a wrapper type. -->
1380 <p>The wrappers must derive from <tt class="docutils literal"><span class="pre">luabind::wrap_base</span></tt>, it contains a Lua reference
1381 that will hold the Lua instance of the object to make it possible to dispatch
1382 virtual function calls into Lua. This is done through an overloaded member function:</p>
1385 Ret call(char const* name, ...)
1386 </pre>
1387 <p>Its used in a similar way as <tt class="docutils literal"><span class="pre">call_function</span></tt>, with the exception that it doesn't
1388 take a <tt class="docutils literal"><span class="pre">lua_State</span></tt> pointer, and the name is a member function in the Lua class.</p>
1391 <p class="last">The current implementation of <tt class="docutils literal"><span class="pre">call_member</span></tt> is not able to distinguish const
1392 member functions from non-const. If you have a situation where you have an overloaded
1393 virtual function where the only difference in their signatures is their constness, the
1394 wrong overload will be called by <tt class="docutils literal"><span class="pre">call_member</span></tt>. This is rarely the case though.</p>
1395 </div>
1398 <p>When a pointer or reference to a registered class with a wrapper is passed
1399 to Lua, luabind will query for it's dynamic type. If the dynamic type
1400 inherits from <tt class="docutils literal"><span class="pre">wrap_base</span></tt>, object identity is preserved.</p>
1402 struct A { .. };
1403 struct A_wrap : A, wrap_base { .. };
1405 A* f(A* ptr) { return ptr; }
1407 module(L)
1408 [
1411 ];
1412 </pre>
1414 > class 'B' (A)
1415 > x = B()
1416 > assert(x == f(x)) -- object identity is preserved when object is
1417 -- passed through C++
1418 </pre>
1419 <p>This functionality relies on RTTI being enabled (that <tt class="docutils literal"><span class="pre">LUABIND_NO_RTTI</span></tt> is
1420 not defined).</p>
1421 </div>
1422 </div>
1425 <p>You can overload most operators in Lua for your classes. You do this by simply
1426 declaring a member function with the same name as an operator (the name of the
1427 metamethods in Lua). The operators you can overload are:</p>
1428 <blockquote>
1441 </ul>
1442 </blockquote>
1443 <p><tt class="docutils literal"><span class="pre">__tostring</span></tt> isn't really an operator, but it's the metamethod that is called
1444 by the standard library's <tt class="docutils literal"><span class="pre">tostring()</span></tt> function. There's one strange behavior
1445 regarding binary operators. You are not guaranteed that the self pointer you
1446 get actually refers to an instance of your class. This is because Lua doesn't
1447 distinguish the two cases where you get the other operand as left hand value or
1448 right hand value. Consider the following examples:</p>
1450 class 'my_class'
1452 function my_class:__init(v)
1453 self.val = v
1454 end
1456 function my_class:__sub(v)
1457 return my_class(self.val - v.val)
1458 end
1460 function my_class:__tostring()
1461 return self.val
1462 end
1463 </pre>
1464 <p>This will work well as long as you only subtracts instances of my_class with
1465 each other. But If you want to be able to subtract ordinary numbers from your
1466 class too, you have to manually check the type of both operands, including the
1467 self object.</p>
1469 function my_class:__sub(v)
1470 if (type(self) == 'number') then
1471 return my_class(self - v.val)
1473 elseif (type(v) == 'number') then
1474 return my_class(self.val - v)
1476 else
1477 -- assume both operands are instances of my_class
1478 return my_class(self.val - v.val)
1480 end
1481 end
1482 </pre>
1483 <p>The reason why <tt class="docutils literal"><span class="pre">__sub</span></tt> is used as an example is because subtraction is not
1484 commutative (the order of the operands matter). That's why luabind cannot
1485 change order of the operands to make the self reference always refer to the
1486 actual class instance.</p>
1487 <p>If you have two different Lua classes with an overloaded operator, the operator
1488 of the right hand side type will be called. If the other operand is a C++ class
1489 with the same operator overloaded, it will be prioritized over the Lua class'
1490 operator. If none of the C++ overloads matches, the Lua class operator will be
1491 called.</p>
1492 </div>
1495 <p>If an object needs to perform actions when it's collected we provide a
1496 <tt class="docutils literal"><span class="pre">__finalize</span></tt> function that can be overridden in lua-classes. The
1497 <tt class="docutils literal"><span class="pre">__finalize</span></tt> functions will be called on all classes in the inheritance
1498 chain, starting with the most derived type.</p>
1500 ...
1502 function lua_testclass:__finalize()
1503 -- called when the an object is collected
1504 end
1505 </pre>
1506 </div>
1509 <p>If your lua C++ classes don't have wrappers (see <a class="reference" href="#deriving-in-lua">Deriving in lua</a>) and
1510 you derive from them in lua, they may be sliced. Meaning, if an object
1511 is passed into C++ as a pointer to its base class, the lua part will be
1512 separated from the C++ base part. This means that if you call virtual
1513 functions on that C++ object, they will not be dispatched to the lua
1514 class. It also means that if you adopt the object, the lua part will be
1515 garbage collected.</p>
1517 +--------------------+
1518 | C++ object | <- ownership of this part is transferred
1519 | | to c++ when adopted
1520 +--------------------+
1521 | lua class instance | <- this part is garbage collected when
1522 | and lua members | instance is adopted, since it cannot
1523 +--------------------+ be held by c++.
1524 </pre>
1527 struct A {};
1529 A* filter_a(A* a) { return a; }
1530 void adopt_a(A* a) { delete a; }
1531 </pre>
1533 using namespace luabind;
1535 module(L)
1536 [
1540 ]
1541 </pre>
1544 a = A()
1545 b = filter_a(a)
1546 adopt_a(b)
1547 </pre>
1548 <p>In this example, lua cannot know that <tt class="docutils literal"><span class="pre">b</span></tt> actually is the same object as
1549 <tt class="docutils literal"><span class="pre">a</span></tt>, and it will therefore consider the object to be owned by the C++ side.
1550 When the <tt class="docutils literal"><span class="pre">b</span></tt> pointer then is adopted, a runtime error will be raised because
1551 an object not owned by lua is being adopted to C++.</p>
1552 <p>If you have a wrapper for your class, none of this will happen, see
1554 </div>
1555 </div>
1558 <p>If any of the functions you register throws an exception when called, that
1559 exception will be caught by luabind and converted to an error string and
1560 <tt class="docutils literal"><span class="pre">lua_error()</span></tt> will be invoked. If the exception is a <tt class="docutils literal"><span class="pre">std::exception</span></tt> or a
1561 <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt> the string that is pushed on the Lua stack, as error message,
1562 will be the string returned by <tt class="docutils literal"><span class="pre">std::exception::what()</span></tt> or the string itself
1563 respectively. If the exception is unknown, a generic string saying that the
1564 function threw an exception will be pushed.</p>
1565 <p>Exceptions thrown from user defined functions have to be caught by luabind. If
1566 they weren't they would be thrown through Lua itself, which is usually compiled
1567 as C code and doesn't support the stack-unwinding that exceptions imply.</p>
1568 <p>Any function that invokes Lua code may throw <tt class="docutils literal"><span class="pre">luabind::error</span></tt>. This exception
1569 means that a Lua run-time error occurred. The error message is found on top of
1570 the Lua stack. The reason why the exception doesn't contain the error string
1571 itself is because it would then require heap allocation which may fail. If an
1572 exception class throws an exception while it is being thrown itself, the
1573 application will be terminated.</p>
1576 class error : public std::exception
1577 {
1578 public:
1579 error(lua_State*);
1580 lua_State* state() const throw();
1581 virtual const char* what() const throw();
1582 };
1583 </pre>
1584 <p>The state function returns a pointer to the Lua state in which the error was
1585 thrown. This pointer may be invalid if you catch this exception after the lua
1586 state is destructed. If the Lua state is valid you can use it to retrieve the
1587 error message from the top of the Lua stack.</p>
1588 <p>An example of where the Lua state pointer may point to an invalid state
1589 follows:</p>
1591 struct lua_state
1592 {
1593 lua_state(lua_State* L): m_L(L) {}
1594 ~lua_state() { lua_close(m_L); }
1595 operator lua_State*() { return m_L; }
1596 lua_State* m_L;
1597 };
1599 int main()
1600 {
1601 try
1602 {
1603 lua_state L = lua_open();
1604 /* ... */
1605 }
1606 catch(luabind::error& e)
1607 {
1608 lua_State* L = e.state();
1609 // L will now point to the destructed
1610 // Lua state and be invalid
1611 /* ... */
1612 }
1613 }
1614 </pre>
1615 <p>There's another exception that luabind may throw: <tt class="docutils literal"><span class="pre">luabind::cast_failed</span></tt>,
1616 this exception is thrown from <tt class="docutils literal"><span class="pre">call_function<></span></tt> or <tt class="docutils literal"><span class="pre">call_member<></span></tt>. It
1617 means that the return value from the Lua function couldn't be converted to
1618 a C++ value. It is also thrown from <tt class="docutils literal"><span class="pre">object_cast<></span></tt> if the cast cannot
1619 be made.</p>
1620 <p>The synopsis for <tt class="docutils literal"><span class="pre">luabind::cast_failed</span></tt> is:</p>
1622 class cast_failed : public std::exception
1623 {
1624 public:
1625 cast_failed(lua_State*);
1626 lua_State* state() const throw();
1627 LUABIND_TYPE_INFO info() const throw();
1628 virtual const char* what() const throw();
1629 };
1630 </pre>
1631 <p>Again, the state member function returns a pointer to the Lua state where the
1632 error occurred. See the example above to see where this pointer may be invalid.</p>
1633 <p>The info member function returns the user defined <tt class="docutils literal"><span class="pre">LUABIND_TYPE_INFO</span></tt>, which
1634 defaults to a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">std::type_info*</span></tt>. This type info describes the type that
1635 we tried to cast a Lua value to.</p>
1636 <p>If you have defined <tt class="docutils literal"><span class="pre">LUABIND_NO_EXCEPTIONS</span></tt> none of these exceptions will be
1637 thrown, instead you can set two callback functions that are called instead.
1638 These two functions are only defined if <tt class="docutils literal"><span class="pre">LUABIND_NO_EXCEPTIONS</span></tt> are defined.</p>
1640 luabind::set_error_callback(void(*)(lua_State*))
1641 </pre>
1642 <p>The function you set will be called when a runtime-error occur in Lua code. You
1643 can find an error message on top of the Lua stack. This function is not
1644 expected to return, if it does luabind will call <tt class="docutils literal"><span class="pre">std::terminate()</span></tt>.</p>
1646 luabind::set_cast_failed_callback(void(*)(lua_State*, LUABIND_TYPE_INFO))
1647 </pre>
1648 <p>The function you set is called instead of throwing <tt class="docutils literal"><span class="pre">cast_failed</span></tt>. This function
1649 is not expected to return, if it does luabind will call <tt class="docutils literal"><span class="pre">std::terminate()</span></tt>.</p>
1650 </div>
1653 <p>Sometimes it is necessary to control how luabind passes arguments and return
1654 value, to do this we have policies. All policies use an index to associate
1655 them with an argument in the function signature. These indices are <tt class="docutils literal"><span class="pre">result</span></tt>
1656 and <tt class="docutils literal"><span class="pre">_N</span></tt> (where <tt class="docutils literal"><span class="pre">N</span> <span class="pre">>=</span> <span class="pre">1</span></tt>). When dealing with member functions <tt class="docutils literal"><span class="pre">_1</span></tt> refers
1659 <p class="topic-title first"><a name="policies-currently-implemented">Policies currently implemented</a></p>
1661 <li><a class="reference" href="#adopt" id="id93" name="id93">12.1 adopt</a></li>
1662 <li><a class="reference" href="#dependency" id="id94" name="id94">12.2 dependency</a></li>
1663 <li><a class="reference" href="#out-value" id="id95" name="id95">12.3 out_value</a></li>
1664 <li><a class="reference" href="#pure-out-value" id="id96" name="id96">12.4 pure_out_value</a></li>
1665 <li><a class="reference" href="#return-reference-to" id="id97" name="id97">12.5 return_reference_to</a></li>
1666 <li><a class="reference" href="#copy" id="id98" name="id98">12.6 copy</a></li>
1667 <li><a class="reference" href="#discard-result" id="id99" name="id99">12.7 discard_result</a></li>
1668 <li><a class="reference" href="#return-stl-iterator" id="id100" name="id100">12.8 return_stl_iterator</a></li>
1669 <li><a class="reference" href="#raw" id="id101" name="id101">12.9 raw</a></li>
1670 <li><a class="reference" href="#yield" id="id102" name="id102">12.10 yield</a></li>
1671 </ul>
1672 </div>
1678 </div>
1683 </pre>
1684 </div>
1688 adopt(index)
1689 </pre>
1690 </div>
1694 <colgroup>
1697 </colgroup>
1701 </tr>
1702 </thead>
1705 <td>The index which should transfer ownership, <tt class="docutils literal"><span class="pre">_N</span></tt> or <tt class="docutils literal"><span class="pre">result</span></tt></td>
1706 </tr>
1707 </tbody>
1708 </table>
1709 </div>
1713 X* create()
1714 {
1715 return new X;
1716 }
1718 ...
1720 module(L)
1721 [
1723 ];
1724 </pre>
1725 </div>
1726 </div>
1728 <h2><a class="toc-backref" href="#id94" name="dependency">12.2 dependency</a></h2>
1731 <p>The dependency policy is used to create life-time dependencies between values.
1732 This is needed for example when returning internal references to some class.</p>
1733 </div>
1738 </pre>
1739 </div>
1743 dependency(nurse_index, patient_index)
1744 </pre>
1745 </div>
1749 <colgroup>
1752 </colgroup>
1756 </tr>
1757 </thead>
1761 </tr>
1764 </tr>
1765 </tbody>
1766 </table>
1767 </div>
1771 struct X
1772 {
1773 B member;
1774 B& get() { return member; }
1775 };
1777 module(L)
1778 [
1781 ];
1782 </pre>
1783 </div>
1784 </div>
1786 <h2><a class="toc-backref" href="#id95" name="out-value">12.3 out_value</a></h2>
1789 <p>This policy makes it possible to wrap functions that take non-const references
1790 or pointer to non-const as it's parameters with the intention to write return
1791 values to them.</p>
1792 </div>
1797 </pre>
1798 </div>
1802 out_value(index, policies = none)
1803 </pre>
1804 </div>
1808 <colgroup>
1811 </colgroup>
1815 </tr>
1816 </thead>
1820 </tr>
1822 <td>The policies used internally to convert the out parameter
1823 to/from Lua. <tt class="docutils literal"><span class="pre">_1</span></tt> means <strong>to</strong> C++, <tt class="docutils literal"><span class="pre">_2</span></tt> means <strong>from</strong>
1824 C++.</td>
1825 </tr>
1826 </tbody>
1827 </table>
1828 </div>
1833 void f2(float* val) { *val = *val + 10.f; }
1835 module(L)
1836 [
1838 ];
1842 20
1844 20
1845 </pre>
1846 </div>
1847 </div>
1849 <h2><a class="toc-backref" href="#id96" name="pure-out-value">12.4 pure_out_value</a></h2>
1852 <p>This works exactly like <tt class="docutils literal"><span class="pre">out_value</span></tt>, except that it will pass a
1853 default constructed object instead of converting an argument from
1854 Lua.</p>
1855 </div>
1860 </pre>
1861 </div>
1865 pure_out_value(index, policies = none)
1866 </pre>
1867 </div>
1871 <colgroup>
1874 </colgroup>
1878 </tr>
1879 </thead>
1883 </tr>
1885 <td>The policies used internally to convert the out parameter
1886 to Lua. <tt class="docutils literal"><span class="pre">_1</span></tt> is used as the internal index.</td>
1887 </tr>
1888 </tbody>
1889 </table>
1890 </div>
1895 void f2(float* val) { *val = 10.f; }
1897 module(L)
1898 [
1900 ];
1903 > print(f1())
1904 10
1905 > print(f2())
1906 10
1907 </pre>
1908 </div>
1909 </div>
1911 <h2><a class="toc-backref" href="#id97" name="return-reference-to">12.5 return_reference_to</a></h2>
1914 <p>It is very common to return references to arguments or the this-pointer to
1915 allow for chaining in C++.</p>
1917 struct A
1918 {
1919 float val;
1921 A& set(float v)
1922 {
1923 val = v;
1924 return *this;
1925 }
1926 };
1927 </pre>
1928 <p>When luabind generates code for this, it will create a new object for the
1929 return-value, pointing to the self-object. This isn't a problem, but could be a
1930 bit inefficient. When using the return_reference_to-policy we have the ability
1931 to tell luabind that the return-value is already on the lua stack.</p>
1932 </div>
1937 </pre>
1938 </div>
1942 return_reference_to(index)
1943 </pre>
1944 </div>
1948 <colgroup>
1951 </colgroup>
1955 </tr>
1956 </thead>
1959 <td>The argument index to return a reference to, any argument but
1961 </tr>
1962 </tbody>
1963 </table>
1964 </div>
1968 struct A
1969 {
1970 float val;
1972 A& set(float v)
1973 {
1974 val = v;
1975 return *this;
1976 }
1977 };
1979 module(L)
1980 [
1982 .def(constructor<>())
1984 ];
1985 </pre>
1989 situations where the parameter type is a perfect match to the
1990 return-type (such as in the example).</p>
1991 </div>
1992 </div>
1993 </div>
1998 <p>This will make a copy of the parameter. This is the default behavior when
1999 passing parameters by-value. Note that this can only be used when passing from
2000 C++ to Lua. This policy requires that the parameter type has an accessible copy
2001 constructor.</p>
2002 </div>
2007 </pre>
2008 </div>
2012 copy(index)
2013 </pre>
2014 </div>
2018 <colgroup>
2021 </colgroup>
2025 </tr>
2026 </thead>
2029 <td>The index to copy. <tt class="docutils literal"><span class="pre">result</span></tt> when used while wrapping C++
2030 functions. <tt class="docutils literal"><span class="pre">_N</span></tt> when passing arguments to Lua.</td>
2031 </tr>
2032 </tbody>
2033 </table>
2034 </div>
2038 X* get()
2039 {
2040 static X instance;
2041 return &instance;
2042 }
2044 ...
2046 module(L)
2047 [
2049 ];
2050 </pre>
2051 </div>
2052 </div>
2054 <h2><a class="toc-backref" href="#id99" name="discard-result">12.7 discard_result</a></h2>
2057 <p>This is a very simple policy which makes it possible to throw away
2058 the value returned by a C++ function, instead of converting it to
2059 Lua.</p>
2060 </div>
2065 </pre>
2066 </div>
2070 discard_result
2071 </pre>
2072 </div>
2076 struct X
2077 {
2078 X& set(T n)
2079 {
2080 ...
2081 return *this;
2082 }
2083 };
2085 ...
2087 module(L)
2088 [
2091 ];
2092 </pre>
2093 </div>
2094 </div>
2096 <h2><a class="toc-backref" href="#id100" name="return-stl-iterator">12.8 return_stl_iterator</a></h2>
2099 <p>This policy converts an STL container to a generator function that can be used
2100 in lua to iterate over the container. It works on any container that defines
2101 <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> member functions (they have to return iterators).</p>
2102 </div>
2107 </pre>
2108 </div>
2112 return_stl_iterator
2113 </pre>
2114 </div>
2118 struct X
2119 {
2121 };
2123 ...
2125 module(L)
2126 [
2129 ];
2131 ...
2133 > a = A()
2134 > for name in a.names do
2135 > print(name)
2136 > end
2137 </pre>
2138 </div>
2139 </div>
2144 <p>This converter policy will pass through the <tt class="docutils literal"><span class="pre">lua_State*</span></tt> unmodified.
2145 This can be useful for example when binding functions that need to
2146 return a <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. The parameter will be removed from the
2147 function signature, decreasing the function arity by one.</p>
2148 </div>
2153 </pre>
2154 </div>
2158 raw(index)
2159 </pre>
2160 </div>
2164 <colgroup>
2167 </colgroup>
2171 </tr>
2172 </thead>
2176 </tr>
2177 </tbody>
2178 </table>
2179 </div>
2183 void greet(lua_State* L)
2184 {
2186 }
2188 ...
2190 module(L)
2191 [
2193 ];
2195 > print(greet())
2196 hello
2197 </pre>
2198 </div>
2199 </div>
2205 </div>
2210 </pre>
2211 </div>
2215 yield
2216 </pre>
2217 </div>
2221 void do_thing_that_takes_time()
2222 {
2223 ...
2224 }
2226 ...
2228 module(L)
2229 [
2230 def("do_thing_that_takes_time", &do_thing_that_takes_time, <strong>yield</strong>)
2231 ];
2232 </pre>
2233 <!-- old policies section
2234 ===================================================
2236 Copy
2237 - - - -
2239 This will make a copy of the parameter. This is the default behavior when
2240 passing parameters by-value. Note that this can only be used when passing from
2241 C++ to Lua. This policy requires that the parameter type has a copy
2242 constructor.
2244 To use this policy you need to include ``luabind/copy_policy.hpp``.
2247 Adopt
2248 - - - - -
2250 This will transfer ownership of the parameter.
2252 Consider making a factory function in C++ and exposing it to lua::
2254 base* create_base()
2255 {
2256 return new base();
2257 }
2259 ...
2261 module(L)
2262 [
2263 def("create_base", create_base)
2264 ];
2266 Here we need to make sure Lua understands that it should adopt the pointer
2267 returned by the factory-function. This can be done using the adopt-policy.
2269 ::
2271 module(L)
2272 [
2273 def(L, "create_base", adopt(return_value))
2274 ];
2276 To specify multiple policies we just separate them with '+'.
2278 ::
2280 base* set_and_get_new(base* ptr)
2281 {
2282 base_ptrs.push_back(ptr);
2283 return new base();
2284 }
2286 module(L)
2287 [
2288 def("set_and_get_new", &set_and_get_new,
2289 adopt(return_value) + adopt(_1))
2290 ];
2292 When Lua adopts a pointer, it will call delete on it. This means that it cannot
2293 adopt pointers allocated with another allocator than new (no malloc for
2294 example).
2296 To use this policy you need to include ``luabind/adopt_policy.hpp``.
2299 Dependency
2300 - - - - - - - - - -
2302 The dependency policy is used to create life-time dependencies between values.
2303 Consider the following example::
2305 struct A
2306 {
2307 B member;
2309 const B& get_member()
2310 {
2311 return member;
2312 }
2313 };
2315 When wrapping this class, we would do something like::
2317 module(L)
2318 [
2319 class_<A>("A")
2320 .def(constructor<>())
2321 .def("get_member", &A::get_member)
2322 ];
2325 However, since the return value of get_member is a reference to a member of A,
2326 this will create some life-time issues. For example::
2328 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2329 a = A()
2330 b = a:get_member() - - b points to a member of a
2331 a = nil
2332 collectgarbage(0) - - since there are no references left to a, it is
2333 - - removed
2334 - - at this point, b is pointing into a removed object
2336 When using the dependency-policy, it is possible to tell luabind to tie the
2337 lifetime of one object to another, like this::
2339 module(L)
2340 [
2341 class_<A>("A")
2342 .def(constructor<>())
2343 .def("get_member", &A::get_member, dependency(result, _1))
2344 ];
2346 This will create a dependency between the return-value of the function, and the
2347 self-object. This means that the self-object will be kept alive as long as the
2348 result is still alive. ::
2350 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2351 a = A()
2352 b = a:get_member() - - b points to a member of a
2353 a = nil
2354 collectgarbage(0) - - a is dependent on b, so it isn't removed
2355 b = nil
2356 collectgarbage(0) - - all dependencies to a gone, a is removed
2358 To use this policy you need to include ``luabind/dependency_policy.hpp``.
2361 Return reference to
2362 - - - - - - - - - - - - - - - - - - -
2364 It is very common to return references to arguments or the this-pointer to
2365 allow for chaining in C++.
2367 ::
2369 struct A
2370 {
2371 float val;
2373 A& set(float v)
2374 {
2375 val = v;
2376 return *this;
2377 }
2378 };
2380 When luabind generates code for this, it will create a new object for the
2381 return-value, pointing to the self-object. This isn't a problem, but could be a
2382 bit inefficient. When using the return_reference_to-policy we have the ability
2383 to tell luabind that the return-value is already on the Lua stack.
2385 ::
2387 module(L)
2388 [
2389 class_<A>("A")
2390 .def(constructor<>())
2391 .def("set", &A::set, return_reference_to(_1))
2392 ];
2394 Instead of creating a new object, luabind will just copy the object that is
2395 already on the stack.
2397 .. warning::
2398 This policy ignores all type information and should be used only it
2399 situations where the parameter type is a perfect match to the
2400 return-type (such as in the example).
2402 To use this policy you need to include ``luabind/return_reference_to_policy.hpp``.
2405 Out value
2406 - - - - - - - - -
2408 This policy makes it possible to wrap functions that take non const references
2409 as its parameters with the intention to write return values to them.
2411 ::
2413 void f(float& val) { val = val + 10.f; }
2415 or
2417 ::
2419 void f(float* val) { *val = *val + 10.f; }
2421 Can be wrapped by doing::
2423 module(L)
2424 [
2425 def("f", &f, out_value(_1))
2426 ];
2428 When invoking this function from Lua it will return the value assigned to its
2429 parameter.
2431 ::
2433 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2434 > a = f(10)
2435 > print(a)
2436 20
2438 When this policy is used in conjunction with user define types we often need
2439 to do ownership transfers.
2441 ::
2443 struct A;
2445 void f1(A*& obj) { obj = new A(); }
2446 void f2(A** obj) { *obj = new A(); }
2448 Here we need to make sure luabind takes control over object returned, for
2449 this we use the adopt policy::
2451 module(L)
2452 [
2453 class_<A>("A"),
2454 def("f1", &f1, out_value(_1, adopt(_2)))
2455 def("f2", &f2, out_value(_1, adopt(_2)))
2456 ];
2458 Here we are using adopt as an internal policy to out_value. The index
2459 specified, _2, means adopt will be used to convert the value back to Lua.
2460 Using _1 means the policy will be used when converting from Lua to C++.
2462 To use this policy you need to include ``luabind/out_value_policy.hpp``.
2464 Pure out value
2465 - - - - - - - - - - - - - -
2467 This policy works in exactly the same way as out_value, except that it
2468 replaces the parameters with default-constructed objects.
2470 ::
2472 void get(float& x, float& y)
2473 {
2474 x = 3.f;
2475 y = 4.f;
2476 }
2478 ...
2480 module(L)
2481 [
2482 def("get", &get,
2483 pure_out_value(_1) + pure_out_value(_2))
2484 ];
2486 ::
2488 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2489 > x, y = get()
2490 > print(x, y)
2491 3 5
2493 Like out_value, it is possible to specify an internal policy used then
2494 converting the values back to Lua.
2496 ::
2498 void get(test_class*& obj)
2499 {
2500 obj = new test_class();
2501 }
2503 ...
2505 module(L)
2506 [
2507 def("get", &get, pure_out_value(_1, adopt(_1)))
2508 ];
2511 Discard result
2512 - - - - - - - - - - - - - -
2514 This is a very simple policy which makes it possible to throw away
2515 the value returned by a C++ function, instead of converting it to
2516 Lua. This example makes sure the this reference never gets converted
2517 to Lua.
2519 ::
2521 struct simple
2522 {
2523 simple& set_name(const std::string& n)
2524 {
2525 name = n;
2526 return *this;
2527 }
2529 std::string name;
2530 };
2532 ...
2534 module(L)
2535 [
2536 class_<simple>("simple")
2537 .def("set_name", &simple::set_name, discard_result)
2538 ];
2540 To use this policy you need to include ``luabind/discard_result_policy.hpp``.
2543 Return STL iterator
2544 - - - - - - - - - - - - - - - - - - -
2546 This policy converts an STL container to a generator function that can be used
2547 in Lua to iterate over the container. It works on any container that defines
2548 ``begin()`` and ``end()`` member functions (they have to return iterators). It
2549 can be used like this::
2551 struct A
2552 {
2553 std::vector<std::string> names;
2554 };
2557 module(L)
2558 [
2559 class_<A>("A")
2560 .def_readwrite("names", &A::names, return_stl_iterator)
2561 ];
2563 The Lua code to iterate over the container::
2565 a = A()
2567 for name in a.names do
2568 print(name)
2569 end
2572 To use this policy you need to include ``luabind/iterator_policy.hpp``.
2575 Yield
2576 - - - - -
2578 This policy will cause the function to always yield the current thread when
2579 returning. See the Lua manual for restrictions on yield. -->
2580 </div>
2581 </div>
2582 </div>
2584 <h1><a name="splitting-up-the-registration">13 Splitting up the registration</a></h1>
2585 <p>It is possible to split up a module registration into several
2586 translation units without making each registration dependent
2587 on the module it's being registered in.</p>
2590 luabind::scope register_a()
2591 {
2592 return
2595 ;
2596 }
2597 </pre>
2600 luabind::scope register_b()
2601 {
2602 return
2605 ;
2606 }
2607 </pre>
2610 luabind::scope register_a();
2611 luabind::scope register_b();
2613 void register_module(lua_State* L)
2614 {
2616 [
2617 register_a(),
2618 register_b()
2619 ];
2620 }
2621 </pre>
2622 </div>
2625 <p>As mentioned in the <a class="reference" href="http://www.lua.org/manual/5.0/manual.html">Lua documentation</a>, it is possible to pass an
2626 error handler function to <tt class="docutils literal"><span class="pre">lua_pcall()</span></tt>. Luabind makes use of
2627 <tt class="docutils literal"><span class="pre">lua_pcall()</span></tt> internally when calling member functions and free functions.
2628 It is possible to set the error handler function that Luabind will use
2629 globally:</p>
2631 typedef void(*pcall_callback_fun)(lua_State*);
2632 void set_pcall_callback(pcall_callback_fun fn);
2633 </pre>
2634 <p>This is primarily useful for adding more information to the error message
2635 returned by a failed protected call.</p>
2638 <p>There are a number of configuration options available when building luabind.
2639 It is very important that your project has the exact same configuration
2640 options as the ones given when the library was build! The exceptions are the
2641 <tt class="docutils literal"><span class="pre">LUABIND_MAX_ARITY</span></tt> and <tt class="docutils literal"><span class="pre">LUABIND_MAX_BASES</span></tt> which are template-based
2642 options and only matters when you use the library (which means they can
2643 differ from the settings of the library).</p>
2644 <p>The default settings which will be used if no other settings are given
2645 can be found in <tt class="docutils literal"><span class="pre">luabind/config.hpp</span></tt>.</p>
2646 <p>If you want to change the settings of the library, you can modify the
2647 config file. It is included and used by all makefiles. You can change paths
2648 to Lua and boost in there as well.</p>
2651 <dd>Controls the maximum arity of functions that are registered with luabind.
2652 You can't register functions that takes more parameters than the number
2653 this macro is set to. It defaults to 5, so, if your functions have greater
2654 arity you have to redefine it. A high limit will increase compilation time.</dd>
2656 <dd>Controls the maximum number of classes one class can derive from in
2657 luabind (the number of classes specified within <tt class="docutils literal"><span class="pre">bases<></span></tt>).
2658 <tt class="docutils literal"><span class="pre">LUABIND_MAX_BASES</span></tt> defaults to 4. A high limit will increase
2659 compilation time.</dd>
2662 calls. If illegal function calls are made (e.g. giving parameters that
2663 doesn't match the function signature) they will not be detected by luabind
2664 and the application will probably crash. Error checking could be disabled
2665 when shipping a release build (given that no end-user has access to write
2666 custom Lua code). Note that function parameter matching will be done if a
2667 function is overloaded, since otherwise it's impossible to know which one
2668 was called. Functions will still be able to throw exceptions when error
2669 checking is disabled.</p>
2672 </dd>
2675 This will in many cases disable run-time errors, when performing invalid
2676 casts or calling Lua functions that fails or returns values that cannot
2677 be converted by the given policy. luabind requires that no function called
2678 directly or indirectly by luabind throws an exception (throwing exceptions
2679 through Lua has undefined behavior).</p>
2681 they will be replaced with calls to the callback functions set with
2682 <tt class="docutils literal"><span class="pre">set_error_callback()</span></tt> and <tt class="docutils literal"><span class="pre">set_cast_failed_callback()</span></tt>.</p>
2683 </dd>
2685 <dd>If you want to link dynamically against Lua, you can set this define to
2686 the import-keyword on your compiler and platform. On windows in devstudio
2687 this should be <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt> if you want to link against Lua
2688 as a dll.</dd>
2690 <dd>If you want to link against luabind as a dll (in devstudio), you can
2691 define <tt class="docutils literal"><span class="pre">LUABIND_EXPORT</span></tt> to <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> and
2692 <tt class="docutils literal"><span class="pre">LUABIND_IMPORT</span></tt> to <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt> or
2693 <tt class="docutils literal"><span class="pre">__attribute__</span> <span class="pre">((visibility("default")))</span></tt> on GCC 4.
2694 Note that you have to link against Lua as a dll aswell, to make it work.</dd>
2696 <dd>You can define this if you don't want luabind to use <tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt>.
2698 <dt>LUABIND_TYPE_INFO, LUABIND_TYPE_INFO_EQUAL(i1,i2), LUABIND_TYPEID(t), LUABIND_INVALID_TYPE_INFO</dt>
2700 type-info structure with the <tt class="docutils literal"><span class="pre">LUABIND_TYPE_INFO</span></tt> define. Your type-info
2701 structure must be copyable and must be able to compare itself against
2702 other type-info structures. You supply the compare function through the
2703 <tt class="docutils literal"><span class="pre">LUABIND_TYPE_INFO_EQUAL()</span></tt> define. It should compare the two type-info
2704 structures it is given and return true if they represent the same type and
2705 false otherwise. You also have to supply a function to generate your
2706 type-info structure. You do this through the <tt class="docutils literal"><span class="pre">LUABIND_TYPEID()</span></tt> define.
2707 It should return your type-info structure and it takes a type as its
2708 parameter. That is, a compile time parameter.
2709 <tt class="docutils literal"><span class="pre">LUABIND_INVALID_TYPE_INFO</span></tt> macro should be defined to an invalid type.
2710 No other type should be able to produce this type info. To use it you
2711 probably have to make a traits class with specializations for all classes
2712 that you have type-info for. Like this:</p>
2714 class A;
2715 class B;
2716 class C;
2723 </pre>
2724 <p>If you have set up your own RTTI system like this (by using integers to
2725 identify types) you can have luabind use it with the following defines:</p>
2727 #define LUABIND_TYPE_INFO const std::type_info*
2728 #define LUABIND_TYPEID(t) &typeid(t)
2729 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
2730 #define LUABIND_INVALID_TYPE_INFO &typeid(detail::null_type)
2731 </pre>
2732 <p class="last">Currently the type given through <tt class="docutils literal"><span class="pre">LUABIND_TYPE_INFO</span></tt> must be less-than
2733 comparable!</p>
2734 </dd>
2736 <dd>This define will disable all asserts and should be defined in a release
2737 build.</dd>
2738 </dl>
2739 </div>
2740 </div>
2743 <p>The classes and objects are implemented as user data in Lua. To make sure that
2744 the user data really is the internal structure it is supposed to be, we tag
2745 their metatables. A user data who's metatable contains a boolean member named
2746 <tt class="docutils literal"><span class="pre">__luabind_classrep</span></tt> is expected to be a class exported by luabind. A user
2747 data who's metatable contains a boolean member named <tt class="docutils literal"><span class="pre">__luabind_class</span></tt> is
2748 expected to be an instantiation of a luabind class.</p>
2749 <p>This means that if you make your own user data and tags its metatable with the
2750 exact same names, you can very easily fool luabind and crash the application.</p>
2751 <p>In the Lua registry, luabind keeps an entry called <tt class="docutils literal"><span class="pre">__luabind_classes</span></tt>. It
2752 should not be removed or overwritten.</p>
2753 <p>In the global table, a variable called <tt class="docutils literal"><span class="pre">super</span></tt> is used every time a
2754 constructor in a lua-class is called. This is to make it easy for that
2755 constructor to call its base class' constructor. So, if you have a global
2756 variable named super it may be overwritten. This is probably not the best
2757 solution, and this restriction may be removed in the future.</p>
2758 <p>Luabind uses two upvalues for functions that it registers. The first is a
2759 userdata containing a list of overloads for the function, the other is a light
2760 userdata with the value 0x1337, this last value is used to identify functions
2761 registered by luabind. It should be virtually impossible to have such a pointer
2762 as secondary upvalue by pure chance. This means, if you are trying to replace
2763 an existing function with a luabind function, luabind will see that the
2764 secondary upvalue isn't the magic id number and replace it. If it can identify
2765 the function to be a luabind function, it won't replace it, but rather add
2766 another overload to it.</p>
2767 <p>Inside the luabind namespace, there's another namespace called detail. This
2768 namespace contains non-public classes and are not supposed to be used directly.</p>
2769 </div>
2772 <ul>
2775 </pre>
2777 or there's no setter-function registered on that property name. See the
2779 </li>
2781 the attribute '<em>class-name.attribute-name</em>' is of type: (<em>class-name</em>) and does not match (<em>class_name</em>)
2782 </pre>
2783 <p>This error is generated if you try to assign an attribute with a value
2784 of a type that cannot be converted to the attribute's type.</p>
2785 </li>
2787 <em>class-name()</em> threw an exception, <em>class-name:function-name()</em> threw an exception
2788 </pre>
2789 <p>The class' constructor or member function threw an unknown exception.
2790 Known exceptions are const char*, std::exception. See the
2792 </li>
2794 no overload of '<em>class-name:function-name</em>' matched the arguments (<em>parameter-types</em>)
2795 no match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>)
2798 </pre>
2799 <p>No function/operator with the given name takes the parameters you gave
2800 it. You have either misspelled the function name, or given it incorrect
2801 parameters. This error is followed by a list of possible candidate
2802 functions to help you figure out what parameter has the wrong type. If
2803 the candidate list is empty there's no function at all with that name.
2804 See the signature matching section.</p>
2805 </li>
2808 ambiguous match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>)
2811 </pre>
2812 <p>This means that the function/operator you are trying to call has at least
2813 one other overload that matches the arguments just as good as the first
2814 overload.</p>
2815 </li>
2818 </pre>
2819 </li>
2820 </ul>
2821 </div>
2826 <dd>If you're having problem with functions
2827 that cannot be converted from <tt class="docutils literal"><span class="pre">void</span> <span class="pre">(__stdcall</span> <span class="pre">*)(int,int)</span></tt> to
2828 <tt class="docutils literal"><span class="pre">void</span> <span class="pre">(__cdecl*)(int,int)</span></tt>. You can change the project settings to make the
2829 compiler generate functions with __cdecl calling conventions. This is
2830 a problem in developer studio.</dd>
2832 <dd>You cannot register a function with ellipses in its signature. Since
2833 ellipses don't preserve type safety, those should be avoided anyway.</dd>
2835 <dd>If you, in visual studio, get fatal error C1204: compiler limit :
2836 internal structure overflow. You should try to split that compilation
2837 unit up in smaller ones. See <a class="reference" href="#splitting-up-the-registration">Splitting up the registration</a> and
2838 <a class="reference" href="#splitting-class-registrations">Splitting class registrations</a>.</dd>
2839 </dl>
2840 <!-- the three entries above were removed, why? -->
2843 <dd>Visual Studio doesn't like anonymous namespace's in its precompiled
2844 headers. If you encounter this problem you can disable precompiled
2845 headers for the compilation unit (cpp-file) that uses luabind.</dd>
2847 <dd>In visual studio you will probably hit this error. To fix it you have to
2848 increase the internal heap with a command-line option. We managed to
2849 compile the test suit with /Zm300, but you may need a larger heap then
2850 that.</dd>
2852 <dd>It seems that this error occurs when too many assert() are used in a
2853 program, or more specifically, the __LINE__ macro. It seems to be fixed by
2854 changing /ZI (Program database for edit and continue) to /Zi
2855 (Program database).</dd>
2858 debug-info and symbols (luabind consists of a lot of functions). Also,
2859 if built in debug mode, no optimizations were applied, luabind relies on
2860 that the compiler is able to inline functions. If you built in release
2861 mode, try running strip on your executable to remove export-symbols,
2862 this will trim down the size.</p>
2864 compared to gcc on other platforms and other compilers.</p>
2865 </dd>
2866 </dl>
2867 <!-- HUH?! // check the magic number that identifies luabind's functions -->
2871 class. Because there's no Lua counterpart to C++ templates. For example,
2874 module(L)
2875 [
2879 ];
2880 </pre>
2881 </dd>
2882 </dl>
2883 <!-- Again, irrelevant to docs: Note that the space between the two > is required by C++. -->
2887 object is collected. Note that Lua has to own the object to collect it.
2888 If you pass it to C++ and gives up ownership (with adopt policy) it will
2889 no longer be owned by Lua, and not collected.</p>
2891 you want to be sure that the correct destructor is called (this apply to C++
2892 in general).</p>
2893 </dd>
2894 </dl>
2895 <!-- And again, the above is irrelevant to docs. This isn't a general C++ FAQ. But it saves us support questions. -->
2898 <dd>VC6.5 chokes on warnings, if you are getting alot of warnings from your
2899 code try suppressing them with a pragma directive, this should solve the
2900 problem.</dd>
2902 <dd>When you build luabind, Lua and you project, make sure you link against
2903 the runtime dynamically (as a dll).</dd>
2905 <dd>This is because there is no way to get a reference to a Lua value. Have
2906 a look at <a class="reference" href="#out-value">out_value</a> and <a class="reference" href="#pure-out-value">pure_out_value</a> policies.</dd>
2907 </dl>
2908 </div>
2912 <li>You cannot use strings with extra nulls in them as member names that refers
2913 to C++ members.</li>
2914 <li>If one class registers two functions with the same name and the same
2915 signature, there's currently no error. The last registered function will
2916 be the one that's used.</li>
2918 <li>If you register a function and later rename it, error messages will use the
2919 original function name.</li>
2920 <li>luabind does not support class hierarchies with virtual inheritance. Casts are
2921 done with static pointer offsets.</li>
2922 </ul>
2923 <!-- remove? - Visual studio have problems selecting the correct overload of std::swap()
2924 for luabind::object. -->
2925 </div>
2929 All rights reserved.</p>
2930 <p>Evan Wies has contributed with thorough testing, countless bug reports
2931 and feature ideas.</p>
2932 <p>This library was highly inspired by Dave Abrahams' <a class="reference" href="http://www.boost.org/libraries/python">Boost.Python</a> library.</p>
2933 </div>
2934 </div>
2935 </body>
2936 </html>