| blob | d46580228b2c73c05c4c5a51331d502330590d97 |
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4 <head>
9 </head>
10 <body>
13 <p>Note: This library is currently in public beta phase. This documentation
14 should be considered beta as well. Please report any grammatical
15 corrections/spelling corrections.</p>
22 <li><a class="reference" href="#building-luabind" id="id4" name="id4">4 Building luabind</a></li>
23 <li><a class="reference" href="#basic-usage" id="id5" name="id5">5 Basic usage</a><ul class="auto-toc">
25 </ul>
26 </li>
28 <li><a class="reference" href="#binding-functions-to-lua" id="id8" name="id8">7 Binding functions to lua</a><ul class="auto-toc">
29 <li><a class="reference" href="#overloaded-functions" id="id9" name="id9">7.1 Overloaded functions</a></li>
30 <li><a class="reference" href="#signature-matching" id="id10" name="id10">7.2 Signature matching</a></li>
31 <li><a class="reference" href="#calling-lua-functions" id="id11" name="id11">7.3 Calling lua functions</a></li>
32 <li><a class="reference" href="#using-lua-threads" id="id12" name="id12">7.4 Using lua threads</a></li>
33 </ul>
34 </li>
35 <li><a class="reference" href="#binding-classes-to-lua" id="id13" name="id13">8 Binding classes to lua</a><ul class="auto-toc">
39 <li><a class="reference" href="#nested-scopes-and-static-functions" id="id17" name="id17">8.4 Nested scopes and static functions</a></li>
40 <li><a class="reference" href="#derived-classes" id="id18" name="id18">8.5 Derived classes</a></li>
41 <li><a class="reference" href="#smart-pointers" id="id19" name="id19">8.6 Smart pointers</a></li>
42 </ul>
43 </li>
46 <li><a class="reference" href="#related-functions" id="id22" name="id22">9.2 Related functions</a></li>
48 </ul>
49 </li>
50 <li><a class="reference" href="#defining-classes-in-lua" id="id24" name="id24">10 Defining classes in lua</a><ul class="auto-toc">
51 <li><a class="reference" href="#deriving-in-lua" id="id25" name="id25">10.1 Deriving in lua</a></li>
52 <li><a class="reference" href="#overloading-operators" id="id26" name="id26">10.2 Overloading operators</a></li>
54 </ul>
55 </li>
57 <li><a class="reference" href="#policies" id="id29" name="id29">12 Policies</a><ul class="auto-toc">
61 <li><a class="reference" href="#return-reference-to" id="id33" name="id33">12.4 Return reference to</a></li>
63 <li><a class="reference" href="#pure-out-value" id="id35" name="id35">12.6 Pure out value</a></li>
64 <li><a class="reference" href="#discard-result" id="id36" name="id36">12.7 Discard result</a></li>
65 <li><a class="reference" href="#return-stl-iterator" id="id37" name="id37">12.8 Return STL iterator</a></li>
67 </ul>
68 </li>
69 <li><a class="reference" href="#splitting-up-the-registration" id="id39" name="id39">13 Splitting up the registration</a></li>
70 <li><a class="reference" href="#configuration" id="id40" name="id40">14 Configuration</a><ul class="auto-toc">
72 </ul>
73 </li>
74 <li><a class="reference" href="#implementation-notes" id="id42" name="id42">15 Implementation notes</a></li>
78 <li><a class="reference" href="#acknowledgments" id="id46" name="id46">19 Acknowledgments</a></li>
79 </ul>
80 </div>
83 <p>Luabind is a library that helps you create bindings between C++ and lua. It has
84 the ability to expose functions and classes, written in C++, to lua. It will
85 also supply the functionality to define classes in lua and let them derive from
86 other lua classes or C++ classes. Lua classes can override virtual functions
87 from their C++ base classes. It is written towards lua 5.0, and does not work
89 <p>It is implemented utilizing template meta programming. That means that you
90 don't need an extra preprocess pass to compile your project (it is done by the
91 compiler). It also means you don't (usually) have to know the exact signature of
92 each function you register, since the library will generate code depending on
93 the compile-time type of the function (which includes the signature). The main
94 drawback of this approach is that the compilation time will increase for the
95 file that does the registration, it is therefore recommended that you register
96 everything in the same cpp-file.</p>
97 <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>
98 <p>We are very interested in hearing about projects that use luabind, please let
99 us know about your project.</p>
100 </div>
104 <blockquote>
120 </ul>
121 </blockquote>
122 </div>
126 <blockquote>
135 </ul>
136 </blockquote>
138 <blockquote>
142 </ul>
143 </blockquote>
145 <blockquote>
150 compiles but fails the const-test. This means that const member
151 functions are treated as non-const member functions.</li>
152 </ul>
153 </blockquote>
154 <p>If you have tried luabind with a compiler not listed here, let us know
155 your result with it.</p>
156 </div>
159 <p>To keep down the compilation-time luabind is built as a library. This means you
160 have to either build it and lika against it, or include its source files in
161 your project. You also have to make sure the luabind directory is somewhere in
162 your compiler's include path. It requires <a class="reference" href="http://www.boost.org">Boost</a> 1.31.0 to be installed (only
163 boost headers). It also requires that lua is installed.</p>
164 <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
165 luabind with Boost.Build you need to set two environment variables:</p>
166 <dl>
170 <dd>Point this to your lua directory. The build system will assume that the
171 include and library files are located in <tt class="literal"><span class="pre">$(LUA_PATH)/include/</span></tt> and
173 </dl>
174 <p>For backward compatibility, there is also a makefile in the root-directory that
175 will build the library and the test program. If you are using a UNIX-system (or
176 cygwin) they will make it easy to build luabind as a static library. If you are
177 using Visual Studio it may be easier to include the files in the src directory
178 in your project.</p>
179 <p>When building luabind you have several options that may streamline the library
180 to better suit your needs. It is extremely important that your application has
181 the same settings as the library was built with. The available options are
183 <p>If you want to change the settings to differ from the default, it's recommended
184 that you define the settings on the commandline of all your files (in the
185 project settings in visual studio).</p>
186 </div>
189 <p>To use luabind, you must include <tt class="literal"><span class="pre">lua.h</span></tt> and luabind's main header file:</p>
192 {
194 }
197 </pre>
198 <p>This includes support for both registering classes and functions. If you just
199 want to have support for functions or classes you can include
200 <tt class="literal"><span class="pre">luabind/function.hpp</span></tt> and <tt class="literal"><span class="pre">luabind/class.hpp</span></tt> separately:</p>
204 </pre>
205 <p>The first thing you need to do is to call <tt class="literal"><span class="pre">luabind::open(lua_State*)</span></tt> which
206 will register the functions to create classes from lua, and initialize some
207 state-global structures used by luabind. If you don't call this function you
208 will hit asserts later in the library. There is no corresponding close function
209 because once a class has been registered in lua, there really isn't any good
210 way to remove it. Partly because any remaining instances of that class relies
211 on the class being there. Everything will be cleaned up when the state is
212 closed though.</p>
213 <!-- Isn't this wrong? Don't we include lua.h using lua_include.hpp ? -->
214 <p>Luabind's headers will never include <tt class="literal"><span class="pre">lua.h``directly,</span> <span class="pre">but</span> <span class="pre">through</span>
215 <span class="pre">``<luabind/lua_include.hpp></span></tt>. If you for some reason need to include another
216 lua header, you can modify this file.</p>
223 void greet()
224 {
226 }
229 {
230 using namespace luabind;
232 open(L);
234 module(L)
235 [
237 ];
239 return 0;
240 }
241 </pre>
244 > loadlib('hello_world.dll', 'init')()
245 > greet()
246 Hello world!
247 >
248 </pre>
249 </div>
250 </div>
253 <p>Everything that gets registered in lua is registered in a namespace (lua
254 tables) or in the global scope (called module). All registrations must be
255 surrounded by its scope. To define a module, the <tt class="literal"><span class="pre">luabind::module</span></tt> class is
256 used. It is used like this:</p>
258 module(L)
259 [
260 // declarations
261 ];
262 </pre>
263 <p>This will register all declared functions or classes in the global namespace in
264 lua. If you want to have a namespace for your module (like the standard
265 libraries) you can give a name to the constructor, like this:</p>
268 [
269 // declarations
270 ];
271 </pre>
273 <p>If you want nested namespaces you can use the <tt class="literal"><span class="pre">luabind::namespace_</span></tt> class. It
274 works exactly as <tt class="literal"><span class="pre">luabind::module</span></tt> except that it doesn't take a lua_State*
275 in it's constructor. An example of its usage could look like this:</p>
278 [
279 // declarations
282 [
283 // library-private declarations
284 ]
285 ];
286 </pre>
289 module(L)
290 [
292 [
293 // declarations
294 ]
296 ];
297 </pre>
300 [
301 // declarations
302 ];
303 </pre>
306 module(L)
307 [
313 ];
314 </pre>
315 <p>More about the actual declarations in the <a class="reference" href="#binding-functions-to-lua">Binding functions to lua</a> and
317 <p>A word of caution, if you are in really bad need for performance, putting your
318 functions in tables will increase the lookup time.</p>
319 </div>
321 <h1><a class="toc-backref" href="#id8" name="binding-functions-to-lua">7 Binding functions to lua</a></h1>
322 <p>To bind functions to lua you use the function <tt class="literal"><span class="pre">luabind::def()</span></tt>. It has the
323 following synopsis:</p>
326 void def(const char* name, F f, const Policies&);
327 </pre>
331 <li>The Policies parameter is used to describe how parameters and return values
332 are treated by the function, this is an optional parameter. More on this in
334 </ul>
335 <p>An example usage could be if you want to register the function <tt class="literal"><span class="pre">float</span>
338 module(L)
339 [
341 ];
342 </pre>
344 <h2><a class="toc-backref" href="#id9" name="overloaded-functions">7.1 Overloaded functions</a></h2>
345 <p>If you have more than one function with the same name, and want to register
346 them in lua, you have to explicitly give the signature. This is to let C++ know
347 which function you refer to. For example, if you have two functions, <tt class="literal"><span class="pre">int</span>
348 <span class="pre">f(const</span> <span class="pre">char*)</span></tt> and <tt class="literal"><span class="pre">void</span> <span class="pre">f(int)</span></tt>.</p>
350 module(L)
351 [
354 ];
355 </pre>
356 </div>
358 <h2><a class="toc-backref" href="#id10" name="signature-matching">7.2 Signature matching</a></h2>
359 <p>luabind will generate code that checks the lua stack to see if the values there
360 can match your functions' signatures. It will handle implicit typecasts between
361 derived classes, and it will prefer matches with the least number of implicit
362 casts. In a function call, if the function is overloaded and there's no
363 overload that match the parameters better than the other, you have an
364 ambiguity. This will spawn a run-time error, stating that the function call is
365 ambiguous. A simple example of this is to register one function that takes an
366 int and one that takes a float. Since lua don't distinguish between floats and
367 integers, both will always match.</p>
368 <p>Since all overloads are tested, it will always find the best match (not the
369 first match). This also means that it can handle situations where the only
370 difference in the signature is that one member function is const and the other
371 isn't.</p>
374 <p>To correctly handle ownership transfer, create_a() would need an adopt
375 return value policy. More on this in the <a class="reference" href="#policies">Policies</a> section.</p>
376 </div>
379 struct A
380 {
381 void f();
382 void f() const;
383 };
385 const A* create_a();
387 struct B: A {};
388 struct C: B {};
390 void g(A*);
391 void g(B*);
392 </pre>
395 a1 = create_a()
396 a1:f() -- the const version is called
398 a2 = A()
399 a2:f() -- the non-const version is called
401 a = A()
402 b = B()
403 c = C()
405 g(a) -- calls g(A*)
406 g(b) -- calls g(B*)
407 g(c) -- calls g(B*)
408 </pre>
409 </div>
411 <h2><a class="toc-backref" href="#id11" name="calling-lua-functions">7.3 Calling lua functions</a></h2>
412 <p>To call a lua function, you can either use <tt class="literal"><span class="pre">call_function()</span></tt>,
413 <tt class="literal"><span class="pre">call_member()</span></tt>, an <tt class="literal"><span class="pre">object</span></tt> or <tt class="literal"><span class="pre">functor</span></tt>.</p>
416 Ret call_function(lua_State* L, const char* name, ...)
417 </pre>
418 <p>This calls the global function called name. This function can only call global
419 lua functions. The ... represents a variable number of parameters that are sent
420 to the lua function. This function call may throw <tt class="literal"><span class="pre">luabind::error</span></tt> if the
421 function call fails.</p>
422 <p>The return value isn't actually Ret (the template parameter), but a proxy
423 object that will do the function call. This enables you to give policies to the
424 call. You do this with the operator[]. You give the policies within the
425 brackets, like this:</p>
428 L
430 , new complex_class()
431 )[ adopt(_1) ];
432 </pre>
435 Ret call_member(object const&, const char* name, ...)
438 Ret call_member(weak_ref, const char* name, ...)
439 </pre>
440 <p>This treats the given object as an instance of a class. The given name is the
441 name of a member function to call. The ... represents a variable number of
442 parameters given to the function. This function may throw <tt class="literal"><span class="pre">luabind::error</span></tt> if
443 the function call fails.</p>
444 <p>You can give policies to a member function call the same way as you do with
446 </div>
449 <p>To start a lua thread, you have to call <tt class="literal"><span class="pre">lua_resume()</span></tt>, this means that you
450 cannot use the previous function <tt class="literal"><span class="pre">call_function()</span></tt> to start a thread. You have
451 to use</p>
454 Ret resume_function(lua_State* L, const char* name, ...)
455 </pre>
459 Ret resume(lua_State* L, ...)
460 </pre>
461 <p>The first time you start the thread, you have to give it a function to execute. i.e. you
462 have to use <tt class="literal"><span class="pre">resume_function</span></tt>, when the lua function yeilds, it will return the first
463 value passed in to <tt class="literal"><span class="pre">lua_yield()</span></tt>. When you want to continue the execution, you just call
464 <tt class="literal"><span class="pre">resume()</span></tt> on your <tt class="literal"><span class="pre">lua_State</span></tt>, since it's already executing a function, you don't pass
465 it one. The parameters to <tt class="literal"><span class="pre">resume()</span></tt> will be returned by <tt class="literal"><span class="pre">yield()</span></tt> on the lua side.</p>
466 <p>For yielding C++-functions (without the support of passing data back and forth between the
467 lua side and the c++ side), you can use the <a class="reference" href="#yield">Yield</a> policy.</p>
468 </div>
469 </div>
471 <h1><a class="toc-backref" href="#id13" name="binding-classes-to-lua">8 Binding classes to lua</a></h1>
472 <p>To register classes you use a class called <tt class="literal"><span class="pre">class_</span></tt>. Its name is supposed to
473 resemble the C++ keyword, to make it look more intuitive. It has an overloaded
474 member function <tt class="literal"><span class="pre">def()</span></tt> that is used to register member functions, operators,
475 constructors, enums and properties on the class. It will return its
476 this-pointer, to let you register more members directly.</p>
479 class testclass
480 {
481 public:
482 testclass(const std::string& s): m_string(s) {}
485 private:
486 std::string m_string;
487 };
488 </pre>
489 <p>To register it with a lua environment, write as follows (assuming you are using
490 namespace luabind):</p>
492 module(L)
493 [
497 ];
498 </pre>
499 <p>This will register the class with the name testclass and constructor that takes
500 a string as argument and one member function with the name <tt class="literal"><span class="pre">print_string</span></tt>.</p>
503 > a = testclass('a string')
504 > a:print_string()
505 a string
506 </pre>
507 <p>It is also possible to register free functions as member functions. The
508 requirement on the function is that it takes a pointer, const pointer,
509 reference or const reference to the class type as the first parameter. The rest
510 of the parameters are the ones that are visible in lua, while the object
511 pointer is given as the first parameter. If we have the following C++ code:</p>
513 struct A
514 {
515 int a;
516 };
518 int plus(A* o, int v) { return o->a + v; }
519 </pre>
520 <p>You can register <tt class="literal"><span class="pre">plus()</span></tt> as if it was a member function of A like this:</p>
524 </pre>
525 <p><tt class="literal"><span class="pre">plus()</span></tt> can now be called as a member function on A with one parameter, int.
526 If the object pointer parameter is const, the function will act as if it was a
527 const member function (it can be called on const objects).</p>
530 <p>To register a global data member with a class is easily done. Consider the
531 following class:</p>
533 struct A
534 {
535 int a;
536 };
537 </pre>
540 module(L)
541 [
544 ];
545 </pre>
546 <p>This gives read and write access to the member variable <tt class="literal"><span class="pre">A::a</span></tt>. It is also
547 possible to register attributes with read-only access:</p>
549 module(L)
550 [
553 ];
554 </pre>
555 <p>You can also register getter and setter functions and make them look as if they
556 were a public data member. Consider the following class:</p>
558 class A
559 {
560 public:
561 void set_a(int x) { a = x; }
562 int get_a() const { return a; }
564 private:
565 int a;
566 };
567 </pre>
572 </pre>
573 <p>This way the <tt class="literal"><span class="pre">get_a()</span></tt> and <tt class="literal"><span class="pre">set_a()</span></tt> functions will be called instead of
574 just writing to the data member. If you want to make it read only you can just
575 omit the last parameter.</p>
576 </div>
579 <p>If your class contains enumerated constants (enums), you can register them as
580 well to make them available in lua. Note that they will not be type safe, all
581 enums are integers in lua, and all functions that takes an enum, will accept
582 any integer. You register them like this:</p>
584 module(L)
585 [
588 [
592 ]
593 ];
594 </pre>
595 <p>In lua they are accessed like any data member, except that they are read-only
596 and reached on the class itself rather than on an instance of the class.</p>
599 > print(A.my_enum)
600 4
601 > print(A.another_enum)
602 6
603 </pre>
604 </div>
607 <p>The mechanism for registering operators on your class is pretty simple. You use
608 a global name <tt class="literal"><span class="pre">luabind::self</span></tt> to refer to the class itself and then you just
609 write the operator expression inside the <tt class="literal"><span class="pre">def()</span></tt> call. This class:</p>
611 struct vec
612 {
613 vec operator+(int s);
614 };
615 </pre>
618 module(L)
619 [
621 .def(self + int())
622 ];
623 </pre>
624 <p>This will work regardless if your plus operator is defined inside your class or
625 as a free function.</p>
626 <p>If you operator is const (or, when defined as a free function, takes a const
627 reference to the class itself) you have to use <tt class="literal"><span class="pre">const_self</span></tt> instead of
630 module(L)
631 [
633 .def(const_self + int())
634 ];
635 </pre>
637 <blockquote>
643 </ul>
644 <!-- more -->
645 </blockquote>
646 <p>This means, no in-place operators. The equality operator (==) has a little
647 hatch, it will not be called if the references are equal. This means that the
648 == operator has to do pretty much what's it's expected to do.</p>
649 <p>In the above example the other operand type is instantiated by writing
650 <tt class="literal"><span class="pre">int()</span></tt>. If the operand type is a complex type that cannot easily be
651 instantiated you can wrap the type in a class called <tt class="literal"><span class="pre">other<></span></tt>. For example:</p>
652 <p>To register this class, we don't want to instantiate a string just to register
653 the operator.</p>
655 struct vec
656 {
657 vec operator+(std::string);
658 };
659 </pre>
660 <p>Instead we use the other <tt class="literal"><span class="pre">wrapper</span></tt> like this:</p>
662 module(L)
663 [
666 ];
667 </pre>
670 module(L)
671 [
673 .def( self(int()) )
674 ];
675 </pre>
676 <p>There's one special operator. In lua it's called <tt class="literal"><span class="pre">__tostring</span></tt>, it's not
677 really an operator. It is used for converting objects to strings in a standard
678 way in lua. If you register this functionality, you will be able to use the lua
679 standard function <tt class="literal"><span class="pre">tostring()</span></tt> for converting you object to a string.</p>
680 <p>To implement this operator in C++ you should supply an <tt class="literal"><span class="pre">operator<<</span></tt> for
681 ostream. Like this example:</p>
683 class number {};
686 ...
688 module(L)
689 [
691 .def(tostring(self))
692 ];
693 </pre>
694 </div>
696 <h2><a class="toc-backref" href="#id17" name="nested-scopes-and-static-functions">8.4 Nested scopes and static functions</a></h2>
697 <p>It is possible to add nested scopes to a class. This is useful when you need
698 to wrap a nested class, or a static function.</p>
701 .def(constructor<>()
702 ...
703 .scope
704 [
707 ];
708 </pre>
710 </div>
713 <p>If you want to register classes that derives from other classes, you can
714 specify a template parameter <tt class="literal"><span class="pre">bases<></span></tt> to the <tt class="literal"><span class="pre">class_</span></tt> instantiation. The
715 following hierarchy:</p>
717 struct A {};
718 struct B : A {};
719 </pre>
722 module(L)
723 [
726 ];
727 </pre>
728 <p>If you have multiple inheritance you can specify more than one base. If B would
729 also derive from a class C, it would be registered like this:</p>
731 module(L)
732 [
734 ];
735 </pre>
736 <p>Note that you can omit <tt class="literal"><span class="pre">bases<></span></tt> when using single inheritance.</p>
739 If you don't specify that classes derive from each other, luabind will not
740 be able to implicitly cast pointers between the types.</div>
741 </div>
744 <p>When you register a class you can tell luabind that all instances of that class
745 should be held by some kind of smart pointer (boost::shared_ptr for instance).
746 You do this by giving the holder type as an extra template parameter to
747 the``class_``your constructing, like this:</p>
749 module(L)
750 [
752 ];
753 </pre>
754 <p>You also have to supply two functions for your smart pointer. One that returns
756 in this case). And one function that extracts the raw pointer from the smart
757 pointer. The first function is needed because luabind has to allow the
758 non-const -> conversion when passing values from lua to C++. The second
759 function is needed when lua calls member functions on held types, the this
760 pointer must be a raw pointer, it is also needed to allow the smart_pointer ->
761 raw_pointer conversion from lua to C++. They look like this:</p>
763 namespace luabind {
767 {
768 return p.get();
769 }
774 {
775 return 0;
776 }
777 }
778 </pre>
781 <colgroup>
784 </colgroup>
787 </tr>
788 </thead>
792 </tr>
795 </tr>
798 </tr>
801 </tr>
804 </tr>
807 </tr>
810 </tr>
813 </tr>
816 </tr>
817 </tbody>
818 </table>
820 <colgroup>
823 </colgroup>
826 </tr>
827 </thead>
831 </tr>
834 </tr>
837 </tr>
840 </tr>
841 </tbody>
842 </table>
843 <p>When using a holder type, it can be useful to know if the pointer is valid. For
844 example when using std::auto_ptr, the holder will be invalidated when passed as
845 a parameter to a function. For this purpose there is a member of all object
848 struct test {};
851 module(L)
852 [
854 .def(constructor<>()),
857 ];
858 </pre>
861 > a = test()
862 > f(a)
863 > print a.__ok
864 false
865 </pre>
866 </div>
867 </div>
870 <p>Since functions have to be able to take lua values (of variable type) we need a
871 wrapper around them. This wrapper is called <tt class="literal"><span class="pre">luabind::object</span></tt>. If the
872 function you register takes an object, it will match any lua value. To use it,
873 you need to include <tt class="literal"><span class="pre">luabind/object.hpp</span></tt>. The object class has the following
874 synopsis:</p>
876 class object
877 {
878 public:
879 class iterator;
880 class raw_iterator;
881 class array_iterator;
884 object(lua_State*, const T& value);
885 object(const object&);
886 object(lua_State*);
887 object();
889 ~object();
891 iterator begin() const;
892 iterator end() const;
893 raw_iterator raw_begin() const;
894 raw_iterator raw_end() const;
895 array_iterator abegin() const;
896 array_iterator aend() const;
898 void set();
899 lua_State* lua_state() const;
900 void pushvalue() const;
901 bool is_valid() const;
902 operator safe_bool_type() const;
908 object at(const Key&) const;
911 object raw_at(const Key&) const;
918 bool operator==(const T&) const;
919 bool operator==(const object&) const;
924 bool operator!=(const object&) const;
926 void swap(object&);
927 int type() const;
937 /* ... */
939 };
940 </pre>
941 <p>When you have a lua object, you can assign it a new value with the assignment
942 operator (=). When you do this, the <tt class="literal"><span class="pre">default_policy</span></tt> will be used to make the
943 conversion from C++ value to lua. If your <tt class="literal"><span class="pre">luabind::object</span></tt> is a table you
944 can access its members through the operator[] or the iterators. The value
945 returned from the operator[] is a proxy object that can be used both for
946 reading and writing values into the table (using operator=). Note that it is
947 impossible to know if a lua value is indexable or not (lua_gettable doesn't
948 fail, it succeeds or crashes). This means that if you're trying to index
949 something that cannot be indexed, you're on your own. Lua will call its
950 <tt class="literal"><span class="pre">panic()</span></tt> function (you can define your own panic function using
951 lua_setpanicf). The <tt class="literal"><span class="pre">at()</span></tt> and <tt class="literal"><span class="pre">raw_at()</span></tt> functions returns the value at
952 the given table position (like operator[] but only for reading).</p>
953 <p>The ordinary <tt class="literal"><span class="pre">object::iterator</span></tt> uses lua_gettable to extract the values from
954 the table, the standard way that will invoke metamethods if any. The
955 <tt class="literal"><span class="pre">object::raw_iterator</span></tt> uses lua_rawget and <tt class="literal"><span class="pre">object::array_iterator</span></tt> uses
956 lua_rawgeti. The latter will only iterate over numberical keys starting at 1
957 and continue until the first nil value.</p>
958 <p>The <tt class="literal"><span class="pre">lua_state()</span></tt> function returns the lua state where this object is stored.
959 If you want to manipulate the object with lua functions directly you can push
960 it onto the lua stack by calling <tt class="literal"><span class="pre">pushvalue()</span></tt>. And set the object's value by
961 calling <tt class="literal"><span class="pre">set()</span></tt>, which will pop the top value from the lua stack and assign
962 it to the object.</p>
964 <p>The <tt class="literal"><span class="pre">type()</span></tt> member function will return the lua type of the object. It will
965 return the same values as lua_type().</p>
966 <p>The <tt class="literal"><span class="pre">is_valid()</span></tt> function tells you whether the object has been initialized
967 or not. When created with its default constructor, objects are invalid. To make
968 an object valid, you can assign it a value. If you want to invalidate an object
969 you can simply assign it an invalid object.</p>
970 <!-- So what? implementation detail, leave out of docs
971 isn't really an implicit cast to bool, but an implicit cast
972 to a member pointer, since member pointers don't have any arithmetic operators
973 on them (which can cause hard to find errors). The functionality of the cast
974 operator -->
975 <p>The <tt class="literal"><span class="pre">operator</span> <span class="pre">safe_bool_type()</span></tt> is equivalent to <tt class="literal"><span class="pre">is_valid()</span></tt>. This means
976 that these snippets are equivalent:</p>
978 object o;
979 // ...
980 if (o)
981 {
982 // ...
983 }
985 ...
987 object o;
988 // ...
989 if (o.is_valid())
990 {
991 // ...
992 }
993 </pre>
994 <p>The application operator will call the value as if it was a function. You can
995 give it any number of parameters (currently the <tt class="literal"><span class="pre">default_policy</span></tt> will be used
996 for the conversion). The returned object refers to the return value (currently
997 only one return value is supported). This operator may throw <tt class="literal"><span class="pre">luabind::error</span></tt>
998 if the function call fails. If you want to specify policies to your function
999 call, you can use index-operator (operator[]) on the function call, and give
1000 the policies within the [ and ]. Like this:</p>
1002 my_function_object(
1003 2
1004 , 8
1005 , new my_complex_structure(6)
1006 ) [ adopt(_3) ];
1007 </pre>
1008 <p>This tells luabind to make lua adopt the ownership and responsibility for the
1009 pointer passed in to the lua-function.</p>
1010 <p>It's important that all instances of object have been destructed by the time
1011 the lua state is closed. The object will keep a pointer to the lua state and
1012 release its lua object in its destructor.</p>
1015 void my_function(const object& table)
1016 {
1017 if (table.type() == LUA_TTABLE)
1018 {
1023 }
1024 }
1025 </pre>
1026 <p>If you take a <tt class="literal"><span class="pre">luabind::object</span></tt> as a parameter to a function, any lua value
1027 will match that parameter. That's why we have to make sure it's a table before
1028 we index into it.</p>
1031 <p>The iterators, that are returned by <tt class="literal"><span class="pre">begin()</span> <span class="pre">and</span> <span class="pre">``end()</span></tt> (and their
1032 variants) are (almost) models of the ForwardIterator concept. The exception
1033 is that post increment doesn't exist on them.</p>
1036 class object::iterator
1037 {
1038 iterator();
1039 iterator(const iterator&);
1041 iterator& operator++();
1042 bool operator!=(const iterator&) const;
1045 object key() const;
1047 implementation-defined operator*();
1048 };
1049 </pre>
1050 <p>The implementation defined return value from the dereference operator is a
1051 proxy object that can be used as if it was an object, it can also be used to
1052 assign the specific table entry with a new value. If you want to assign a value
1053 to an entry pointed to by an iterator, just use the assignment operator on the
1054 dereferenced iterator:</p>
1056 *iter = 5;
1057 </pre>
1058 <p>The <tt class="literal"><span class="pre">key()</span></tt> member returns the key used by the iterator when indexing the
1059 associated lua table.</p>
1060 </div>
1062 <h2><a class="toc-backref" href="#id22" name="related-functions">9.2 Related functions</a></h2>
1073 </pre>
1074 </div>
1077 <p>The <tt class="literal"><span class="pre">functor</span></tt> class is similar to object, with the exception that it can only
1078 be used to store functions. If you take it as a parameter, it will only match
1079 functions.</p>
1083 </pre>
1084 <p>It takes one template parameter, the return value of the lua function it
1085 represents. Currently the functor can have at most one return value (unlike lua
1086 functions). It has the following synopsis:</p>
1089 class functor
1090 {
1091 public:
1093 functor(lua_State*, const char* name);
1094 functor(const functor&);
1096 ~functor();
1098 bool is_valid() const;
1099 operator safe_bool_type() const;
1100 void reset();
1102 lua_State* lua_state() const;
1103 void pushvalue() const;
1116 /* ... */
1117 };
1118 </pre>
1119 <p>The application operator takes any parameters. The parameters are converted
1120 into lua and the function is called. The return value will act as if it was the
1121 type Ret, with the exception that you can use the return value to give policies
1122 to the call. You do this the same way as you do with objects, using the
1123 operator[], and giving the policies inside the brackets.</p>
1124 <p>The <tt class="literal"><span class="pre">is_valid()</span></tt> function works just like the one on object, it tells you if
1125 the functor has been assigned with a valid lua function. The <tt class="literal"><span class="pre">operator</span>
1126 <span class="pre">safe_bool_type()</span></tt> is an alias for this member function and also works just as
1127 the one found in object.</p>
1130 function f(a, b)
1131 return a + b
1132 end
1133 </pre>
1139 </pre>
1141 to the application operator of <tt class="literal"><span class="pre">luabind::functor</span></tt>, this is because lua
1142 doesn't have signatures for its functions. All lua functions take any number of
1143 parameters of any type.</p>
1144 <p>If we have a C++ function that takes a <tt class="literal"><span class="pre">luabind::functor</span></tt> and registers it,
1145 it will accept lua functions passed to it. This enables us to expose APIs that
1146 requires you to register callbacks. For example, if your C++ API looks like
1147 this:</p>
1149 void set_callback(void(*)(int, int));
1150 </pre>
1151 <p>And you want to expose it to lua, you have to wrap the call to the lua
1152 function inside a real C++ function, like this:</p>
1156 void callback_wrapper(int a, int b)
1157 {
1158 lua_callback(a, b);
1159 }
1162 {
1163 lua_callback = f;
1164 set_callback(&callback_wrapper);
1165 }
1166 </pre>
1167 <p>And then register <tt class="literal"><span class="pre">set_callback_wrapper</span></tt> instead of registering
1168 <tt class="literal"><span class="pre">set_callback</span></tt>. This will have the effect that when one tries to register the
1169 callback from lua, your <tt class="literal"><span class="pre">set_callback_wrapper</span></tt> will be called instead and
1170 first set the lua functor to the given function. It will then call the real
1171 <tt class="literal"><span class="pre">set_callback</span></tt> with the <tt class="literal"><span class="pre">callback_wrapper</span></tt>. The <tt class="literal"><span class="pre">callback_wrapper</span></tt> will
1172 be called whenever the callback should be called, and it will simply call the
1173 lua function that we registered.</p>
1174 <p>You can also use <tt class="literal"><span class="pre">object_cast</span></tt> to cast an object to a functor.</p>
1175 <p><tt class="literal"><span class="pre">reset</span></tt> on <tt class="literal"><span class="pre">functor</span></tt> will invalidate the functor (and remove any references
1176 to its lua value). If the functor object has longer lifetime than the lua state
1177 (e.g. if it's a global).</p>
1178 </div>
1179 </div>
1181 <h1><a class="toc-backref" href="#id24" name="defining-classes-in-lua">10 Defining classes in lua</a></h1>
1182 <p>In addition to binding C++ functions and classes with lua, luabind also provide
1183 an OO-system in lua.</p>
1185 class 'lua_testclass'
1187 function lua_testclass:__init(name)
1188 self.name = name
1189 end
1191 function lua_testclass:print()
1192 print(self.name)
1193 end
1195 a = lua_testclass('example')
1196 a:print()
1197 </pre>
1200 class 'derived' (lua_testclass)
1202 function derived:__init() super('derived name')
1203 end
1205 function derived:print()
1206 print('Derived:print() -> ')
1207 lua_testclass.print(self)
1208 end
1209 </pre>
1210 <p>Here the <tt class="literal"><span class="pre">super</span></tt> keyword is used in the constructor to initialize the base
1211 class. The user is required to call <tt class="literal"><span class="pre">super</span></tt> first in the constructor.</p>
1212 <p>As you can see in this example, you can call the base class member functions.
1213 You can find all member functions in the base class, but you will have to give
1214 the this-pointer (<tt class="literal"><span class="pre">self</span></tt>) as first argument.</p>
1217 <p>It is also possible to derive lua classes from C++ classes, and override
1218 virtual functions with lua functions. To do this we have to create a wrapper
1219 class for our C++ base class. This is the class that will hold the lua object
1220 when we instantiate a lua class.</p>
1221 <p>The wrapper class has to provide the same constructors as the base class, with
1222 the addition of one extra parameter: <tt class="literal"><span class="pre">luabind::weak_ref</span></tt>. This is the reference
1223 to the lua object that should be held by the wrapper, and should be stored in a
1224 member variable as done in the sample below.</p>
1226 class base
1227 {
1228 public:
1229 base(const char* s)
1232 virtual void f(int a)
1234 };
1236 struct base_wrapper : base
1237 {
1238 weak_ref self;
1239 base_wrapper(weak_ref self_, const char* s)
1240 : base(s), self(self_)
1241 {}
1243 virtual void f(int a)
1244 {
1246 }
1248 static void f_static(base* ptr, int a)
1249 {
1250 return ptr->base::f(a);
1251 }
1252 };
1254 ...
1256 module(L)
1257 [
1261 ];
1262 </pre>
1263 <p>Note that if you have both base classes and a base class wrapper, you must give
1264 both bases and the base class wrapper type as template parameter to
1265 <tt class="literal"><span class="pre">class_</span></tt>. The order in which you specify them is not important.</p>
1266 <p>If we didn't have a class wrapper, it would not be possible to pass a lua class
1267 back to C++. Since the entry points of the virtual functions would still point
1268 to the C++ base class, and not to the functions defined in lua. That's why we
1269 need one function that calls the base class' real function (used if the lua
1270 class doesn't redefine it) and one virtual function that dispatches the call
1271 into luabind, to allow it to select if a lua function should be called, or if
1272 the original function should be called. If you don't intend to derive from a
1273 C++ class, or if it doesn't have any virtual member functions, you can register
1274 it without a class wrapper.</p>
1275 <p>You don't need to have a class wrapper in order to derive from a class, but if
1276 it has virtual functions you may have silent errors.</p>
1277 <!-- Unnecessary? The rule of thumb is:
1278 If your class has virtual functions, create a wrapper type, if it doesn't
1279 don't create a wrapper type. -->
1280 </div>
1282 <h2><a class="toc-backref" href="#id26" name="overloading-operators">10.2 Overloading operators</a></h2>
1283 <p>You can overload most operators in lua for your classes. You do this by simply
1284 declaring a member function with the same name as an operator (the name of the
1285 metamethods in lua). The operators you can overload are:</p>
1286 <blockquote>
1299 </ul>
1300 </blockquote>
1301 <p><tt class="literal"><span class="pre">__tostring</span></tt> isn't really an operator, but it's the metamethod that is called
1302 by the standard library's <tt class="literal"><span class="pre">tostring()</span></tt> function. There's one strange behavior
1303 regarding binary operators. You are not guaranteed that the self pointer you
1304 get actually refers to an instance of your class. This is because lua doesn't
1305 distinguish the two cases where you get the other operand as left hand value or
1306 right hand value. Consider the following examples:</p>
1308 class 'my_class'
1310 function my_class:__init(v)
1311 self.val = v
1312 end
1314 function my_class:__sub(v)
1315 return my_class(self.val - v.val)
1316 end
1318 function my_class:__tostring()
1319 return self.val
1320 end
1321 </pre>
1322 <p>This will work well as long as you only subtracts instances of my_class with
1323 each other. But If you want to be able to subtract ordinary numbers from your
1324 class too, you have to manually check the type of both operands, including the
1325 self object.</p>
1327 function my_class:__sub(v)
1328 if (type(self) == 'number') then
1329 return my_class(self - v.val)
1331 elseif (type(v) == 'number') then
1332 return my_class(self.val - v)
1334 else
1335 -- assume both operands are instances of my_class
1336 return my_class(self.val - v.val)
1338 end
1339 end
1340 </pre>
1341 <p>The reason why <tt class="literal"><span class="pre">__sub</span></tt> is used as an example is because subtraction is not
1342 commutative (the order of the operands matter). That's why luabind cannot
1343 change order of the operands to make the self reference always refer to the
1344 actual class instance.</p>
1345 <p>If you have two different lua classes with an overloaded operator, the operator
1346 of the right hand side type will be called. If the other operand is a C++ class
1347 with the same operator overloaded, it will be prioritized over the lua class'
1348 operator. If none of the C++ overloads matches, the lua class operator will be
1349 called.</p>
1350 </div>
1353 <p>If an object needs to perform actions when it's collected we provide a
1354 <tt class="literal"><span class="pre">__finalize</span></tt> function that can be overridden in lua-classes. The
1355 <tt class="literal"><span class="pre">__finalize</span></tt> functions will be called on all classes in the inheritance
1356 chain, starting with the most derived type.</p>
1358 ...
1360 function lua_testclass:__finalize()
1361 -- called when the an object is collected
1362 end
1363 </pre>
1364 </div>
1365 </div>
1368 <p>If any of the functions you register throws an exception when called, that
1369 exception will be caught by luabind and converted to an error string and
1370 <tt class="literal"><span class="pre">lua_error()</span></tt> will be invoked. If the exception is a <tt class="literal"><span class="pre">std::exception</span></tt> or a
1371 <tt class="literal"><span class="pre">const</span> <span class="pre">char*</span></tt> the string that is pushed on the lua stack, as error message,
1372 will be the string returned by <tt class="literal"><span class="pre">std::exception::what()</span></tt> or the string itself
1373 respectively. If the exception is unknown, a generic string saying that the
1374 function threw an exception will be pushed.</p>
1375 <p>Exceptions thrown from user defined functions have to be caught by luabind. If
1376 they weren't they would be thrown through lua itself, which is usually compiled
1377 as C code and doesn't support the stack-unwinding that exceptions imply.</p>
1378 <p>Any function that invokes lua code may throw <tt class="literal"><span class="pre">luabind::error</span></tt>. This exception
1379 means that a lua run-time error occurred. The error message is found on top of
1380 the lua stack. The reason why the exception doesn't contain the error string
1381 itself is because it would then require heap allocation which may fail. If an
1382 exception class throws an exception while it is being thrown itself, the
1383 application will be terminated.</p>
1386 class error : public std::exception
1387 {
1388 public:
1389 error(lua_State*);
1390 lua_State* state() const throw();
1391 virtual const char* what() const throw();
1392 };
1393 </pre>
1394 <p>The state function returns a pointer to the lua state in which the error was
1395 thrown. This pointer may be invalid if you catch this exception after the lua
1396 state is destructed. If the lua state is valid you can use it to retrieve the
1397 error message from the top of the lua stack.</p>
1398 <p>An example of where the lua state pointer may point to an invalid state
1399 follows:</p>
1401 struct lua_state
1402 {
1403 lua_state(lua_State* L): m_L(L) {}
1404 ~lua_state() { lua_close(m_L); }
1405 operator lua_State*() { return m_L; }
1406 lua_State* m_L;
1407 };
1409 int main()
1410 {
1411 try
1412 {
1413 lua_state L = lua_open();
1414 /* ... */
1415 }
1416 catch(luabind::error& e)
1417 {
1418 lua_State* L = e.state();
1419 // L will now point to the destructed
1420 // lua state and be invalid
1421 /* ... */
1422 }
1423 }
1424 </pre>
1425 <p>There's another exception that luabind may throw: <tt class="literal"><span class="pre">luabind::cast_failed</span></tt>,
1426 this exception is thrown from <tt class="literal"><span class="pre">call_function<></span></tt>, <tt class="literal"><span class="pre">call_member<></span></tt> or when
1427 <tt class="literal"><span class="pre">functor<></span></tt> is invoked. It means that the return value from the lua function
1428 couldn't be converted to a C++ value. It is also thrown from <tt class="literal"><span class="pre">object_cast<></span></tt>
1429 if the cast cannot be made.</p>
1430 <p>The synopsis for <tt class="literal"><span class="pre">luabind::cast_failed</span></tt> is:</p>
1432 class cast_failed : public std::exception
1433 {
1434 public:
1435 cast_failed(lua_State*);
1436 lua_State* state() const throw();
1437 LUABIND_TYPE_INFO info() const throw();
1438 virtual const char* what() const throw();
1439 };
1440 </pre>
1441 <p>Again, the state member function returns a pointer to the lua state where the
1442 error occurred. See the example above to see where this pointer may be invalid.</p>
1443 <p>The info member function returns the user defined <tt class="literal"><span class="pre">LUABIND_TYPE_INFO</span></tt>, which
1444 defaults to a <tt class="literal"><span class="pre">const</span> <span class="pre">std::type_info*</span></tt>. This type info describes the type that
1445 we tried to cast a lua value to.</p>
1446 <p>If you have defined <tt class="literal"><span class="pre">LUABIND_NO_EXCEPTIONS</span></tt> none of these exceptions will be
1447 thrown, instead you can set two callback functions that are called instead.
1448 These two functions are only defined if <tt class="literal"><span class="pre">LUABIND_NO_EXCEPTIONS</span></tt> are defined.</p>
1450 luabind::set_error_callback(void(*)(lua_State*))
1451 </pre>
1452 <p>The function you set will be called when a runtime-error occur in lua code. You
1453 can find an error message on top of the lua stack. This function is not
1454 expected to return, if it does luabind will call <tt class="literal"><span class="pre">std::terminate()</span></tt>.</p>
1456 luabind::set_cast_failed_callback(void(*)(lua_State*, LUABIND_TYPE_INFO))
1457 </pre>
1458 <p>The function you set is called instead of throwing <tt class="literal"><span class="pre">cast_failed</span></tt>. This function
1459 is not expected to return, if it does luabind will call <tt class="literal"><span class="pre">std::terminate()</span></tt>.</p>
1460 </div>
1463 <p>Sometimes it is necessary to control how luabind passes arguments and return
1464 value, to do this we have policies. These are the policies that can be used:</p>
1467 <p>This will make a copy of the parameter. This is the default behavior when
1468 passing parameters by-value. Note that this can only be used when passing from
1469 C++ to lua. This policy requires that the parameter type has a copy
1470 constructor.</p>
1471 <p>To use this policy you need to include <tt class="literal"><span class="pre">luabind/copy_policy.hpp</span></tt>.</p>
1472 </div>
1478 base* create_base()
1479 {
1480 return new base();
1481 }
1483 ...
1485 module(L)
1486 [
1488 ];
1489 </pre>
1490 <p>Here we need to make sure lua understands that it should adopt the pointer
1491 returned by the factory-function. This can be done using the adopt-policy.</p>
1493 module(L)
1494 [
1496 ];
1497 </pre>
1500 base* set_and_get_new(base* ptr)
1501 {
1502 base_ptrs.push_back(ptr);
1503 return new base();
1504 }
1506 module(L)
1507 [
1509 adopt(return_value) + adopt(_1))
1510 ];
1511 </pre>
1512 <p>When lua adopts a pointer, it will call delete on it. This means that it cannot
1513 adopt pointers allocated with another allocator than new (no malloc for
1514 example).</p>
1515 <p>To use this policy you need to include <tt class="literal"><span class="pre">luabind/adopt_policy.hpp</span></tt>.</p>
1516 </div>
1519 <p>The dependency policy is used to create life-time dependencies between values.
1520 Consider the following example:</p>
1522 struct A
1523 {
1524 B member;
1526 const B& get_member()
1527 {
1528 return member;
1529 }
1530 };
1531 </pre>
1534 module(L)
1535 [
1537 .def(constructor<>())
1539 ];
1540 </pre>
1541 <p>However, since the return value of get_member is a reference to a member of A,
1542 this will create some life-time issues. For example:</p>
1545 a = A()
1546 b = a:get_member() -- b points to a member of a
1547 a = nil
1548 collectgarbage(0) -- since there are no references left to a, it is
1549 -- removed
1550 -- at this point, b is pointing into a removed object
1551 </pre>
1552 <p>When using the dependency-policy, it is possible to tell luabind to tie the
1553 lifetime of one object to another, like this:</p>
1555 module(L)
1556 [
1558 .def(constructor<>())
1560 ];
1561 </pre>
1562 <p>This will create a dependency between the return-value of the function, and the
1563 self-object. This means that the self-object will be kept alive as long as the
1564 result is still alive.</p>
1567 a = A()
1568 b = a:get_member() -- b points to a member of a
1569 a = nil
1570 collectgarbage(0) -- a is dependent on b, so it isn't removed
1571 b = nil
1572 collectgarbage(0) -- all dependencies to a gone, a is removed
1573 </pre>
1574 <p>To use this policy you need to include <tt class="literal"><span class="pre">luabind/dependency_policy.hpp</span></tt>.</p>
1575 </div>
1577 <h2><a class="toc-backref" href="#id33" name="return-reference-to">12.4 Return reference to</a></h2>
1578 <p>It is very common to return references to arguments or the this-pointer to
1579 allow for chaining in C++.</p>
1581 struct A
1582 {
1583 float val;
1585 A& set(float v)
1586 {
1587 val = v;
1588 return *this;
1589 }
1590 };
1591 </pre>
1592 <p>When luabind generates code for this, it will create a new object for the
1593 return-value, pointing to the self-object. This isn't a problem, but could be a
1594 bit inefficient. When using the return_reference_to-policy we have the ability
1595 to tell luabind that the return-value is already on the lua stack.</p>
1597 module(L)
1598 [
1600 .def(constructor<>())
1602 ];
1603 </pre>
1604 <p>Instead of creating a new object, luabind will just copy the object that is
1605 already on the stack.</p>
1608 This policy ignores all type information and should be used only it
1609 situations where the parameter type is a perfect match to the
1610 return-type (such as in the example).</div>
1611 <p>To use this policy you need to include <tt class="literal"><span class="pre">luabind/return_reference_to_policy.hpp</span></tt>.</p>
1612 </div>
1615 <p>This policy makes it possible to wrap functions that take non const references
1616 as its parameters with the intention to write return values to them.</p>
1619 </pre>
1622 void f(float* val) { *val = *val + 10.f; }
1623 </pre>
1626 module(L)
1627 [
1629 ];
1630 </pre>
1631 <p>When invoking this function from lua it will return the value assigned to its
1632 parameter.</p>
1636 > print(a)
1637 20
1638 </pre>
1639 <p>When this policy is used in conjunction with user define types we often need
1640 to do ownership transfers.</p>
1642 struct A;
1644 void f1(A*& obj) { obj = new A(); }
1645 void f2(A** obj) { *obj = new A(); }
1646 </pre>
1647 <p>Here we need to make sure luabind takes control over object returned, for
1648 this we use the adopt policy:</p>
1650 module(L)
1651 [
1655 ];
1656 </pre>
1657 <p>Here we are using adopt as an internal policy to out_value. The index
1658 specified, _2, means adopt will be used to convert the value back to lua.
1659 Using _1 means the policy will be used when converting from lua to C++.</p>
1660 <p>To use this policy you need to include <tt class="literal"><span class="pre">luabind/out_value_policy.hpp</span></tt>.</p>
1661 </div>
1664 <p>This policy works in exactly the same way as out_value, except that it
1665 replaces the parameters with default-constructed objects.</p>
1668 {
1669 x = 3.f;
1670 y = 4.f;
1671 }
1673 ...
1675 module(L)
1676 [
1678 pure_out_value(_1) + pure_out_value(_2))
1679 ];
1680 </pre>
1683 > x, y = get()
1684 > print(x, y)
1685 3 5
1686 </pre>
1687 <p>Like out_value, it is possible to specify an internal policy used then
1688 converting the values back to lua.</p>
1690 void get(test_class*& obj)
1691 {
1692 obj = new test_class();
1693 }
1695 ...
1697 module(L)
1698 [
1700 ];
1701 </pre>
1702 </div>
1705 <p>This is a very simple policy which makes it possible to throw away
1706 the value returned by a C++ function, instead of converting it to
1707 lua. This example makes sure the this reference never gets converted
1708 to lua.</p>
1710 struct simple
1711 {
1713 {
1714 name = n;
1715 return *this;
1716 }
1718 std::string name;
1719 };
1721 ...
1723 module(L)
1724 [
1727 ];
1728 </pre>
1729 <p>To use this policy you need to include <tt class="literal"><span class="pre">luabind/discard_result_policy.hpp</span></tt>.</p>
1730 </div>
1732 <h2><a class="toc-backref" href="#id37" name="return-stl-iterator">12.8 Return STL iterator</a></h2>
1733 <p>This policy converts an STL container to a generator function that can be used
1734 in lua to iterate over the container. It works on any container that defines
1735 <tt class="literal"><span class="pre">begin()</span></tt> and <tt class="literal"><span class="pre">end()</span></tt> member functions (they have to return iterators). It
1736 can be used like this:</p>
1738 struct A
1739 {
1741 };
1744 module(L)
1745 [
1748 ];
1749 </pre>
1752 a = A()
1754 for name in a.names do
1755 print(name)
1756 end
1757 </pre>
1758 <p>To use this policy you need to include <tt class="literal"><span class="pre">luabind/iterator_policy.hpp</span></tt>.</p>
1759 </div>
1762 <p>This policy will cause the function to always yield the current thread when
1763 returning. See the lua manual for restrictions on yield.</p>
1764 </div>
1765 </div>
1767 <h1><a class="toc-backref" href="#id39" name="splitting-up-the-registration">13 Splitting up the registration</a></h1>
1770 luabind::scope register_a()
1771 {
1772 return
1775 ;
1776 }
1777 </pre>
1780 luabind::scope register_b()
1781 {
1782 return
1785 ;
1786 }
1787 </pre>
1790 luabind::scope register_a();
1791 luabind::scope register_b();
1793 void register_module(lua_State* L)
1794 {
1796 [
1797 register_a(),
1798 register_b()
1799 ];
1800 }
1801 </pre>
1802 </div>
1805 <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
1806 error handler function to <tt class="literal"><span class="pre">lua_pcall()</span></tt>. Luabind makes use of
1807 <tt class="literal"><span class="pre">lua_pcall()</span></tt> internally when calling methods and functions. It is
1808 possible to set the error handler function that Luabind will use
1809 globally:</p>
1811 typedef void(*pcall_callback_fun)(lua_State*);
1812 void set_pcall_callback(pcall_callback_fun fn);
1813 </pre>
1814 <p>This is primarily useful for adding more information to the error message
1815 returned by a failed protected call.</p>
1818 <p>There are a number of configuration options available when building luabind.
1819 It is very important that your project has the exact same conmfiguration
1820 options as the ones given when the library was build! The exceptions are the
1821 <tt class="literal"><span class="pre">LUABIND_MAX_ARITY</span></tt> and <tt class="literal"><span class="pre">LUABIND_MAX_BASES</span></tt> which are template-based
1822 options and only matters when you use the library (which means they can
1823 differ from the settings of the library).</p>
1824 <p>The default settings which will be used if no other settings are given
1826 <p>If you want to change the settings of the library, you can modify the
1827 config file. It is included and used by all makefiles. You can change paths
1828 to lua and boost in there as well.</p>
1829 <dl>
1831 <dd>Controls the maximum arity of functions that are registered with luabind.
1832 You can't register functions that takes more parameters than the number
1833 this macro is set to. It defaults to 5, so, if your functions have greater
1834 arity you have to redefine it. A high limit will increase compilation time.</dd>
1836 <dd>Controls the maximum number of classes one class can derive from in
1837 luabind (the number of classes specified within <tt class="literal"><span class="pre">bases<></span></tt>).
1838 <tt class="literal"><span class="pre">LUABIND_MAX_BASES</span></tt> defaults to 4. A high limit will increase
1839 compilation time.</dd>
1842 calls. If illegal function calls are made (e.g. giving parameters that
1843 doesn't match the function signature) they will not be detected by luabind
1844 and the application will probably crash. Error checking could be disabled
1845 when shipping a release build (given that no end-user has access to write
1846 custom lua code). Note that function parameter matching will be done if a
1847 function is overloaded, since otherwise it's impossible to know which one
1848 was called. Functions will still be able to throw exceptions when error
1849 checking is disabled.</p>
1852 </dd>
1855 This will in many cases disable run-time errors, when performing invalid
1856 casts or calling lua functions that fails or returns values that cannot
1857 be converted by the given policy. luabind requires that no function called
1858 directly or indirectly by luabind throws an exception (throwing exceptions
1859 through lua has undefined behavior).</p>
1861 they will be replaced with calls to the callback functions set with
1862 <tt class="literal"><span class="pre">set_error_callback()</span></tt> and <tt class="literal"><span class="pre">set_cast_failed_callback()</span></tt>.</p>
1863 </dd>
1865 <dd>If you want to link dynamically against lua, you can set this define to
1866 the import-keyword on your compiler and platform. On windows in devstudio
1867 this should be <tt class="literal"><span class="pre">__declspec(dllimport)</span></tt> if you want to link against lua
1868 as a dll.</dd>
1870 <dd>If you want to link against luabind as a dll (in devstudio), you can
1871 define <tt class="literal"><span class="pre">LUABIND_EXPORT</span></tt> to <tt class="literal"><span class="pre">__declspec(dllexport)</span></tt> and
1872 <tt class="literal"><span class="pre">LUABIND_IMPORT</span></tt> to <tt class="literal"><span class="pre">__declspec(dllimport)</span></tt>.
1873 Note that you have to link against lua as a dll aswell, to make it work.</dd>
1874 <dt>LUABIND_TYPE_INFO, LUABIND_TYPE_INFO_EQUAL(i1,i2), LUABIND_TYPEID(t), LUABIND_INVALID_TYPE_INFO</dt>
1876 type-info structure with the <tt class="literal"><span class="pre">LUABIND_TYPE_INFO</span></tt> define. Your type-info
1877 structure must be copyable and must be able to compare itself against
1878 other type-info structures. You supply the compare function through the
1879 <tt class="literal"><span class="pre">LUABIND_TYPE_INFO_EQUAL()</span></tt> define. It should compare the two type-info
1880 structures it is given and return true if they represent the same type and
1881 false otherwise. You also have to supply a function to generate your
1882 type-info structure. You do this through the <tt class="literal"><span class="pre">LUABIND_TYPEID()</span></tt> define.
1883 It should return your type-info structure and it takes a type as its
1884 parameter. That is, a compile time parameter.
1885 <tt class="literal"><span class="pre">LUABIND_INVALID_TYPE_INFO</span></tt> macro should be defined to an invalid type.
1886 No other type should be able to produce this type info. To use it you
1887 probably have to make a traits class with specializations for all classes
1888 that you have type-info for. Like this:</p>
1890 class A;
1891 class B;
1892 class C;
1899 </pre>
1900 <p>If you have set up your own RTTI system like this (by using integers to
1901 identify types) you can have luabind use it with the following defines:</p>
1903 #define LUABIND_TYPE_INFO const std::type_info*
1904 #define LUABIND_TYPEID(t) &typeid(t)
1905 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
1906 #define LUABIND_INVALID_TYPE_INFO &typeid(detail::null_type)
1907 </pre>
1908 <p class="last">Currently the type given through <tt class="literal"><span class="pre">LUABIND_TYPE_INFO</span></tt> must be less-than
1909 comparable!</p>
1910 </dd>
1912 <dd>This define will disable all asserts and should be defined in a release
1913 build.</dd>
1914 </dl>
1915 </div>
1916 </div>
1918 <h1><a class="toc-backref" href="#id42" name="implementation-notes">15 Implementation notes</a></h1>
1919 <p>The classes and objects are implemented as user data in lua. To make sure that
1920 the user data really is the internal structure it is supposed to be, we tag
1921 their metatables. A user data who's metatable contains a boolean member named
1922 <tt class="literal"><span class="pre">__luabind_classrep</span></tt> is expected to be a class exported by luabind. A user
1923 data who's metatable contains a boolean member named <tt class="literal"><span class="pre">__luabind_class</span></tt> is
1924 expected to be an instantiation of a luabind class.</p>
1925 <p>This means that if you make your own user data and tags its metatable with the
1926 exact same names, you can very easily fool luabind and crash the application.</p>
1927 <p>In the lua registry, luabind keeps an entry called <tt class="literal"><span class="pre">__luabind_classes</span></tt>. It
1928 should not be removed or overwritten.</p>
1929 <p>In the global table, a variable called <tt class="literal"><span class="pre">super</span></tt> is used every time a
1930 constructor in a lua-class is called. This is to make it easy for that
1931 constructor to call its base class' constructor. So, if you have a global
1932 variable named super it may very well be overwritten. This is probably not the
1933 best solution, and this restriction may very well be removed in the future.</p>
1934 <p>Luabind uses two upvalues for functions that it registers. The first is a
1935 userdata containing a list of overloads for the function, the other is a light
1936 userdata with the value 0x1337, this last value is used to identify functions
1937 registered by luabind. It should be virtually impossible to have such a pointer
1938 as secondary upvalue by pure chance. This means, if you are trying to replace
1939 an existing function with a luabind function, luabind will see that the
1940 secondary upvalue isn't the magic id number and replace it. If it can identify
1941 the function to be a luabind function, it won't replace it, but rather add
1942 another overload to it.</p>
1943 <p>Inside the luabind namespace, there's another namespace called detail. This
1944 namespace contains non-public classes and are not supposed to be used directly.</p>
1945 </div>
1948 <ul>
1949 <li><p class="first"><cite>the attribute '<class-name>.<attribute-name>' is read only</cite></p>
1950 <blockquote>
1952 or there's no setter-method registered on that property name. See the
1953 properties section.</p>
1954 </blockquote>
1955 </li>
1956 <li><p class="first"><cite>the attribute '<class-name>.<attribute-name>' is of type: (<class-name>)
1958 <blockquote>
1959 <p>This error is generated if you try to assign an attribute with a value
1960 of a type that cannot be converted to the attribute's type.</p>
1961 </blockquote>
1962 </li>
1963 <li><p class="first"><cite><class-name>() threw an exception, <class-name>:<function-name>() threw an
1964 exception</cite></p>
1965 <blockquote>
1966 <p>The class' constructor or member function threw an unknown exception.
1967 Known exceptions are const char*, std::exception. See the
1969 </blockquote>
1970 </li>
1971 <li><p class="first"><cite>no overload of '<class-name>:<function-name>' matched the arguments
1973 </li>
1974 <li><p class="first"><cite>no match for function call '<function-name>' with the parameters
1976 </li>
1977 <li><p class="first"><cite>no constructor of <class-name> matched the arguments (<parameter-types>)</cite></p>
1978 </li>
1979 <li><p class="first"><cite>no operator <operator-name> matched the arguments (<parameter-types>)</cite></p>
1980 <blockquote>
1981 <p>No function/operator with the given name takes the parameters you gave
1982 it. You have either misspelled the function name, or given it incorrect
1983 parameters. This error is followed by a list of possible candidate
1984 functions to help you figure out what parameter has the wrong type. If
1985 the candidate list is empty there's no function at all with that name.
1986 See the signature matching section.</p>
1987 </blockquote>
1988 </li>
1989 <li><p class="first"><cite>call of overloaded '<class-name>:<function-name>(<parameter-types>)' is
1990 ambiguous</cite></p>
1991 </li>
1992 <li><p class="first"><cite>ambiguous match for function call '<function-name>' with the parameters
1994 </li>
1995 <li><p class="first"><cite>call of overloaded constructor '<class-name>(<parameter-types>)' is
1996 ambiguous</cite></p>
1997 </li>
1998 <li><p class="first"><cite>call of overloaded operator <operator-name> (<parameter-types>) is
1999 ambiguous</cite></p>
2000 <blockquote>
2001 <p>This means that the function/operator you are trying to call has at least
2002 one other overload that matches the arguments just as good as the first
2003 overload.</p>
2004 </blockquote>
2005 </li>
2006 <li><p class="first"><cite>cannot derive from C++ class '<class-name>'. It does not have a wrapped
2007 type.</cite></p>
2008 <blockquote>
2009 <p>You are trying to derive a lua class from a C++ class that doesn't have a
2010 wrapped type. You have to give your C++ class a wrapped type when you
2011 register it with lua. See the deriving in lua section.</p>
2012 </blockquote>
2013 </li>
2015 </li>
2016 <li><p class="first"><cite>cannot set property '<class-name>.<attribute_name>' because it's read only</cite></p>
2017 <blockquote>
2018 <p>The attribute you are trying to set is registered as read only. If you want
2019 it to be writeable you have to change your class registration and use
2020 def_readwrite() instead of def_readonly(). Alternatively (if your
2021 attribute is a property with getter and setter functions), you have to
2022 give a setter function when declaring your attribute. See the properties section.</p>
2023 </blockquote>
2024 </li>
2025 <li><p class="first"><cite>no static '<enum-name>' in class '<class-name>'</cite></p>
2026 <blockquote>
2027 <p>You will get this error message if you are trying to access an enum that
2028 doesn't exist. Read about how to declare enums.</p>
2029 </blockquote>
2030 </li>
2032 <blockquote>
2033 <p>You have written a malformed class definition in lua. The format is: class
2035 class, you have to break the line directly after the class declaration.</p>
2036 </blockquote>
2037 </li>
2039 <blockquote>
2040 <p>You have written a malformed class definition in lua. The class function
2041 expects a string as argument. That string is the name of the lua class to
2042 define.</p>
2043 </blockquote>
2044 </li>
2045 </ul>
2046 </div>
2049 <dl>
2051 <dd>If you're having problem with functions
2052 that cannot be converted from 'void (__stdcall <em>)(int,int)' to 'void
2053 (__cdecl</em>)(int,int)'. You can change the project settings to make the
2054 compiler generate functions with __cdecl calling conventions. This is
2055 a problem in developer studio.</dd>
2057 <dd>You cannot register a function with ellipses in its signature. Since
2058 ellipses don't preserve type safety, those should be avoided anyway.</dd>
2060 <dd>If you, in visual studio, get fatal error C1204: compiler limit :
2061 internal structure overflow. You should try to split that compilation
2062 unit up in smaller ones.</dd>
2064 <dd>Visual Studio doesn't like anonymous namespaces in its precompiled
2065 headers. If you encounter this problem you can disable precompiled
2066 headers for the compilation unit (cpp-file) that uses luabind.</dd>
2068 <dd>In visual studio you will probably hit this error. To fix it you have to
2069 increase the internal heap with a command-line option. We managed to
2070 compile the test suit with /Zm300, but you may need a larger heap then
2071 that.</dd>
2072 <dt>error C1055: compiler limit <span class="classifier-delimiter">:</span> <span class="classifier">out of keys in VC</span></dt>
2073 <dd>It seems that this error occurs when too many assert() are used in a
2074 program, or more specifically, the __LINE__ macro. It seems to be fixed by
2075 changing /ZI (Program database for edit and continue) to /Zi
2076 (Program database).</dd>
2079 debug-info and symbols (luabind consists of a lot of functions). Also,
2080 if built in debug mode, no optimizations were applied, luabind relies on
2081 that the compiler is able to inline functions. If you built in release
2082 mode, try running strip on your executable to remove export-symbols,
2083 this will trim down the size.</p>
2085 compared to gcc on other platforms and other compilers.</p>
2086 </dd>
2087 </dl>
2088 <!-- HUH?! // check the magic number that identifies luabind's functions -->
2089 <dl>
2092 class. Because there's no lua counterpart to C++ templates. For example,
2095 module(L)
2096 [
2100 ];
2101 </pre>
2102 </dd>
2103 </dl>
2104 <!-- Again, irrelevant to docs: Note that the space between the two > is required by C++. -->
2105 <dl>
2108 object is collected. Note that lua has to own the object to collect it.
2109 If you pass it to C++ and gives up ownership (with adopt policy) it will
2110 no longer be owned by lua, and not collected.</p>
2112 you want to be sure that the correct destructor is called (this apply to C++
2113 in general).</p>
2114 </dd>
2115 </dl>
2116 <!-- And again, the above is irrelevant to docs. This isn't a general C++ FAQ. -->
2117 <dl>
2118 <dt>Fatal Error C1063 compiler limit <span class="classifier-delimiter">:</span> <span class="classifier">compiler stack overflow in VC</span></dt>
2119 <dd>VC6.5 chokes on warnings, if you are getting alot of warnings from your
2120 code try suppressing them with a pragma directive, this should solve the
2121 problem.</dd>
2123 <dd>When you build luabind, lua and you project, make sure you link against
2124 the runtime dynamically (as a dll).</dd>
2126 <dd>This is because there is no way to get a reference to a lua value. Have
2127 a look at out_value and pure_out_value policies.</dd>
2128 </dl>
2129 </div>
2133 <li>You cannot use strings with extra nulls in them as member names that refers
2134 to C++ members.</li>
2135 <li>If one class registers two functions with the same name and the same
2136 signature, there's currently no error. The last registered function will
2137 be the one that's used.</li>
2139 </ul>
2140 <!-- remove? - Visual studio have problems selecting the correct overload of std::swap()
2141 for luabind::object. -->
2143 <li>If you register a function and later rename it, error messages will use the
2144 original function name.</li>
2145 </ul>
2146 </div>
2150 All rights reserved.</p>
2151 <p>This library was inspired by Dave Abrahams' Boost.Python library which can be
2153 <p>Evan Wies has contributed with thorough testing and countless bug reports and
2154 feature ideas.</p>
2156 </div>
2157 </div>
2162 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
2163 </div>
2164 </body>
2165 </html>