| blob | 7efc71688fd9a58bce9a68395b98095db11aca77 |
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>
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">
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">
75 <li><a class="reference" href="#nested-scopes-and-static-functions" id="id60" name="id60">8.4 Nested scopes and static functions</a></li>
76 <li><a class="reference" href="#derived-classes" id="id61" name="id61">8.5 Derived classes</a></li>
77 <li><a class="reference" href="#smart-pointers" id="id62" name="id62">8.6 Smart pointers</a></li>
78 </ul>
79 </li>
82 <li><a class="reference" href="#related-functions" id="id65" name="id65">9.2 Related functions</a></li>
84 </ul>
85 </li>
86 <li><a class="reference" href="#defining-classes-in-lua" id="id67" name="id67">10 Defining classes in Lua</a><ul class="auto-toc">
87 <li><a class="reference" href="#deriving-in-lua" id="id68" name="id68">10.1 Deriving in lua</a></li>
88 <li><a class="reference" href="#overloading-operators" id="id69" name="id69">10.2 Overloading operators</a></li>
91 </ul>
92 </li>
94 <li><a class="reference" href="#policies" id="id73" name="id73">12 Policies</a><ul class="auto-toc">
98 <li><a class="reference" href="#pure-out-value" id="id77" name="id77">12.4 pure_out_value</a></li>
99 <li><a class="reference" href="#return-reference-to" id="id78" name="id78">12.5 return_reference_to</a></li>
101 <li><a class="reference" href="#discard-result" id="id80" name="id80">12.7 discard_result</a></li>
102 <li><a class="reference" href="#return-stl-iterator" id="id81" name="id81">12.8 return_stl_iterator</a></li>
105 </ul>
106 </li>
107 <li><a class="reference" href="#splitting-up-the-registration" id="id84" name="id84">13 Splitting up the registration</a></li>
108 <li><a class="reference" href="#configuration" id="id85" name="id85">14 Configuration</a><ul class="auto-toc">
109 <li><a class="reference" href="#build-options" id="id86" name="id86">14.1 Build options</a></li>
110 </ul>
111 </li>
112 <li><a class="reference" href="#implementation-notes" id="id87" name="id87">15 Implementation notes</a></li>
113 <li><a class="reference" href="#error-messages" id="id88" name="id88">16 Error messages</a></li>
116 <li><a class="reference" href="#acknowledgments" id="id91" name="id91">19 Acknowledgments</a></li>
117 </ul>
118 </div>
121 <p>Luabind is a library that helps you create bindings between C++ and Lua. It has
122 the ability to expose functions and classes, written in C++, to Lua. It will
123 also supply the functionality to define classes in Lua and let them derive from
124 other Lua classes or C++ classes. Lua classes can override virtual functions
125 from their C++ base classes. It is written towards Lua 5.0, and does not work
127 <p>It is implemented utilizing template meta programming. That means that you
128 don't need an extra preprocess pass to compile your project (it is done by the
129 compiler). It also means you don't (usually) have to know the exact signatureof
130 each function you register, since the library will generate code depending on
131 the compile-time type of the function (which includes the signature). The main
132 drawback of this approach is that the compilation time will increase for the
133 file that does the registration, it is therefore recommended that you register
134 everything in the same cpp-file.</p>
135 <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>
136 <p>We are very interested in hearing about projects that use luabind, please let
137 us know about your project.</p>
138 </div>
142 <blockquote>
158 </ul>
159 </blockquote>
160 </div>
164 <blockquote>
175 </ul>
176 </blockquote>
178 <blockquote>
181 </ul>
182 </blockquote>
184 means that const member functions are treated as non-const member
185 functions.</p>
186 <p>If you have tried luabind with a compiler not listed here, let us know
187 your result with it.</p>
188 </div>
191 <p>To keep down the compilation-time luabind is built as a library. This means you
192 have to either build it and lika against it, or include its source files in
193 your project. You also have to make sure the luabind directory is somewhere in
194 your compiler's include path. It requires <a class="reference" href="http://www.boost.org">Boost</a> 1.31.0 to be installed (only
195 boost headers). It also requires that Lua is installed.</p>
196 <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
197 luabind with Boost.Build you need to set two environment variables:</p>
198 <dl>
202 <dd>Point this to your Lua directory. The build system will assume that the
203 include and library files are located in <tt class="literal"><span class="pre">$(LUA_PATH)/include/</span></tt> and
205 </dl>
206 <p>For backward compatibility, there is also a makefile in the root-directory that
207 will build the library and the test program. If you are using a UNIX-system (or
208 cygwin) they will make it easy to build luabind as a static library. If you are
209 using Visual Studio it may be easier to include the files in the src directory
210 in your project.</p>
211 <p>When building luabind you have several options that may streamline the library
212 to better suit your needs. It is extremely important that your application has
213 the same settings as the library was built with. The available options are
215 <p>If you want to change the settings to differ from the default, it's recommended
216 that you define the settings on the commandline of all your files (in the
217 project settings in visual studio).</p>
218 </div>
221 <p>To use luabind, you must include <tt class="literal"><span class="pre">lua.h</span></tt> and luabind's main header file:</p>
224 {
226 }
229 </pre>
230 <p>This includes support for both registering classes and functions. If you just
231 want to have support for functions or classes you can include
232 <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>
236 </pre>
237 <p>The first thing you need to do is to call <tt class="literal"><span class="pre">luabind::open(lua_State*)</span></tt> which
238 will register the functions to create classes from Lua, and initialize some
239 state-global structures used by luabind. If you don't call this function you
240 will hit asserts later in the library. There is no corresponding close function
241 because once a class has been registered in Lua, there really isn't any good
242 way to remove it. Partly because any remaining instances of that class relies
243 on the class being there. Everything will be cleaned up when the state is
244 closed though.</p>
245 <!-- Isn't this wrong? Don't we include lua.h using lua_include.hpp ? -->
246 <p>Luabind's headers will never include <tt class="literal"><span class="pre">lua.h</span></tt> directly, but through
247 <tt class="literal"><span class="pre"><luabind/lua_include.hpp></span></tt>. If you for some reason need to include another
248 Lua header, you can modify this file.</p>
255 void greet()
256 {
258 }
261 {
262 using namespace luabind;
264 open(L);
266 module(L)
267 [
269 ];
271 return 0;
272 }
273 </pre>
276 > loadlib('hello_world.dll', 'init')()
277 > greet()
278 Hello world!
279 >
280 </pre>
281 </div>
282 </div>
285 <p>Everything that gets registered in Lua is registered in a namespace (Lua
286 tables) or in the global scope (called module). All registrations must be
287 surrounded by its scope. To define a module, the <tt class="literal"><span class="pre">luabind::module</span></tt> class is
288 used. It is used like this:</p>
290 module(L)
291 [
292 // declarations
293 ];
294 </pre>
295 <p>This will register all declared functions or classes in the global namespace in
296 Lua. If you want to have a namespace for your module (like the standard
297 libraries) you can give a name to the constructor, like this:</p>
300 [
301 // declarations
302 ];
303 </pre>
305 <p>If you want nested namespaces you can use the <tt class="literal"><span class="pre">luabind::namespace_</span></tt> class. It
306 works exactly as <tt class="literal"><span class="pre">luabind::module</span></tt> except that it doesn't take a lua_State*
307 in it's constructor. An example of its usage could look like this:</p>
310 [
311 // declarations
314 [
315 // library-private declarations
316 ]
317 ];
318 </pre>
321 module(L)
322 [
324 [
325 // declarations
326 ]
328 ];
329 </pre>
332 [
333 // declarations
334 ];
335 </pre>
338 module(L)
339 [
345 ];
346 </pre>
347 <p>More about the actual declarations in the <a class="reference" href="#binding-functions-to-lua">Binding functions to Lua</a> and
349 <p>A word of caution, if you are in really bad need for performance, putting your
350 functions in tables will increase the lookup time.</p>
351 </div>
354 <p>To bind functions to Lua you use the function <tt class="literal"><span class="pre">luabind::def()</span></tt>. It has the
355 following synopsis:</p>
358 void def(const char* name, F f, const Policies&);
359 </pre>
363 <li>The Policies parameter is used to describe how parameters and return values
364 are treated by the function, this is an optional parameter. More on this in
366 </ul>
367 <p>An example usage could be if you want to register the function <tt class="literal"><span class="pre">float</span>
370 module(L)
371 [
373 ];
374 </pre>
377 <p>If you have more than one function with the same name, and want to register
378 them in Lua, you have to explicitly give the signature. This is to let C++ know
379 which function you refer to. For example, if you have two functions, <tt class="literal"><span class="pre">int</span>
380 <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>
382 module(L)
383 [
386 ];
387 </pre>
388 </div>
391 <p>luabind will generate code that checks the Lua stack to see if the values there
392 can match your functions' signatures. It will handle implicit typecasts between
393 derived classes, and it will prefer matches with the least number of implicit
394 casts. In a function call, if the function is overloaded and there's no
395 overload that match the parameters better than the other, you have an
396 ambiguity. This will spawn a run-time error, stating that the function call is
397 ambiguous. A simple example of this is to register one function that takes an
398 int and one that takes a float. Since Lua don't distinguish between floats and
399 integers, both will always match.</p>
400 <p>Since all overloads are tested, it will always find the best match (not the
401 first match). This also means that it can handle situations where the only
402 difference in the signature is that one member function is const and the other
403 isn't.</p>
406 <p>To correctly handle ownership transfer, create_a() would need an adopt
407 return value policy. More on this in the <a class="reference" href="#policies">Policies</a> section.</p>
408 </div>
411 struct A
412 {
413 void f();
414 void f() const;
415 };
417 const A* create_a();
419 struct B: A {};
420 struct C: B {};
422 void g(A*);
423 void g(B*);
424 </pre>
427 a1 = create_a()
428 a1:f() -- the const version is called
430 a2 = A()
431 a2:f() -- the non-const version is called
433 a = A()
434 b = B()
435 c = C()
437 g(a) -- calls g(A*)
438 g(b) -- calls g(B*)
439 g(c) -- calls g(B*)
440 </pre>
441 </div>
444 <p>To call a Lua function, you can either use <tt class="literal"><span class="pre">call_function()</span></tt>,
445 an <tt class="literal"><span class="pre">object</span></tt> or <tt class="literal"><span class="pre">functor</span></tt>.</p>
448 Ret call_function(lua_State* L, const char* name, ...)
450 Ret call_function(object const& obj, ...)
451 </pre>
452 <p>There are two overloads of the <tt class="literal"><span class="pre">call_function</span></tt> function, one that calls
453 a function given its name, and one that takes an object that should be a Lua
454 value that can be called as a function.</p>
455 <p>The overload that takes a name can only call global Lua functions. The ...
456 represents a variable number of parameters that are sent to the Lua
457 function. This function call may throw <tt class="literal"><span class="pre">luabind::error</span></tt> if the function
458 call fails.</p>
459 <p>The return value isn't actually Ret (the template parameter), but a proxy
460 object that will do the function call. This enables you to give policies to the
461 call. You do this with the operator[]. You give the policies within the
462 brackets, like this:</p>
465 L
467 , new complex_class()
468 )[ adopt(_1) ];
469 </pre>
470 <p>If you want to pass a parameter as a reference, you have to wrap it with the
475 </pre>
476 </div>
479 <p>To start a Lua thread, you have to call <tt class="literal"><span class="pre">lua_resume()</span></tt>, this means that you
480 cannot use the previous function <tt class="literal"><span class="pre">call_function()</span></tt> to start a thread. You have
481 to use</p>
484 Ret resume_function(lua_State* L, const char* name, ...)
486 Ret resume_function(object const& obj, ...)
487 </pre>
491 Ret resume(lua_State* L, ...)
492 </pre>
493 <p>The first time you start the thread, you have to give it a function to execute. i.e. you
494 have to use <tt class="literal"><span class="pre">resume_function</span></tt>, when the Lua function yeilds, it will return the first
495 value passed in to <tt class="literal"><span class="pre">lua_yield()</span></tt>. When you want to continue the execution, you just call
496 <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
497 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>
498 <p>For yielding C++-functions (without the support of passing data back and forth between the
499 Lua side and the c++ side), you can use the <a class="reference" href="#yield">yield</a> policy.</p>
500 <p>With the overload of <tt class="literal"><span class="pre">resume_function</span></tt> that takes an <a class="reference" href="#object">object</a>, it is important that the
501 object was constructed with the thread as its <tt class="literal"><span class="pre">lua_State*</span></tt>. Like this:</p>
503 lua_State* thread = lua_newthread(L);
505 resume_function(fun);
506 </pre>
507 </div>
508 </div>
511 <p>To register classes you use a class called <tt class="literal"><span class="pre">class_</span></tt>. Its name is supposed to
512 resemble the C++ keyword, to make it look more intuitive. It has an overloaded
513 member function <tt class="literal"><span class="pre">def()</span></tt> that is used to register member functions, operators,
514 constructors, enums and properties on the class. It will return its
515 this-pointer, to let you register more members directly.</p>
518 class testclass
519 {
520 public:
521 testclass(const std::string& s): m_string(s) {}
524 private:
525 std::string m_string;
526 };
527 </pre>
528 <p>To register it with a Lua environment, write as follows (assuming you are using
529 namespace luabind):</p>
531 module(L)
532 [
536 ];
537 </pre>
538 <p>This will register the class with the name testclass and constructor that takes
539 a string as argument and one member function with the name <tt class="literal"><span class="pre">print_string</span></tt>.</p>
542 > a = testclass('a string')
543 > a:print_string()
544 a string
545 </pre>
546 <p>It is also possible to register free functions as member functions. The
547 requirement on the function is that it takes a pointer, const pointer,
548 reference or const reference to the class type as the first parameter. The rest
549 of the parameters are the ones that are visible in Lua, while the object
550 pointer is given as the first parameter. If we have the following C++ code:</p>
552 struct A
553 {
554 int a;
555 };
557 int plus(A* o, int v) { return o->a + v; }
558 </pre>
559 <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>
563 </pre>
564 <p><tt class="literal"><span class="pre">plus()</span></tt> can now be called as a member function on A with one parameter, int.
565 If the object pointer parameter is const, the function will act as if it was a
566 const member function (it can be called on const objects).</p>
569 <p>To register a global data member with a class is easily done. Consider the
570 following class:</p>
572 struct A
573 {
574 int a;
575 };
576 </pre>
579 module(L)
580 [
583 ];
584 </pre>
585 <p>This gives read and write access to the member variable <tt class="literal"><span class="pre">A::a</span></tt>. It is also
586 possible to register attributes with read-only access:</p>
588 module(L)
589 [
592 ];
593 </pre>
594 <p>You can also register getter and setter functions and make them look as if they
595 were a public data member. Consider the following class:</p>
597 class A
598 {
599 public:
600 void set_a(int x) { a = x; }
601 int get_a() const { return a; }
603 private:
604 int a;
605 };
606 </pre>
611 </pre>
612 <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
613 just writing to the data member. If you want to make it read only you can just
614 omit the last parameter.</p>
615 </div>
618 <p>If your class contains enumerated constants (enums), you can register them as
619 well to make them available in Lua. Note that they will not be type safe, all
620 enums are integers in Lua, and all functions that takes an enum, will accept
621 any integer. You register them like this:</p>
623 module(L)
624 [
627 [
631 ]
632 ];
633 </pre>
634 <p>In Lua they are accessed like any data member, except that they are read-only
635 and reached on the class itself rather than on an instance of the class.</p>
638 > print(A.my_enum)
639 4
640 > print(A.another_enum)
641 6
642 </pre>
643 </div>
646 <p>The mechanism for registering operators on your class is pretty simple. You use
647 a global name <tt class="literal"><span class="pre">luabind::self</span></tt> to refer to the class itself and then you just
648 write the operator expression inside the <tt class="literal"><span class="pre">def()</span></tt> call. This class:</p>
650 struct vec
651 {
652 vec operator+(int s);
653 };
654 </pre>
657 module(L)
658 [
661 ];
662 </pre>
663 <p>This will work regardless if your plus operator is defined inside your class or
664 as a free function.</p>
665 <p>If you operator is const (or, when defined as a free function, takes a const
666 reference to the class itself) you have to use <tt class="literal"><span class="pre">const_self</span></tt> instead of
669 module(L)
670 [
673 ];
674 </pre>
678 </pre>
679 <p>This means, no in-place operators. The equality operator (<tt class="literal"><span class="pre">==</span></tt>) has a little
680 hitch; it will not be called if the references are equal. This means that the
681 <tt class="literal"><span class="pre">==</span></tt> operator has to do pretty much what's it's expected to do.</p>
682 <p>In the above example the other operand type is instantiated by writing
683 <tt class="literal"><span class="pre">int()</span></tt>. If the operand type is a complex type that cannot easily be
684 instantiated you can wrap the type in a class called <tt class="literal"><span class="pre">other<></span></tt>. For example:</p>
685 <p>To register this class, we don't want to instantiate a string just to register
686 the operator.</p>
688 struct vec
689 {
690 vec operator+(std::string);
691 };
692 </pre>
693 <p>Instead we use the <tt class="literal"><span class="pre">other<></span></tt> wrapper like this:</p>
695 module(L)
696 [
699 ];
700 </pre>
703 module(L)
704 [
707 ];
708 </pre>
709 <p>There's one special operator. In Lua it's called <tt class="literal"><span class="pre">__tostring</span></tt>, it's not
710 really an operator. It is used for converting objects to strings in a standard
711 way in Lua. If you register this functionality, you will be able to use the lua
712 standard function <tt class="literal"><span class="pre">tostring()</span></tt> for converting you object to a string.</p>
713 <p>To implement this operator in C++ you should supply an <tt class="literal"><span class="pre">operator<<</span></tt> for
714 ostream. Like this example:</p>
716 class number {};
719 ...
721 module(L)
722 [
725 ];
726 </pre>
727 </div>
729 <h2><a name="nested-scopes-and-static-functions">8.4 Nested scopes and static functions</a></h2>
730 <p>It is possible to add nested scopes to a class. This is useful when you need
731 to wrap a nested class, or a static function.</p>
734 .def(constructor<>()
735 <strong>.scope
736 [
739 ]</strong>;
740 </pre>
742 </div>
745 <p>If you want to register classes that derives from other classes, you can
746 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
747 following hierarchy:</p>
749 struct A {};
750 struct B : A {};
751 </pre>
754 module(L)
755 [
758 ];
759 </pre>
760 <p>If you have multiple inheritance you can specify more than one base. If B would
761 also derive from a class C, it would be registered like this:</p>
763 module(L)
764 [
766 ];
767 </pre>
768 <p>Note that you can omit <tt class="literal"><span class="pre">bases<></span></tt> when using single inheritance.</p>
771 If you don't specify that classes derive from each other, luabind will not
772 be able to implicitly cast pointers between the types.</div>
773 </div>
776 <p>When you register a class you can tell luabind that all instances of that class
777 should be held by some kind of smart pointer (boost::shared_ptr for instance).
778 You do this by giving the holder type as an extra template parameter to
779 the <tt class="literal"><span class="pre">class_</span></tt> you are constructing, like this:</p>
781 module(L)
782 [
784 ];
785 </pre>
786 <p>You also have to supply two functions for your smart pointer. One that returns
788 in this case). And one function that extracts the raw pointer from the smart
789 pointer. The first function is needed because luabind has to allow the
790 non-const -> conversion when passing values from Lua to C++. The second
791 function is needed when Lua calls member functions on held types, the this
792 pointer must be a raw pointer, it is also needed to allow the smart_pointer ->
793 raw_pointer conversion from Lua to C++. They look like this:</p>
795 namespace luabind {
799 {
800 return p.get();
801 }
806 {
807 return 0;
808 }
809 }
810 </pre>
815 <colgroup>
818 </colgroup>
822 </tr>
823 </thead>
827 </tr>
830 </tr>
833 </tr>
836 </tr>
839 </tr>
841 <td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
842 </tr>
843 <tr><td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
845 </tr>
846 <tr><td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
848 </tr>
849 <tr><td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
850 <td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
851 </tr>
852 </tbody>
853 </table>
854 </div>
858 <colgroup>
861 </colgroup>
865 </tr>
866 </thead>
870 </tr>
871 <tr><td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
872 <td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
873 </tr>
874 <tr><td><tt class="literal"><span class="pre">holder_type<A></span> <span class="pre">const&</span></tt></td>
876 </tr>
877 <tr><td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span> <span class="pre">const&</span></tt></td>
878 <td><tt class="literal"><span class="pre">holder_type<A</span> <span class="pre">const></span></tt></td>
879 </tr>
880 </tbody>
881 </table>
882 </div>
883 <p>When using a holder type, it can be useful to know if the pointer is valid. For
884 example when using std::auto_ptr, the holder will be invalidated when passed as
885 a parameter to a function. For this purpose there is a member of all object
888 struct X {};
891 module(L)
892 [
894 .def(constructor<>()),
897 ];
898 </pre>
901 > a = X()
902 > f(a)
903 > print a.__ok
904 false
905 </pre>
906 </div>
907 </div>
910 <p>Since functions have to be able to take Lua values (of variable type) we need a
911 wrapper around them. This wrapper is called <tt class="literal"><span class="pre">luabind::object</span></tt>. If the
912 function you register takes an object, it will match any Lua value. To use it,
917 class object
918 {
919 public:
920 class iterator;
921 class raw_iterator;
922 class array_iterator;
925 object(lua_State*, T const& value);
926 object(object const&);
927 object(lua_State*);
928 object();
930 ~object();
932 iterator begin() const;
933 iterator end() const;
934 raw_iterator raw_begin() const;
935 raw_iterator raw_end() const;
936 array_iterator abegin() const;
937 array_iterator aend() const;
939 void set();
940 lua_State* lua_state() const;
941 void pushvalue() const;
942 bool is_valid() const;
943 operator safe_bool_type() const;
949 object at(Key const&) const;
952 object raw_at(Key const&) const;
959 bool operator==(T const&) const;
960 bool operator==(object const&) const;
965 bool operator!=(object const&) const;
967 void swap(object&);
968 int type() const;
978 /* ... */
979 };
980 </pre>
981 </div>
982 <p>When you have a Lua object, you can assign it a new value with the assignment
983 operator (=). When you do this, the <tt class="literal"><span class="pre">default_policy</span></tt> will be used to make the
984 conversion from C++ value to Lua. If your <tt class="literal"><span class="pre">luabind::object</span></tt> is a table you
985 can access its members through the operator[] or the iterators. The value
986 returned from the operator[] is a proxy object that can be used both for
987 reading and writing values into the table (using operator=). Note that it is
988 impossible to know if a Lua value is indexable or not (lua_gettable doesn't
989 fail, it succeeds or crashes). This means that if you're trying to index
990 something that cannot be indexed, you're on your own. Lua will call its
991 <tt class="literal"><span class="pre">panic()</span></tt> function (you can define your own panic function using
992 <tt class="literal"><span class="pre">lua_setpanicf</span></tt>). 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
993 the given table position (like operator[] but only for reading).</p>
994 <p>The ordinary <tt class="literal"><span class="pre">object::iterator</span></tt> uses lua_gettable to extract the values from
995 the table, the standard way that will invoke metamethods if any. The
996 <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
997 lua_rawgeti. The latter will only iterate over numberical keys starting at 1
998 and continue until the first nil value.</p>
999 <p>The <tt class="literal"><span class="pre">lua_state()</span></tt> function returns the Lua state where this object is stored.
1000 If you want to manipulate the object with Lua functions directly you can push
1001 it onto the Lua stack by calling <tt class="literal"><span class="pre">pushvalue()</span></tt>. And set the object's value by
1002 calling <tt class="literal"><span class="pre">set()</span></tt>, which will pop the top value from the Lua stack and assign
1003 it to the object.</p>
1005 <p>The <tt class="literal"><span class="pre">type()</span></tt> member function will return the Lua type of the object. It will
1006 return the same values as lua_type().</p>
1007 <p>The <tt class="literal"><span class="pre">is_valid()</span></tt> function tells you whether the object has been initialized
1008 or not. When created with its default constructor, objects are invalid. To make
1009 an object valid, you can assign it a value. If you want to invalidate an object
1010 you can simply assign it an invalid object.</p>
1011 <!-- So what? implementation detail, leave out of docs
1012 isn't really an implicit cast to bool, but an implicit cast
1013 to a member pointer, since member pointers don't have any arithmetic operators
1014 on them (which can cause hard to find errors). The functionality of the cast
1015 operator -->
1016 <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
1017 that these snippets are equivalent:</p>
1019 object o;
1020 // ...
1021 if (o)
1022 {
1023 // ...
1024 }
1026 ...
1028 object o;
1029 // ...
1030 if (o.is_valid())
1031 {
1032 // ...
1033 }
1034 </pre>
1035 <p>The application operator will call the value as if it was a function. You can
1036 give it any number of parameters (currently the <tt class="literal"><span class="pre">default_policy</span></tt> will be used
1037 for the conversion). The returned object refers to the return value (currently
1038 only one return value is supported). This operator may throw <tt class="literal"><span class="pre">luabind::error</span></tt>
1039 if the function call fails. If you want to specify policies to your function
1040 call, you can use index-operator (operator[]) on the function call, and give
1041 the policies within the [ and ]. Like this:</p>
1043 my_function_object(
1044 2
1045 , 8
1046 , new my_complex_structure(6)
1047 ) [ adopt(_3) ];
1048 </pre>
1049 <p>This tells luabind to make Lua adopt the ownership and responsibility for the
1050 pointer passed in to the lua-function.</p>
1051 <p>It's important that all instances of object have been destructed by the time
1052 the Lua state is closed. The object will keep a pointer to the lua state and
1053 release its Lua object in its destructor.</p>
1056 void my_function(const object& table)
1057 {
1058 if (table.type() == LUA_TTABLE)
1059 {
1064 }
1065 }
1066 </pre>
1067 <p>If you take a <tt class="literal"><span class="pre">luabind::object</span></tt> as a parameter to a function, any Lua value
1068 will match that parameter. That's why we have to make sure it's a table before
1069 we index into it.</p>
1072 <p>The iterators, that are returned by <tt class="literal"><span class="pre">begin()</span></tt> and <tt class="literal"><span class="pre">end()</span></tt> (and their
1073 variants) are (almost) models of the ForwardIterator concept. The exception
1074 is that post increment doesn't exist on them.</p>
1077 class object::iterator
1078 {
1079 iterator();
1080 iterator(const iterator&);
1082 iterator& operator++();
1083 bool operator!=(const iterator&) const;
1086 object key() const;
1089 };
1090 </pre>
1091 <p>The implementation defined return value from the dereference operator is a
1092 proxy object that can be used as if it was an object, it can also be used to
1093 assign the specific table entry with a new value. If you want to assign a value
1094 to an entry pointed to by an iterator, just use the assignment operator on the
1095 dereferenced iterator:</p>
1097 *iter = 5;
1098 </pre>
1099 <p>The <tt class="literal"><span class="pre">key()</span></tt> member returns the key used by the iterator when indexing the
1100 associated Lua table.</p>
1101 </div>
1111 </pre>
1112 </div>
1115 <p>The <tt class="literal"><span class="pre">functor</span></tt> class is similar to object, with the exception that it can only
1116 be used to store functions. If you take it as a parameter, it will only match
1117 functions.</p>
1121 </pre>
1122 <p>It takes one template parameter, the return value of the Lua function it
1123 represents. Currently the functor can have at most one return value (unlike Lua
1124 functions).</p>
1129 class functor
1130 {
1131 public:
1133 functor(lua_State*, char const* name);
1134 functor(functor const&);
1135 ~functor();
1137 bool is_valid() const;
1138 operator safe_bool_type() const;
1139 void reset();
1141 lua_State* lua_state() const;
1142 void pushvalue() const;
1155 /* ... */
1156 };
1157 </pre>
1158 </div>
1159 <p>The application operator takes any parameters. The parameters are converted
1160 into Lua and the function is called. The return value will act as if it was the
1161 type Ret, with the exception that you can use the return value to give policies
1162 to the call. You do this the same way as you do with objects, using the
1163 operator[], and giving the policies inside the brackets.</p>
1164 <p>The <tt class="literal"><span class="pre">is_valid()</span></tt> function works just like the one on object, it tells you if
1165 the functor has been assigned with a valid Lua function. The <tt class="literal"><span class="pre">operator</span>
1166 <span class="pre">safe_bool_type()</span></tt> is an alias for this member function and also works just as
1167 the one found in object.</p>
1170 function f(a, b)
1171 return a + b
1172 end
1173 </pre>
1179 </pre>
1181 to the application operator of <tt class="literal"><span class="pre">luabind::functor</span></tt>, this is because lua
1182 doesn't have signatures for its functions. All Lua functions take any number of
1183 parameters of any type.</p>
1184 <p>If we have a C++ function that takes a <tt class="literal"><span class="pre">luabind::functor</span></tt> and registers it,
1185 it will accept Lua functions passed to it. This enables us to expose APIs that
1186 requires you to register callbacks. For example, if your C++ API looks like
1187 this:</p>
1189 void set_callback(void(*)(int, int));
1190 </pre>
1191 <p>And you want to expose it to Lua, you have to wrap the call to the Lua
1192 function inside a real C++ function, like this:</p>
1196 void callback_wrapper(int a, int b)
1197 {
1198 lua_callback(a, b);
1199 }
1202 {
1203 lua_callback = f;
1204 set_callback(&callback_wrapper);
1205 }
1206 </pre>
1207 <p>And then register <tt class="literal"><span class="pre">set_callback_wrapper</span></tt> instead of registering
1208 <tt class="literal"><span class="pre">set_callback</span></tt>. This will have the effect that when one tries to register the
1209 callback from Lua, your <tt class="literal"><span class="pre">set_callback_wrapper</span></tt> will be called instead and
1210 first set the Lua functor to the given function. It will then call the real
1211 <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
1212 be called whenever the callback should be called, and it will simply call the
1213 Lua function that we registered.</p>
1214 <p>You can also use <tt class="literal"><span class="pre">object_cast</span></tt> to cast an object to a functor.</p>
1215 <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
1216 to its Lua value). If the functor object has longer lifetime than the lua state
1217 (e.g. if it's a global).</p>
1218 </div>
1219 </div>
1222 <p>In addition to binding C++ functions and classes with Lua, luabind also provide
1223 an OO-system in Lua.</p>
1225 class 'lua_testclass'
1227 function lua_testclass:__init(name)
1228 self.name = name
1229 end
1231 function lua_testclass:print()
1232 print(self.name)
1233 end
1235 a = lua_testclass('example')
1236 a:print()
1237 </pre>
1240 class 'derived' (lua_testclass)
1242 function derived:__init() super('derived name')
1243 end
1245 function derived:print()
1246 print('Derived:print() -> ')
1247 lua_testclass.print(self)
1248 end
1249 </pre>
1250 <p>Here the <tt class="literal"><span class="pre">super</span></tt> keyword is used in the constructor to initialize the base
1251 class. The user is required to call <tt class="literal"><span class="pre">super</span></tt> first in the constructor.</p>
1252 <p>As you can see in this example, you can call the base class member functions.
1253 You can find all member functions in the base class, but you will have to give
1254 the this-pointer (<tt class="literal"><span class="pre">self</span></tt>) as first argument.</p>
1257 <p>It is also possible to derive Lua classes from C++ classes, and override
1258 virtual functions with Lua functions. To do this we have to create a wrapper
1259 class for our C++ base class. This is the class that will hold the Lua object
1260 when we instantiate a Lua class.</p>
1262 class base
1263 {
1264 public:
1265 base(const char* s)
1268 virtual void f(int a)
1270 };
1272 struct base_wrapper : base, luabind::wrap_base
1273 {
1274 base_wrapper(const char* s)
1275 : base(s)
1276 {}
1278 virtual void f(int a)
1279 {
1281 }
1283 static void default_f(base* ptr, int a)
1284 {
1285 return ptr->base::f(a);
1286 }
1287 };
1289 ...
1291 module(L)
1292 [
1296 ];
1297 </pre>
1300 Since visual studio 6.5 doesn't support explicit template parameters
1301 to member functions, instead of using the member function <tt class="literal"><span class="pre">call()</span></tt>
1302 you call a free function <tt class="literal"><span class="pre">call_member()</span></tt> and pass the this-pointer
1303 as first parameter.</div>
1304 <p>Note that if you have both base classes and a base class wrapper, you must give
1305 both bases and the base class wrapper type as template parameter to
1306 <tt class="literal"><span class="pre">class_</span></tt> (as done in the example above). The order in which you specify
1307 them is not important. You must also register both the static version and the
1308 virtual version of the function from the wrapper, this is necessary in order
1309 to allow luabind to use both dynamic and static dispatch when calling the function.</p>
1312 It is extremely important that the signatures of the static (default) function
1313 is identical to the virtual function. The fact that one of them is a free
1314 function and the other a member function doesn't matter, but the parameters
1315 as seen from lua must match. It would not have worked if the static function
1316 took a <tt class="literal"><span class="pre">base_wrapper*</span></tt> as its first argument, since the virtual function
1317 takes a <tt class="literal"><span class="pre">base*</span></tt> as its first argument (its this pointer). There's currently
1318 no check in luabind to make sure the signatures match.</div>
1319 <p>If we didn't have a class wrapper, it would not be possible to pass a Lua class
1320 back to C++. Since the entry points of the virtual functions would still point
1321 to the C++ base class, and not to the functions defined in Lua. That's why we
1322 need one function that calls the base class' real function (used if the lua
1323 class doesn't redefine it) and one virtual function that dispatches the call
1324 into luabind, to allow it to select if a Lua function should be called, or if
1325 the original function should be called. If you don't intend to derive from a
1326 C++ class, or if it doesn't have any virtual member functions, you can register
1327 it without a class wrapper.</p>
1328 <p>You don't need to have a class wrapper in order to derive from a class, but if
1329 it has virtual functions you may have silent errors.</p>
1330 <!-- Unnecessary? The rule of thumb is:
1331 If your class has virtual functions, create a wrapper type, if it doesn't
1332 don't create a wrapper type. -->
1333 <p>The wrappers must derive from <tt class="literal"><span class="pre">luabind::wrap_base</span></tt>, it contains a Lua reference
1334 that will hold the Lua instance of the object to make it possible to dispatch
1335 virtual function calls into Lua. This is done through an overloaded member function:</p>
1338 Ret call(char const* name, ...)
1339 </pre>
1340 <p>Its used in a similar way as <tt class="literal"><span class="pre">call_function</span></tt>, with the exception that it doesn't
1341 take a <tt class="literal"><span class="pre">lua_State</span></tt> pointer, and the name is a member function in the Lua class.</p>
1344 The current implementation of <tt class="literal"><span class="pre">call_member</span></tt> is not able to distinguish const
1345 member functions from non-const. If you have a situation where you have an overloaded
1346 virtual function where the only difference in their signatures is their constness, the
1347 wrong overload will be called by <tt class="literal"><span class="pre">call_member</span></tt>. This is rarely the case though.</div>
1350 <p>When a pointer or reference to a registered class with a wrapper is passed
1351 to Lua, luabind will query for it's dynamic type. If the dynamic type
1352 inherits from <tt class="literal"><span class="pre">wrap_base</span></tt>, object identity is preserved.</p>
1354 struct A { .. };
1355 struct A_wrap : A, wrap_base { .. };
1357 A* f(A* ptr) { return ptr; }
1359 module(L)
1360 [
1363 ];
1364 </pre>
1366 > class 'B' (A)
1367 > x = B()
1368 > assert(x == f(x)) -- object identity is preserved when object is
1369 -- passed through C++
1370 </pre>
1371 <p>This functionality relies on RTTI being enabled (that <tt class="literal"><span class="pre">LUABIND_NO_RTTI</span></tt> is
1372 not defined).</p>
1373 </div>
1374 </div>
1377 <p>You can overload most operators in Lua for your classes. You do this by simply
1378 declaring a member function with the same name as an operator (the name of the
1379 metamethods in Lua). The operators you can overload are:</p>
1380 <blockquote>
1393 </ul>
1394 </blockquote>
1395 <p><tt class="literal"><span class="pre">__tostring</span></tt> isn't really an operator, but it's the metamethod that is called
1396 by the standard library's <tt class="literal"><span class="pre">tostring()</span></tt> function. There's one strange behavior
1397 regarding binary operators. You are not guaranteed that the self pointer you
1398 get actually refers to an instance of your class. This is because Lua doesn't
1399 distinguish the two cases where you get the other operand as left hand value or
1400 right hand value. Consider the following examples:</p>
1402 class 'my_class'
1404 function my_class:__init(v)
1405 self.val = v
1406 end
1408 function my_class:__sub(v)
1409 return my_class(self.val - v.val)
1410 end
1412 function my_class:__tostring()
1413 return self.val
1414 end
1415 </pre>
1416 <p>This will work well as long as you only subtracts instances of my_class with
1417 each other. But If you want to be able to subtract ordinary numbers from your
1418 class too, you have to manually check the type of both operands, including the
1419 self object.</p>
1421 function my_class:__sub(v)
1422 if (type(self) == 'number') then
1423 return my_class(self - v.val)
1425 elseif (type(v) == 'number') then
1426 return my_class(self.val - v)
1428 else
1429 -- assume both operands are instances of my_class
1430 return my_class(self.val - v.val)
1432 end
1433 end
1434 </pre>
1435 <p>The reason why <tt class="literal"><span class="pre">__sub</span></tt> is used as an example is because subtraction is not
1436 commutative (the order of the operands matter). That's why luabind cannot
1437 change order of the operands to make the self reference always refer to the
1438 actual class instance.</p>
1439 <p>If you have two different Lua classes with an overloaded operator, the operator
1440 of the right hand side type will be called. If the other operand is a C++ class
1441 with the same operator overloaded, it will be prioritized over the Lua class'
1442 operator. If none of the C++ overloads matches, the Lua class operator will be
1443 called.</p>
1444 </div>
1447 <p>If an object needs to perform actions when it's collected we provide a
1448 <tt class="literal"><span class="pre">__finalize</span></tt> function that can be overridden in lua-classes. The
1449 <tt class="literal"><span class="pre">__finalize</span></tt> functions will be called on all classes in the inheritance
1450 chain, starting with the most derived type.</p>
1452 ...
1454 function lua_testclass:__finalize()
1455 -- called when the an object is collected
1456 end
1457 </pre>
1458 </div>
1461 <p>If your lua C++ classes don't have wrappers (see <a class="reference" href="#deriving-in-lua">Deriving in lua</a>) and
1462 you derive from them in lua, they may be sliced. Meaning, if an object
1463 is passed into C++ as a pointer to its base class, the lua part will be
1464 separated from the C++ base part. This means that if you call virtual
1465 functions on that C++ object, thyey will not be dispatched to the lua
1466 class. It also means that if you adopt the object, the lua part will be
1467 garbage collected.</p>
1469 +--------------------+
1470 | C++ object | <- ownership of this part is transferred
1471 | | to c++ when adopted
1472 +--------------------+
1473 | lua class instance | <- this part is garbage collected when
1474 | and lua members | instance is adopted, since it cannot
1475 +--------------------+ be held by c++.
1476 </pre>
1479 struct A {};
1481 A* filter_a(A* a) { return a; }
1482 void adopt_a(A* a) { delete a; }
1483 </pre>
1485 using namespace luabind;
1487 module(L)
1488 [
1492 ]
1493 </pre>
1496 a = A()
1497 b = filter_a(a)
1498 adopt_a(b)
1499 </pre>
1500 <p>In this example, lua cannot know that <tt class="literal"><span class="pre">b</span></tt> actually is the same object as
1501 <tt class="literal"><span class="pre">a</span></tt>, and it will therefore consider the object to be owned by the C++ side.
1502 When the <tt class="literal"><span class="pre">b</span></tt> pointer then is adopted, a runtime error will be raised because
1503 an object not owned by lua is being adopted to C++.</p>
1504 <p>If you have a wrapper for your class, none of this will happen, see
1506 </div>
1507 </div>
1510 <p>If any of the functions you register throws an exception when called, that
1511 exception will be caught by luabind and converted to an error string and
1512 <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
1513 <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,
1514 will be the string returned by <tt class="literal"><span class="pre">std::exception::what()</span></tt> or the string itself
1515 respectively. If the exception is unknown, a generic string saying that the
1516 function threw an exception will be pushed.</p>
1517 <p>Exceptions thrown from user defined functions have to be caught by luabind. If
1518 they weren't they would be thrown through Lua itself, which is usually compiled
1519 as C code and doesn't support the stack-unwinding that exceptions imply.</p>
1520 <p>Any function that invokes Lua code may throw <tt class="literal"><span class="pre">luabind::error</span></tt>. This exception
1521 means that a Lua run-time error occurred. The error message is found on top of
1522 the Lua stack. The reason why the exception doesn't contain the error string
1523 itself is because it would then require heap allocation which may fail. If an
1524 exception class throws an exception while it is being thrown itself, the
1525 application will be terminated.</p>
1528 class error : public std::exception
1529 {
1530 public:
1531 error(lua_State*);
1532 lua_State* state() const throw();
1533 virtual const char* what() const throw();
1534 };
1535 </pre>
1536 <p>The state function returns a pointer to the Lua state in which the error was
1537 thrown. This pointer may be invalid if you catch this exception after the lua
1538 state is destructed. If the Lua state is valid you can use it to retrieve the
1539 error message from the top of the Lua stack.</p>
1540 <p>An example of where the Lua state pointer may point to an invalid state
1541 follows:</p>
1543 struct lua_state
1544 {
1545 lua_state(lua_State* L): m_L(L) {}
1546 ~lua_state() { lua_close(m_L); }
1547 operator lua_State*() { return m_L; }
1548 lua_State* m_L;
1549 };
1551 int main()
1552 {
1553 try
1554 {
1555 lua_state L = lua_open();
1556 /* ... */
1557 }
1558 catch(luabind::error& e)
1559 {
1560 lua_State* L = e.state();
1561 // L will now point to the destructed
1562 // Lua state and be invalid
1563 /* ... */
1564 }
1565 }
1566 </pre>
1567 <p>There's another exception that luabind may throw: <tt class="literal"><span class="pre">luabind::cast_failed</span></tt>,
1568 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
1569 <tt class="literal"><span class="pre">functor<></span></tt> is invoked. It means that the return value from the Lua function
1570 couldn't be converted to a C++ value. It is also thrown from <tt class="literal"><span class="pre">object_cast<></span></tt>
1571 if the cast cannot be made.</p>
1572 <p>The synopsis for <tt class="literal"><span class="pre">luabind::cast_failed</span></tt> is:</p>
1574 class cast_failed : public std::exception
1575 {
1576 public:
1577 cast_failed(lua_State*);
1578 lua_State* state() const throw();
1579 LUABIND_TYPE_INFO info() const throw();
1580 virtual const char* what() const throw();
1581 };
1582 </pre>
1583 <p>Again, the state member function returns a pointer to the Lua state where the
1584 error occurred. See the example above to see where this pointer may be invalid.</p>
1585 <p>The info member function returns the user defined <tt class="literal"><span class="pre">LUABIND_TYPE_INFO</span></tt>, which
1586 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
1587 we tried to cast a Lua value to.</p>
1588 <p>If you have defined <tt class="literal"><span class="pre">LUABIND_NO_EXCEPTIONS</span></tt> none of these exceptions will be
1589 thrown, instead you can set two callback functions that are called instead.
1590 These two functions are only defined if <tt class="literal"><span class="pre">LUABIND_NO_EXCEPTIONS</span></tt> are defined.</p>
1592 luabind::set_error_callback(void(*)(lua_State*))
1593 </pre>
1594 <p>The function you set will be called when a runtime-error occur in Lua code. You
1595 can find an error message on top of the Lua stack. This function is not
1596 expected to return, if it does luabind will call <tt class="literal"><span class="pre">std::terminate()</span></tt>.</p>
1598 luabind::set_cast_failed_callback(void(*)(lua_State*, LUABIND_TYPE_INFO))
1599 </pre>
1600 <p>The function you set is called instead of throwing <tt class="literal"><span class="pre">cast_failed</span></tt>. This function
1601 is not expected to return, if it does luabind will call <tt class="literal"><span class="pre">std::terminate()</span></tt>.</p>
1602 </div>
1605 <p>Sometimes it is necessary to control how luabind passes arguments and return
1606 value, to do this we have policies. All policies use an index to associate
1607 them with an argument in the function signature. These indices are <tt class="literal"><span class="pre">result</span></tt>
1608 and <tt class="literal"><span class="pre">_N</span></tt> (where <tt class="literal"><span class="pre">N</span> <span class="pre">>=</span> <span class="pre">1</span></tt>). When dealing with member functions <tt class="literal"><span class="pre">_1</span></tt> refers
1611 <p class="topic-title"><a name="policies-currently-implemented">Policies currently implemented</a></p>
1616 <li><a class="reference" href="#pure-out-value" id="id95" name="id95">12.4 pure_out_value</a></li>
1617 <li><a class="reference" href="#return-reference-to" id="id96" name="id96">12.5 return_reference_to</a></li>
1619 <li><a class="reference" href="#discard-result" id="id98" name="id98">12.7 discard_result</a></li>
1620 <li><a class="reference" href="#return-stl-iterator" id="id99" name="id99">12.8 return_stl_iterator</a></li>
1623 </ul>
1624 </div>
1630 </div>
1635 </pre>
1636 </div>
1640 adopt(index)
1641 </pre>
1642 </div>
1646 <colgroup>
1649 </colgroup>
1653 </tr>
1654 </thead>
1657 <td>The index which should transfer ownership, <tt class="literal"><span class="pre">_N</span></tt> or <tt class="literal"><span class="pre">result</span></tt></td>
1658 </tr>
1659 </tbody>
1660 </table>
1661 </div>
1665 X* create()
1666 {
1667 return new X;
1668 }
1670 ...
1672 module(L)
1673 [
1675 ];
1676 </pre>
1677 </div>
1678 </div>
1683 <p>The dependency policy is used to create life-time dependencies between values.
1684 This is needed for example when returning internal references to some class.</p>
1685 </div>
1690 </pre>
1691 </div>
1695 dependency(nurse_index, patient_index)
1696 </pre>
1697 </div>
1701 <colgroup>
1704 </colgroup>
1708 </tr>
1709 </thead>
1713 </tr>
1716 </tr>
1717 </tbody>
1718 </table>
1719 </div>
1723 struct X
1724 {
1725 B member;
1726 B& get() { return member; }
1727 };
1729 module(L)
1730 [
1733 ];
1734 </pre>
1735 </div>
1736 </div>
1741 <p>This policy makes it possible to wrap functions that take non-const references
1742 or pointer to non-const as it's parameters with the intention to write return
1743 values to them.</p>
1744 </div>
1749 </pre>
1750 </div>
1754 out_value(index, policies = none)
1755 </pre>
1756 </div>
1760 <colgroup>
1763 </colgroup>
1767 </tr>
1768 </thead>
1772 </tr>
1774 <td>The policies used internally to convert the out parameter
1775 to/from Lua. <tt class="literal"><span class="pre">_1</span></tt> means <strong>to</strong> C++, <tt class="literal"><span class="pre">_2</span></tt> means <strong>from</strong>
1776 C++.</td>
1777 </tr>
1778 </tbody>
1779 </table>
1780 </div>
1785 void f2(float* val) { *val = *val + 10.f; }
1787 module(L)
1788 [
1790 ];
1794 20
1796 20
1797 </pre>
1798 </div>
1799 </div>
1804 <p>This works exactly like <tt class="literal"><span class="pre">out_value</span></tt>, except that it will pass a
1805 default constructed object instead of converting an argument from
1806 Lua.</p>
1807 </div>
1812 </pre>
1813 </div>
1817 pure_out_value(index, policies = none)
1818 </pre>
1819 </div>
1823 <colgroup>
1826 </colgroup>
1830 </tr>
1831 </thead>
1835 </tr>
1837 <td>The policies used internally to convert the out parameter
1838 to Lua. <tt class="literal"><span class="pre">_1</span></tt> is used as the interal index.</td>
1839 </tr>
1840 </tbody>
1841 </table>
1842 </div>
1847 void f2(float* val) { *val = 10.f; }
1849 module(L)
1850 [
1852 ];
1855 > print(f1())
1856 10
1857 > print(f2())
1858 10
1859 </pre>
1860 </div>
1861 </div>
1866 <p>It is very common to return references to arguments or the this-pointer to
1867 allow for chaining in C++.</p>
1869 struct A
1870 {
1871 float val;
1873 A& set(float v)
1874 {
1875 val = v;
1876 return *this;
1877 }
1878 };
1879 </pre>
1880 <p>When luabind generates code for this, it will create a new object for the
1881 return-value, pointing to the self-object. This isn't a problem, but could be a
1882 bit inefficient. When using the return_reference_to-policy we have the ability
1883 to tell luabind that the return-value is already on the lua stack.</p>
1884 </div>
1889 </pre>
1890 </div>
1894 return_reference_to(index)
1895 </pre>
1896 </div>
1900 <colgroup>
1903 </colgroup>
1907 </tr>
1908 </thead>
1911 <td>The argument index to return a reference to, any argument but
1913 </tr>
1914 </tbody>
1915 </table>
1916 </div>
1920 struct A
1921 {
1922 float val;
1924 A& set(float v)
1925 {
1926 val = v;
1927 return *this;
1928 }
1929 };
1931 module(L)
1932 [
1934 .def(constructor<>())
1936 ];
1937 </pre>
1940 This policy ignores all type information and should be used only it
1941 situations where the parameter type is a perfect match to the
1942 return-type (such as in the example).</div>
1943 </div>
1944 </div>
1949 <p>This will make a copy of the parameter. This is the default behavior when
1950 passing parameters by-value. Note that this can only be used when passing from
1951 C++ to Lua. This policy requires that the parameter type has an accessible copy
1952 constructor.</p>
1953 </div>
1958 </pre>
1959 </div>
1963 copy(index)
1964 </pre>
1965 </div>
1969 <colgroup>
1972 </colgroup>
1976 </tr>
1977 </thead>
1980 <td>The index to copy. <tt class="literal"><span class="pre">result</span></tt> when used while wrapping C++
1981 functions. <tt class="literal"><span class="pre">_N</span></tt> when passing arguments to Lua.</td>
1982 </tr>
1983 </tbody>
1984 </table>
1985 </div>
1989 X* get()
1990 {
1991 static X instance;
1992 return &instance;
1993 }
1995 ...
1997 module(L)
1998 [
2000 ];
2001 </pre>
2002 </div>
2003 </div>
2008 <p>This is a very simple policy which makes it possible to throw away
2009 the value returned by a C++ function, instead of converting it to
2010 Lua.</p>
2011 </div>
2016 </pre>
2017 </div>
2021 discard_result
2022 </pre>
2023 </div>
2027 struct X
2028 {
2029 X& set(T n)
2030 {
2031 ...
2032 return *this;
2033 }
2034 };
2036 ...
2038 module(L)
2039 [
2042 ];
2043 </pre>
2044 </div>
2045 </div>
2050 <p>This policy converts an STL container to a generator function that can be used
2051 in lua to iterate over the container. It works on any container that defines
2052 <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).</p>
2053 </div>
2058 </pre>
2059 </div>
2063 return_stl_iterator
2064 </pre>
2065 </div>
2069 struct X
2070 {
2072 };
2074 ...
2076 module(L)
2077 [
2080 ];
2082 ...
2084 > a = A()
2085 > for name in a.names do
2086 > print(name)
2087 > end
2088 </pre>
2089 </div>
2090 </div>
2095 <p>This converter policy will pass through the <tt class="literal"><span class="pre">lua_State*</span></tt> unmodified.
2096 This can be useful for example when binding functions that need to
2097 return a <tt class="literal"><span class="pre">luabind::object</span></tt>. The parameter will be removed from the
2098 function signature, decreasing the function arity by one.</p>
2099 </div>
2104 </pre>
2105 </div>
2109 raw(index)
2110 </pre>
2111 </div>
2115 <colgroup>
2118 </colgroup>
2122 </tr>
2123 </thead>
2127 </tr>
2128 </tbody>
2129 </table>
2130 </div>
2134 void greet(lua_State* L)
2135 {
2137 }
2139 ...
2141 module(L)
2142 [
2144 ];
2146 > print(greet())
2147 hello
2148 </pre>
2149 </div>
2150 </div>
2156 </div>
2161 </pre>
2162 </div>
2166 yield
2167 </pre>
2168 </div>
2172 void do_thing_that_takes_time()
2173 {
2174 ...
2175 }
2177 ...
2179 module(L)
2180 [
2181 def("do_thing_that_takes_time", &do_thing_that_takes_time, <strong>yield</strong>)
2182 ];
2183 </pre>
2184 <!-- old policies section
2185 ===================================================
2187 Copy
2188 - - - -
2190 This will make a copy of the parameter. This is the default behavior when
2191 passing parameters by-value. Note that this can only be used when passing from
2192 C++ to Lua. This policy requires that the parameter type has a copy
2193 constructor.
2195 To use this policy you need to include ``luabind/copy_policy.hpp``.
2198 Adopt
2199 - - - - -
2201 This will transfer ownership of the parameter.
2203 Consider making a factory function in C++ and exposing it to lua::
2205 base* create_base()
2206 {
2207 return new base();
2208 }
2210 ...
2212 module(L)
2213 [
2214 def("create_base", create_base)
2215 ];
2217 Here we need to make sure Lua understands that it should adopt the pointer
2218 returned by the factory-function. This can be done using the adopt-policy.
2220 ::
2222 module(L)
2223 [
2224 def(L, "create_base", adopt(return_value))
2225 ];
2227 To specify multiple policies we just separate them with '+'.
2229 ::
2231 base* set_and_get_new(base* ptr)
2232 {
2233 base_ptrs.push_back(ptr);
2234 return new base();
2235 }
2237 module(L)
2238 [
2239 def("set_and_get_new", &set_and_get_new,
2240 adopt(return_value) + adopt(_1))
2241 ];
2243 When Lua adopts a pointer, it will call delete on it. This means that it cannot
2244 adopt pointers allocated with another allocator than new (no malloc for
2245 example).
2247 To use this policy you need to include ``luabind/adopt_policy.hpp``.
2250 Dependency
2251 - - - - - - - - - -
2253 The dependency policy is used to create life-time dependencies between values.
2254 Consider the following example::
2256 struct A
2257 {
2258 B member;
2260 const B& get_member()
2261 {
2262 return member;
2263 }
2264 };
2266 When wrapping this class, we would do something like::
2268 module(L)
2269 [
2270 class_<A>("A")
2271 .def(constructor<>())
2272 .def("get_member", &A::get_member)
2273 ];
2276 However, since the return value of get_member is a reference to a member of A,
2277 this will create some life-time issues. For example::
2279 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2280 a = A()
2281 b = a:get_member() - - b points to a member of a
2282 a = nil
2283 collectgarbage(0) - - since there are no references left to a, it is
2284 - - removed
2285 - - at this point, b is pointing into a removed object
2287 When using the dependency-policy, it is possible to tell luabind to tie the
2288 lifetime of one object to another, like this::
2290 module(L)
2291 [
2292 class_<A>("A")
2293 .def(constructor<>())
2294 .def("get_member", &A::get_member, dependency(result, _1))
2295 ];
2297 This will create a dependency between the return-value of the function, and the
2298 self-object. This means that the self-object will be kept alive as long as the
2299 result is still alive. ::
2301 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2302 a = A()
2303 b = a:get_member() - - b points to a member of a
2304 a = nil
2305 collectgarbage(0) - - a is dependent on b, so it isn't removed
2306 b = nil
2307 collectgarbage(0) - - all dependencies to a gone, a is removed
2309 To use this policy you need to include ``luabind/dependency_policy.hpp``.
2312 Return reference to
2313 - - - - - - - - - - - - - - - - - - -
2315 It is very common to return references to arguments or the this-pointer to
2316 allow for chaining in C++.
2318 ::
2320 struct A
2321 {
2322 float val;
2324 A& set(float v)
2325 {
2326 val = v;
2327 return *this;
2328 }
2329 };
2331 When luabind generates code for this, it will create a new object for the
2332 return-value, pointing to the self-object. This isn't a problem, but could be a
2333 bit inefficient. When using the return_reference_to-policy we have the ability
2334 to tell luabind that the return-value is already on the Lua stack.
2336 ::
2338 module(L)
2339 [
2340 class_<A>("A")
2341 .def(constructor<>())
2342 .def("set", &A::set, return_reference_to(_1))
2343 ];
2345 Instead of creating a new object, luabind will just copy the object that is
2346 already on the stack.
2348 .. warning::
2349 This policy ignores all type information and should be used only it
2350 situations where the parameter type is a perfect match to the
2351 return-type (such as in the example).
2353 To use this policy you need to include ``luabind/return_reference_to_policy.hpp``.
2356 Out value
2357 - - - - - - - - -
2359 This policy makes it possible to wrap functions that take non const references
2360 as its parameters with the intention to write return values to them.
2362 ::
2364 void f(float& val) { val = val + 10.f; }
2366 or
2368 ::
2370 void f(float* val) { *val = *val + 10.f; }
2372 Can be wrapped by doing::
2374 module(L)
2375 [
2376 def("f", &f, out_value(_1))
2377 ];
2379 When invoking this function from Lua it will return the value assigned to its
2380 parameter.
2382 ::
2384 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2385 > a = f(10)
2386 > print(a)
2387 20
2389 When this policy is used in conjunction with user define types we often need
2390 to do ownership transfers.
2392 ::
2394 struct A;
2396 void f1(A*& obj) { obj = new A(); }
2397 void f2(A** obj) { *obj = new A(); }
2399 Here we need to make sure luabind takes control over object returned, for
2400 this we use the adopt policy::
2402 module(L)
2403 [
2404 class_<A>("A"),
2405 def("f1", &f1, out_value(_1, adopt(_2)))
2406 def("f2", &f2, out_value(_1, adopt(_2)))
2407 ];
2409 Here we are using adopt as an internal policy to out_value. The index
2410 specified, _2, means adopt will be used to convert the value back to Lua.
2411 Using _1 means the policy will be used when converting from Lua to C++.
2413 To use this policy you need to include ``luabind/out_value_policy.hpp``.
2415 Pure out value
2416 - - - - - - - - - - - - - -
2418 This policy works in exactly the same way as out_value, except that it
2419 replaces the parameters with default-constructed objects.
2421 ::
2423 void get(float& x, float& y)
2424 {
2425 x = 3.f;
2426 y = 4.f;
2427 }
2429 ...
2431 module(L)
2432 [
2433 def("get", &get,
2434 pure_out_value(_1) + pure_out_value(_2))
2435 ];
2437 ::
2439 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2440 > x, y = get()
2441 > print(x, y)
2442 3 5
2444 Like out_value, it is possible to specify an internal policy used then
2445 converting the values back to Lua.
2447 ::
2449 void get(test_class*& obj)
2450 {
2451 obj = new test_class();
2452 }
2454 ...
2456 module(L)
2457 [
2458 def("get", &get, pure_out_value(_1, adopt(_1)))
2459 ];
2462 Discard result
2463 - - - - - - - - - - - - - -
2465 This is a very simple policy which makes it possible to throw away
2466 the value returned by a C++ function, instead of converting it to
2467 Lua. This example makes sure the this reference never gets converted
2468 to Lua.
2470 ::
2472 struct simple
2473 {
2474 simple& set_name(const std::string& n)
2475 {
2476 name = n;
2477 return *this;
2478 }
2480 std::string name;
2481 };
2483 ...
2485 module(L)
2486 [
2487 class_<simple>("simple")
2488 .def("set_name", &simple::set_name, discard_result)
2489 ];
2491 To use this policy you need to include ``luabind/discard_result_policy.hpp``.
2494 Return STL iterator
2495 - - - - - - - - - - - - - - - - - - -
2497 This policy converts an STL container to a generator function that can be used
2498 in Lua to iterate over the container. It works on any container that defines
2499 ``begin()`` and ``end()`` member functions (they have to return iterators). It
2500 can be used like this::
2502 struct A
2503 {
2504 std::vector<std::string> names;
2505 };
2508 module(L)
2509 [
2510 class_<A>("A")
2511 .def_readwrite("names", &A::names, return_stl_iterator)
2512 ];
2514 The Lua code to iterate over the container::
2516 a = A()
2518 for name in a.names do
2519 print(name)
2520 end
2523 To use this policy you need to include ``luabind/iterator_policy.hpp``.
2526 Yield
2527 - - - - -
2529 This policy will cause the function to always yield the current thread when
2530 returning. See the Lua manual for restrictions on yield. -->
2531 </div>
2532 </div>
2533 </div>
2536 <p>It is possible to split up a module registration into several
2537 translation units without making each registration dependent
2538 on the module it's being registered in.</p>
2541 luabind::scope register_a()
2542 {
2543 return
2546 ;
2547 }
2548 </pre>
2551 luabind::scope register_b()
2552 {
2553 return
2556 ;
2557 }
2558 </pre>
2561 luabind::scope register_a();
2562 luabind::scope register_b();
2564 void register_module(lua_State* L)
2565 {
2567 [
2568 register_a(),
2569 register_b()
2570 ];
2571 }
2572 </pre>
2573 </div>
2576 <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
2577 error handler function to <tt class="literal"><span class="pre">lua_pcall()</span></tt>. Luabind makes use of
2578 <tt class="literal"><span class="pre">lua_pcall()</span></tt> internally when calling methods and functions. It is
2579 possible to set the error handler function that Luabind will use
2580 globally:</p>
2582 typedef void(*pcall_callback_fun)(lua_State*);
2583 void set_pcall_callback(pcall_callback_fun fn);
2584 </pre>
2585 <p>This is primarily useful for adding more information to the error message
2586 returned by a failed protected call.</p>
2589 <p>There are a number of configuration options available when building luabind.
2590 It is very important that your project has the exact same conmfiguration
2591 options as the ones given when the library was build! The exceptions are the
2592 <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
2593 options and only matters when you use the library (which means they can
2594 differ from the settings of the library).</p>
2595 <p>The default settings which will be used if no other settings are given
2597 <p>If you want to change the settings of the library, you can modify the
2598 config file. It is included and used by all makefiles. You can change paths
2599 to Lua and boost in there as well.</p>
2600 <dl>
2602 <dd>Controls the maximum arity of functions that are registered with luabind.
2603 You can't register functions that takes more parameters than the number
2604 this macro is set to. It defaults to 5, so, if your functions have greater
2605 arity you have to redefine it. A high limit will increase compilation time.</dd>
2607 <dd>Controls the maximum number of classes one class can derive from in
2608 luabind (the number of classes specified within <tt class="literal"><span class="pre">bases<></span></tt>).
2609 <tt class="literal"><span class="pre">LUABIND_MAX_BASES</span></tt> defaults to 4. A high limit will increase
2610 compilation time.</dd>
2613 calls. If illegal function calls are made (e.g. giving parameters that
2614 doesn't match the function signature) they will not be detected by luabind
2615 and the application will probably crash. Error checking could be disabled
2616 when shipping a release build (given that no end-user has access to write
2617 custom Lua code). Note that function parameter matching will be done if a
2618 function is overloaded, since otherwise it's impossible to know which one
2619 was called. Functions will still be able to throw exceptions when error
2620 checking is disabled.</p>
2623 </dd>
2626 This will in many cases disable run-time errors, when performing invalid
2627 casts or calling Lua functions that fails or returns values that cannot
2628 be converted by the given policy. luabind requires that no function called
2629 directly or indirectly by luabind throws an exception (throwing exceptions
2630 through Lua has undefined behavior).</p>
2632 they will be replaced with calls to the callback functions set with
2633 <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>
2634 </dd>
2636 <dd>If you want to link dynamically against Lua, you can set this define to
2637 the import-keyword on your compiler and platform. On windows in devstudio
2638 this should be <tt class="literal"><span class="pre">__declspec(dllimport)</span></tt> if you want to link against Lua
2639 as a dll.</dd>
2641 <dd>If you want to link against luabind as a dll (in devstudio), you can
2642 define <tt class="literal"><span class="pre">LUABIND_EXPORT</span></tt> to <tt class="literal"><span class="pre">__declspec(dllexport)</span></tt> and
2643 <tt class="literal"><span class="pre">LUABIND_IMPORT</span></tt> to <tt class="literal"><span class="pre">__declspec(dllimport)</span></tt>.
2644 Note that you have to link against Lua as a dll aswell, to make it work.</dd>
2646 <dd>You can define this if you don't want luabind to use <tt class="literal"><span class="pre">dynamic_cast<></span></tt>.
2648 <dt>LUABIND_TYPE_INFO, LUABIND_TYPE_INFO_EQUAL(i1,i2), LUABIND_TYPEID(t), LUABIND_INVALID_TYPE_INFO</dt>
2650 type-info structure with the <tt class="literal"><span class="pre">LUABIND_TYPE_INFO</span></tt> define. Your type-info
2651 structure must be copyable and must be able to compare itself against
2652 other type-info structures. You supply the compare function through the
2653 <tt class="literal"><span class="pre">LUABIND_TYPE_INFO_EQUAL()</span></tt> define. It should compare the two type-info
2654 structures it is given and return true if they represent the same type and
2655 false otherwise. You also have to supply a function to generate your
2656 type-info structure. You do this through the <tt class="literal"><span class="pre">LUABIND_TYPEID()</span></tt> define.
2657 It should return your type-info structure and it takes a type as its
2658 parameter. That is, a compile time parameter.
2659 <tt class="literal"><span class="pre">LUABIND_INVALID_TYPE_INFO</span></tt> macro should be defined to an invalid type.
2660 No other type should be able to produce this type info. To use it you
2661 probably have to make a traits class with specializations for all classes
2662 that you have type-info for. Like this:</p>
2664 class A;
2665 class B;
2666 class C;
2673 </pre>
2674 <p>If you have set up your own RTTI system like this (by using integers to
2675 identify types) you can have luabind use it with the following defines:</p>
2677 #define LUABIND_TYPE_INFO const std::type_info*
2678 #define LUABIND_TYPEID(t) &typeid(t)
2679 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
2680 #define LUABIND_INVALID_TYPE_INFO &typeid(detail::null_type)
2681 </pre>
2682 <p class="last">Currently the type given through <tt class="literal"><span class="pre">LUABIND_TYPE_INFO</span></tt> must be less-than
2683 comparable!</p>
2684 </dd>
2686 <dd>This define will disable all asserts and should be defined in a release
2687 build.</dd>
2688 </dl>
2689 </div>
2690 </div>
2693 <p>The classes and objects are implemented as user data in Lua. To make sure that
2694 the user data really is the internal structure it is supposed to be, we tag
2695 their metatables. A user data who's metatable contains a boolean member named
2696 <tt class="literal"><span class="pre">__luabind_classrep</span></tt> is expected to be a class exported by luabind. A user
2697 data who's metatable contains a boolean member named <tt class="literal"><span class="pre">__luabind_class</span></tt> is
2698 expected to be an instantiation of a luabind class.</p>
2699 <p>This means that if you make your own user data and tags its metatable with the
2700 exact same names, you can very easily fool luabind and crash the application.</p>
2701 <p>In the Lua registry, luabind keeps an entry called <tt class="literal"><span class="pre">__luabind_classes</span></tt>. It
2702 should not be removed or overwritten.</p>
2703 <p>In the global table, a variable called <tt class="literal"><span class="pre">super</span></tt> is used every time a
2704 constructor in a lua-class is called. This is to make it easy for that
2705 constructor to call its base class' constructor. So, if you have a global
2706 variable named super it may be overwritten. This is probably not the best
2707 solution, and this restriction may be removed in the future.</p>
2708 <p>Luabind uses two upvalues for functions that it registers. The first is a
2709 userdata containing a list of overloads for the function, the other is a light
2710 userdata with the value 0x1337, this last value is used to identify functions
2711 registered by luabind. It should be virtually impossible to have such a pointer
2712 as secondary upvalue by pure chance. This means, if you are trying to replace
2713 an existing function with a luabind function, luabind will see that the
2714 secondary upvalue isn't the magic id number and replace it. If it can identify
2715 the function to be a luabind function, it won't replace it, but rather add
2716 another overload to it.</p>
2717 <p>Inside the luabind namespace, there's another namespace called detail. This
2718 namespace contains non-public classes and are not supposed to be used directly.</p>
2719 </div>
2722 <ul>
2725 </pre>
2727 or there's no setter-method registered on that property name. See the
2728 properties section.</p>
2729 </li>
2731 the attribute '<em>class-name.attribute-name</em>' is of type: (<em>class-name</em>) and does not match (<em>class_name</em>)
2732 </pre>
2733 <p>This error is generated if you try to assign an attribute with a value
2734 of a type that cannot be converted to the attribute's type.</p>
2735 </li>
2737 <em>class-name()</em> threw an exception, <em>class-name:function-name()</em> threw an exception
2738 </pre>
2739 <p>The class' constructor or member function threw an unknown exception.
2740 Known exceptions are const char*, std::exception. See the
2742 </li>
2744 no overload of '<em>class-name:function-name</em>' matched the arguments (<em>parameter-types</em>)
2745 no match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>)
2748 </pre>
2749 <p>No function/operator with the given name takes the parameters you gave
2750 it. You have either misspelled the function name, or given it incorrect
2751 parameters. This error is followed by a list of possible candidate
2752 functions to help you figure out what parameter has the wrong type. If
2753 the candidate list is empty there's no function at all with that name.
2754 See the signature matching section.</p>
2755 </li>
2758 ambiguous match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>)
2761 </pre>
2762 <p>This means that the function/operator you are trying to call has at least
2763 one other overload that matches the arguments just as good as the first
2764 overload.</p>
2765 </li>
2768 </pre>
2769 </li>
2770 </ul>
2771 </div>
2774 <dl>
2776 <dd>If you're having problem with functions
2777 that cannot be converted from <tt class="literal"><span class="pre">void</span> <span class="pre">(__stdcall</span> <span class="pre">*)(int,int)</span></tt> to
2778 <tt class="literal"><span class="pre">void</span> <span class="pre">(__cdecl*)(int,int)</span></tt>. You can change the project settings to make the
2779 compiler generate functions with __cdecl calling conventions. This is
2780 a problem in developer studio.</dd>
2782 <dd>You cannot register a function with ellipses in its signature. Since
2783 ellipses don't preserve type safety, those should be avoided anyway.</dd>
2785 <dd>If you, in visual studio, get fatal error C1204: compiler limit :
2786 internal structure overflow. You should try to split that compilation
2787 unit up in smaller ones.</dd>
2788 </dl>
2789 <!-- the three entries above were removed, why? -->
2790 <dl>
2792 <dd>Visual Studio doesn't like anonymous namespaces in its precompiled
2793 headers. If you encounter this problem you can disable precompiled
2794 headers for the compilation unit (cpp-file) that uses luabind.</dd>
2796 <dd>In visual studio you will probably hit this error. To fix it you have to
2797 increase the internal heap with a command-line option. We managed to
2798 compile the test suit with /Zm300, but you may need a larger heap then
2799 that.</dd>
2801 <dd>It seems that this error occurs when too many assert() are used in a
2802 program, or more specifically, the __LINE__ macro. It seems to be fixed by
2803 changing /ZI (Program database for edit and continue) to /Zi
2804 (Program database).</dd>
2807 debug-info and symbols (luabind consists of a lot of functions). Also,
2808 if built in debug mode, no optimizations were applied, luabind relies on
2809 that the compiler is able to inline functions. If you built in release
2810 mode, try running strip on your executable to remove export-symbols,
2811 this will trim down the size.</p>
2813 compared to gcc on other platforms and other compilers.</p>
2814 </dd>
2815 </dl>
2816 <!-- HUH?! // check the magic number that identifies luabind's functions -->
2817 <dl>
2820 class. Because there's no Lua counterpart to C++ templates. For example,
2823 module(L)
2824 [
2828 ];
2829 </pre>
2830 </dd>
2831 </dl>
2832 <!-- Again, irrelevant to docs: Note that the space between the two > is required by C++. -->
2833 <dl>
2836 object is collected. Note that Lua has to own the object to collect it.
2837 If you pass it to C++ and gives up ownership (with adopt policy) it will
2838 no longer be owned by Lua, and not collected.</p>
2840 you want to be sure that the correct destructor is called (this apply to C++
2841 in general).</p>
2842 </dd>
2843 </dl>
2844 <!-- And again, the above is irrelevant to docs. This isn't a general C++ FAQ. -->
2845 <dl>
2847 <dd>VC6.5 chokes on warnings, if you are getting alot of warnings from your
2848 code try suppressing them with a pragma directive, this should solve the
2849 problem.</dd>
2851 <dd>When you build luabind, Lua and you project, make sure you link against
2852 the runtime dynamically (as a dll).</dd>
2854 <dd>This is because there is no way to get a reference to a Lua value. Have
2855 a look at out_value and pure_out_value policies.</dd>
2856 </dl>
2857 </div>
2861 <li>You cannot use strings with extra nulls in them as member names that refers
2862 to C++ members.</li>
2863 <li>If one class registers two functions with the same name and the same
2864 signature, there's currently no error. The last registered function will
2865 be the one that's used.</li>
2867 <li>If you register a function and later rename it, error messages will use the
2868 original function name.</li>
2869 <li>luabind does not support class hierarchies with virtual inheritance. Casts are
2870 done with static pointer offsets.</li>
2871 </ul>
2872 <!-- remove? - Visual studio have problems selecting the correct overload of std::swap()
2873 for luabind::object. -->
2874 </div>
2878 All rights reserved.</p>
2879 <p>Evan Wies has contributed with thorough testing, countless bug reports
2880 and feature ideas.</p>
2881 <p>This library was highly inspired by Dave Abrahams' <a class="reference" href="http://www.boost.org/libraries/python">Boost.Python</a> library.</p>
2882 </div>
2883 </div>
2888 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.
2889 </div>
2890 </body>
2891 </html>