5 :Author: Daniel Wallin, Arvid Norberg
6 :Copyright: Copyright Daniel Wallin, Arvid Norberg 2003.
9 :License: Permission is hereby granted, free of charge, to any person obtaining a
10 copy of this software and associated documentation files (the "Software"),
11 to deal in the Software without restriction, including without limitation
12 the rights to use, copy, modify, merge, publish, distribute, sublicense,
13 and/or sell copies of the Software, and to permit persons to whom the
14 Software is furnished to do so, subject to the following conditions:
16 The above copyright notice and this permission notice shall be included
17 in all copies or substantial portions of the Software.
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
20 ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
21 TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
22 PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
23 SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
24 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
25 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
27 OR OTHER DEALINGS IN THE SOFTWARE.
30 .. _MIT license: http://www.opensource.org/licenses/mit-license.php
31 .. _Boost: http://www.boost.org
33 Note: This library is currently in public beta phase. This documentation
34 should be considered beta as well. Please report any grammatical
35 corrections/spelling corrections.
40 .. section-numbering::
45 Luabind is a library that helps you create bindings between C++ and Lua. It has
46 the ability to expose functions and classes, written in C++, to Lua. It will
47 also supply the functionality to define classes in Lua and let them derive from
48 other Lua classes or C++ classes. Lua classes can override virtual functions
49 from their C++ base classes. It is written towards Lua 5.0, and does not work
52 It is implemented utilizing template meta programming. That means that you
53 don't need an extra preprocess pass to compile your project (it is done by the
54 compiler). It also means you don't (usually) have to know the exact signature
55 of each function you register, since the library will generate code depending
56 on the compile-time type of the function (which includes the signature). The
57 main drawback of this approach is that the compilation time will increase for
58 the file that does the registration, it is therefore recommended that you
59 register everything in the same cpp-file.
61 Luabind is released under the terms of the `MIT license`_.
63 We are very interested in hearing about projects that use luabind, please let
64 us know about your project.
66 The main channel for help and feedback is the `luabind mailing list`_.
67 There's also an IRC channel ``#luabind`` on irc.freenode.net.
69 .. _`luabind mailing list`: https://lists.sourceforge.net/lists/listinfo/luabind-user
77 - Overloaded free functions
79 - Overloaded member functions
83 - Lua functions in C++
85 - Lua classes (single inheritance)
86 - Derives from Lua or C++ classes
87 - Override virtual functions from C++ classes
88 - Implicit casts between registered types
89 - Best match signature matching
90 - Return value policies and parameter policies
96 Luabind has been tested to work on the following compilers:
100 - Visual Studio 6.0 (sp 5)
101 - Intel C++ 6.0 (Windows)
102 - GCC 2.95.3 (cygwin)
103 - GCC 3.0.4 (Debian/Linux)
104 - GCC 3.1 (SunOS 5.8)
107 - GCC 3.3 (Apple, MacOS X)
108 - GCC 4.0 (Apple, MacOS X)
110 It has been confirmed not to work with:
112 - GCC 2.95.2 (SunOS 5.8)
114 Metrowerks 8.3 (Windows) compiles but fails the const-test. This
115 means that const member functions are treated as non-const member
118 If you have tried luabind with a compiler not listed here, let us know
121 .. include:: building.rst
126 To use luabind, you must include ``lua.h`` and luabind's main header file::
133 #include <luabind/luabind.hpp>
135 This includes support for both registering classes and functions. If you just
136 want to have support for functions or classes you can include
137 ``luabind/function.hpp`` and ``luabind/class.hpp`` separately::
139 #include <luabind/function.hpp>
140 #include <luabind/class.hpp>
142 The first thing you need to do is to call ``luabind::open(lua_State*)`` which
143 will register the functions to create classes from Lua, and initialize some
144 state-global structures used by luabind. If you don't call this function you
145 will hit asserts later in the library. There is no corresponding close function
146 because once a class has been registered in Lua, there really isn't any good
147 way to remove it. Partly because any remaining instances of that class relies
148 on the class being there. Everything will be cleaned up when the state is
151 .. Isn't this wrong? Don't we include lua.h using lua_include.hpp ?
153 Luabind's headers will never include ``lua.h`` directly, but through
154 ``<luabind/lua_include.hpp>``. If you for some reason need to include another
155 Lua header, you can modify this file.
164 #include <luabind/luabind.hpp>
168 std::cout << "hello world!\n";
171 extern "C" int init(lua_State* L)
173 using namespace luabind;
187 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
188 > loadlib('hello_world.dll', 'init')()
196 Everything that gets registered in Lua is registered in a namespace (Lua
197 tables) or in the global scope (called module). All registrations must be
198 surrounded by its scope. To define a module, the ``luabind::module`` class is
199 used. It is used like this::
206 This will register all declared functions or classes in the global namespace in
207 Lua. If you want to have a namespace for your module (like the standard
208 libraries) you can give a name to the constructor, like this::
210 module(L, "my_library")
215 Here all declarations will be put in the my_library table.
217 If you want nested namespace's you can use the ``luabind::namespace_`` class. It
218 works exactly as ``luabind::module`` except that it doesn't take a lua_State*
219 in it's constructor. An example of its usage could look like this::
221 module(L, "my_library")
227 // library-private declarations
231 As you might have figured out, the following declarations are equivalent::
235 namespace_("my_library")
244 module(L, "my_library")
249 Each declaration must be separated by a comma, like this::
256 .def(constructor<int, int>),
261 More about the actual declarations in the `Binding functions to Lua`_ and
262 `Binding classes to Lua`_ sections.
264 A word of caution, if you are in really bad need for performance, putting your
265 functions in tables will increase the lookup time.
268 Binding functions to Lua
269 ========================
271 To bind functions to Lua you use the function ``luabind::def()``. It has the
274 template<class F, class policies>
275 void def(const char* name, F f, const Policies&);
277 - name is the name the function will have within Lua.
278 - F is the function pointer you want to register.
279 - The Policies parameter is used to describe how parameters and return values
280 are treated by the function, this is an optional parameter. More on this in
281 the `policies`_ section.
283 An example usage could be if you want to register the function ``float
288 def("sin", &std::sin)
294 If you have more than one function with the same name, and want to register
295 them in Lua, you have to explicitly give the signature. This is to let C++ know
296 which function you refer to. For example, if you have two functions, ``int
297 f(const char*)`` and ``void f(int)``. ::
301 def("f", (int(*)(const char*)) &f),
302 def("f", (void(*)(int)) &f)
308 luabind will generate code that checks the Lua stack to see if the values there
309 can match your functions' signatures. It will handle implicit typecasts between
310 derived classes, and it will prefer matches with the least number of implicit
311 casts. In a function call, if the function is overloaded and there's no
312 overload that match the parameters better than the other, you have an
313 ambiguity. This will spawn a run-time error, stating that the function call is
314 ambiguous. A simple example of this is to register one function that takes an
315 int and one that takes a float. Since Lua doesn't distinguish between floats and
316 integers, both will always match.
318 Since all overloads are tested, it will always find the best match (not the
319 first match). This also means that it can handle situations where the only
320 difference in the signature is that one member function is const and the other
323 .. sidebar:: Ownership transfer
325 To correctly handle ownership transfer, create_a() would need an adopt
326 return value policy. More on this in the `Policies`_ section.
328 For example, if the following function and class is registered:
346 And the following Lua code is executed::
349 a1:f() -- the const version is called
352 a2:f() -- the non-const version is called
363 Calling Lua functions
364 ---------------------
366 To call a Lua function, you can either use ``call_function()`` or
372 Ret call_function(lua_State* L, const char* name, ...)
374 Ret call_function(object const& obj, ...)
376 There are two overloads of the ``call_function`` function, one that calls
377 a function given its name, and one that takes an object that should be a Lua
378 value that can be called as a function.
380 The overload that takes a name can only call global Lua functions. The ...
381 represents a variable number of parameters that are sent to the Lua
382 function. This function call may throw ``luabind::error`` if the function
385 The return value isn't actually Ret (the template parameter), but a proxy
386 object that will do the function call. This enables you to give policies to the
387 call. You do this with the operator[]. You give the policies within the
388 brackets, like this::
390 int ret = call_function<int>(
393 , new complex_class()
396 If you want to pass a parameter as a reference, you have to wrap it with the
399 __ http://www.boost.org/doc/html/ref.html
403 int ret = call_function(L, "fun", boost::ref(val));
406 If you want to use a custom error handler for the function call, see
407 ``set_pcall_callback`` under `pcall errorfunc`_.
412 To start a Lua thread, you have to call ``lua_resume()``, this means that you
413 cannot use the previous function ``call_function()`` to start a thread. You have
419 Ret resume_function(lua_State* L, const char* name, ...)
421 Ret resume_function(object const& obj, ...)
428 Ret resume(lua_State* L, ...)
430 The first time you start the thread, you have to give it a function to execute. i.e. you
431 have to use ``resume_function``, when the Lua function yields, it will return the first
432 value passed in to ``lua_yield()``. When you want to continue the execution, you just call
433 ``resume()`` on your ``lua_State``, since it's already executing a function, you don't pass
434 it one. The parameters to ``resume()`` will be returned by ``yield()`` on the Lua side.
436 For yielding C++-functions (without the support of passing data back and forth between the
437 Lua side and the c++ side), you can use the yield_ policy.
439 With the overload of ``resume_function`` that takes an object_, it is important that the
440 object was constructed with the thread as its ``lua_State*``. Like this:
444 lua_State* thread = lua_newthread(L);
445 object fun = get_global(**thread**)["my_thread_fun"];
446 resume_function(fun);
449 Binding classes to Lua
450 ======================
452 To register classes you use a class called ``class_``. Its name is supposed to
453 resemble the C++ keyword, to make it look more intuitive. It has an overloaded
454 member function ``def()`` that is used to register member functions, operators,
455 constructors, enums and properties on the class. It will return its
456 this-pointer, to let you register more members directly.
458 Let's start with a simple example. Consider the following C++ class::
463 testclass(const std::string& s): m_string(s) {}
464 void print_string() { std::cout << m_string << "\n"; }
467 std::string m_string;
470 To register it with a Lua environment, write as follows (assuming you are using
475 class_<testclass>("testclass")
476 .def(constructor<const std::string&>())
477 .def("print_string", &testclass::print_string)
480 This will register the class with the name testclass and constructor that takes
481 a string as argument and one member function with the name ``print_string``.
485 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
486 > a = testclass('a string')
490 It is also possible to register free functions as member functions. The
491 requirement on the function is that it takes a pointer, const pointer,
492 reference or const reference to the class type as the first parameter. The rest
493 of the parameters are the ones that are visible in Lua, while the object
494 pointer is given as the first parameter. If we have the following C++ code::
501 int plus(A* o, int v) { return o->a + v; }
503 You can register ``plus()`` as if it was a member function of A like this::
508 ``plus()`` can now be called as a member function on A with one parameter, int.
509 If the object pointer parameter is const, the function will act as if it was a
510 const member function (it can be called on const objects).
513 Overloaded member functions
514 ---------------------------
516 When binding more than one overloads of a member function, or just binding
517 one overload of an overloaded member function, you have to disambiguate
518 the member function pointer you pass to ``def``. To do this, you can use an
519 ordinary C-style cast, to cast it to the right overload. To do this, you have
520 to know how to express member function types in C++, here's a short tutorial
521 (for more info, refer to your favourite book on C++).
523 The syntax for member function pointer follows:
527 *return-value* (*class-name*::\*)(*arg1-type*, *arg2-type*, *...*)
529 Here's an example illlustrating this::
540 .def("f", (void(A::*)(int))&A::f)
542 This selects the first overload of the function ``f`` to bind. The second
543 overload is not bound.
549 To register a global data member with a class is easily done. Consider the
557 This class is registered like this::
562 .def_readwrite("a", &A::a)
565 This gives read and write access to the member variable ``A::a``. It is also
566 possible to register attributes with read-only access::
571 .def_readonly("a", &A::a)
574 When binding members that are a non-primitive type, the auto generated getter
575 function will return a reference to it. This is to allow chained .-operators.
576 For example, when having a struct containing another struct. Like this::
581 When binding ``B`` to lua, the following expression code should work::
587 This requires the first lookup (on ``a``) to return a reference to ``A``, and
588 not a copy. In that case, luabind will automatically use the dependency policy
589 to make the return value dependent on the object in which it is stored. So, if
590 the returned reference lives longer than all references to the object (b in
591 this case) it will keep the object alive, to avoid being a dangling pointer.
593 You can also register getter and setter functions and make them look as if they
594 were a public data member. Consider the following class::
599 void set_a(int x) { a = x; }
600 int get_a() const { return a; }
606 It can be registered as if it had a public data member a like this::
609 .property("a", &A::get_a, &A::set_a)
611 This way the ``get_a()`` and ``set_a()`` functions will be called instead of
612 just writing to the data member. If you want to make it read only you can just
613 omit the last parameter. Please note that the get function **has to be
614 const**, otherwise it won't compile. This seems to be a common source of errors.
620 If your class contains enumerated constants (enums), you can register them as
621 well to make them available in Lua. Note that they will not be type safe, all
622 enums are integers in Lua, and all functions that takes an enum, will accept
623 any integer. You register them like this::
631 value("my_2nd_enum", 7),
632 value("another_enum", 6)
636 In Lua they are accessed like any data member, except that they are read-only
637 and reached on the class itself rather than on an instance of the class.
641 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
644 > print(A.another_enum)
651 To bind operators you have to include ``<luabind/operator.hpp>``.
653 The mechanism for registering operators on your class is pretty simple. You use
654 a global name ``luabind::self`` to refer to the class itself and then you just
655 write the operator expression inside the ``def()`` call. This class::
659 vec operator+(int s);
662 Is registered like this:
669 .def(**self + int()**)
672 This will work regardless if your plus operator is defined inside your class or
675 If your operator is const (or, when defined as a free function, takes a const
676 reference to the class itself) you have to use ``const_self`` instead of
684 .def(**const_self** + int())
687 The operators supported are those available in Lua:
693 This means, no in-place operators. The equality operator (``==``) has a little
694 hitch; it will not be called if the references are equal. This means that the
695 ``==`` operator has to do pretty much what's it's expected to do.
697 Lua does not support operators such as ``!=``, ``>`` or ``>=``. That's why you
698 can only register the operators listed above. When you invoke one of the
699 mentioned operators, lua will define it in terms of one of the avaliable
702 In the above example the other operand type is instantiated by writing
703 ``int()``. If the operand type is a complex type that cannot easily be
704 instantiated you can wrap the type in a class called ``other<>``. For example:
706 To register this class, we don't want to instantiate a string just to register
713 vec operator+(std::string);
716 Instead we use the ``other<>`` wrapper like this:
723 .def(self + **other<std::string>()**)
726 To register an application (function call-) operator:
733 .def( **self(int())** )
736 There's one special operator. In Lua it's called ``__tostring``, it's not
737 really an operator. It is used for converting objects to strings in a standard
738 way in Lua. If you register this functionality, you will be able to use the lua
739 standard function ``tostring()`` for converting your object to a string.
741 To implement this operator in C++ you should supply an ``operator<<`` for
742 std::ostream. Like this example:
747 std::ostream& operator<<(std::ostream&, number&);
753 class_<number>("number")
754 .def(**tostring(self)**)
758 Nested scopes and static functions
759 ----------------------------------
761 It is possible to add nested scopes to a class. This is useful when you need
762 to wrap a nested class, or a static function.
767 .def(constructor<>())
770 class_<inner>("nested"),
774 In this example, ``f`` will behave like a static member function of the class
775 ``foo``, and the class ``nested`` will behave like a nested class of ``foo``.
777 It's also possible to add namespace's to classes using the same syntax.
783 If you want to register classes that derives from other classes, you can
784 specify a template parameter ``bases<>`` to the ``class_`` instantiation. The
785 following hierarchy::
790 Would be registered like this::
798 If you have multiple inheritance you can specify more than one base. If B would
799 also derive from a class C, it would be registered like this::
803 class_<B, bases<A, C> >("B")
806 Note that you can omit ``bases<>`` when using single inheritance.
809 If you don't specify that classes derive from each other, luabind will not
810 be able to implicitly cast pointers between the types.
816 When you register a class you can tell luabind that all instances of that class
817 should be held by some kind of smart pointer (boost::shared_ptr for instance).
818 You do this by giving the holder type as an extra template parameter to
819 the ``class_`` you are constructing, like this::
823 class_<A, boost::shared_ptr<A> >("A")
826 You also have to supply two functions for your smart pointer. One that returns
827 the type of const version of the smart pointer type (boost::shared_ptr<const A>
828 in this case). And one function that extracts the raw pointer from the smart
829 pointer. The first function is needed because luabind has to allow the
830 non-const -> conversion when passing values from Lua to C++. The second
831 function is needed when Lua calls member functions on held types, the this
832 pointer must be a raw pointer, it is also needed to allow the smart_pointer ->
833 raw_pointer conversion from Lua to C++. They look like this::
838 T* get_pointer(boost::shared_ptr<T>& p)
844 boost::shared_ptr<const A>*
845 get_const_holder(boost::shared_ptr<A>*)
851 The second function will only be used to get a compile time mapping
852 of ``boost::shared_ptr<A>`` to its const version,
853 ``boost::shared_ptr<const A>``. It will never be called, so the
854 return value doesn't matter (only the return type).
856 The conversion that works are (given that B is a base class of A):
858 .. topic:: From Lua to C++
860 ========================= ========================
862 ========================= ========================
863 ``holder_type<A>`` ``A*``
864 ``holder_type<A>`` ``B*``
865 ``holder_type<A>`` ``A const*``
866 ``holder_type<A>`` ``B const*``
867 ``holder_type<A>`` ``holder_type<A>``
868 ``holder_type<A>`` ``holder_type<A const>``
869 ``holder_type<A const>`` ``A const*``
870 ``holder_type<A const>`` ``B const*``
871 ``holder_type<A const>`` ``holder_type<A const>``
872 ========================= ========================
874 .. topic:: From C++ to Lua
876 =============================== ========================
878 =============================== ========================
879 ``holder_type<A>`` ``holder_type<A>``
880 ``holder_type<A const>`` ``holder_type<A const>``
881 ``holder_type<A> const&`` ``holder_type<A>``
882 ``holder_type<A const> const&`` ``holder_type<A const>``
883 =============================== ========================
885 When using a holder type, it can be useful to know if the pointer is valid
886 (i.e. not null). For example when using std::auto_ptr, the holder will be
887 invalidated when passed as a parameter to a function. For this purpose there
888 is a member of all object instances in luabind: ``__ok``. ::
891 void f(std::auto_ptr<X>);
895 class_<X, std::auto_ptr<X> >("X")
896 .def(constructor<>()),
903 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
910 When registering a hierarchy of classes, where all instances are to be held
911 by a smart pointer, all the classes should have the baseclass' holder type.
918 class_<base, boost::shared_ptr<base> >("base")
919 .def(constructor<>()),
920 class_<derived, base, **boost::shared_ptr<base>** >("base")
921 .def(constructor<>())
924 Internally, luabind will do the necessary conversions on the raw pointers, which
925 are first extracted from the holder type.
928 Splitting class registrations
929 -----------------------------
931 In some situations it may be desirable to split a registration of a class
932 across different compilation units. Partly to save rebuild time when changing
933 in one part of the binding, and in some cases compiler limits may force you
934 to split it. To do this is very simple. Consider the following sample code::
936 void register_part1(class_<X>& x)
941 void register_part2(class_<X>& x)
946 void register_(lua_State* L)
956 Here, the class ``X`` is registered in two steps. The two functions
957 ``register_part1`` and ``register_part2`` may be put in separate compilation
960 To separate the module registration and the classes to be registered, see
961 `Splitting up the registration`_.
966 Since functions have to be able to take Lua values (of variable type) we need a
967 wrapper around them. This wrapper is called ``luabind::object``. If the
968 function you register takes an object, it will match any Lua value. To use it,
969 you need to include ``<luabind/object.hpp>``.
979 object(lua_State\*, T const& value);
980 object(from_stack const&);
981 object(object const&);
986 lua_State\* interpreter() const;
988 bool is_valid() const;
989 operator *safe_bool_type* () const;
992 *implementation-defined* operator[](Key const&);
995 object& operator=(T const&);
996 object& operator=(object const&);
998 bool operator==(object const&) const;
999 bool operator<(object const&) const;
1000 bool operator<=(object const&) const;
1001 bool operator>(object const&) const;
1002 bool operator>=(object const&) const;
1003 bool operator!=(object const&) const;
1006 *implementation-defined* operator[](T const& key) const
1010 *implementation-defined* operator()();
1013 *implementation-defined* operator()(A0 const& a0);
1015 template<class A0, class A1>
1016 *implementation-defined* operator()(A0 const& a0, A1 const& a1);
1021 When you have a Lua object, you can assign it a new value with the assignment
1022 operator (=). When you do this, the ``default_policy`` will be used to make the
1023 conversion from C++ value to Lua. If your ``luabind::object`` is a table you
1024 can access its members through the operator[] or the Iterators_. The value
1025 returned from the operator[] is a proxy object that can be used both for
1026 reading and writing values into the table (using operator=).
1028 Note that it is impossible to know if a Lua value is indexable or not
1029 (``lua_gettable`` doesn't fail, it succeeds or crashes). This means that if
1030 you're trying to index something that cannot be indexed, you're on your own.
1031 Lua will call its ``panic()`` function. See `lua panic`_.
1033 There are also free functions that can be used for indexing the table, see
1034 `Related functions`_.
1036 The constructor that takes a ``from_stack`` object is used when you want to
1037 initialize the object with a value from the lua stack. The ``from_stack``
1038 type has the following constructor::
1040 from_stack(lua_State* L, int index);
1042 The index is an ordinary lua stack index, negative values are indexed from the
1043 top of the stack. You use it like this::
1045 object o(from_stack(L, -1));
1047 This will create the object ``o`` and copy the value from the top of the lua stack.
1049 The ``interpreter()`` function returns the Lua state where this object is stored.
1050 If you want to manipulate the object with Lua functions directly you can push
1051 it onto the Lua stack by calling ``push()``.
1053 The operator== will call lua_equal() on the operands and return its result.
1055 The ``is_valid()`` function tells you whether the object has been initialized
1056 or not. When created with its default constructor, objects are invalid. To make
1057 an object valid, you can assign it a value. If you want to invalidate an object
1058 you can simply assign it an invalid object.
1060 The ``operator safe_bool_type()`` is equivalent to ``is_valid()``. This means
1061 that these snippets are equivalent::
1079 The application operator will call the value as if it was a function. You can
1080 give it any number of parameters (currently the ``default_policy`` will be used
1081 for the conversion). The returned object refers to the return value (currently
1082 only one return value is supported). This operator may throw ``luabind::error``
1083 if the function call fails. If you want to specify policies to your function
1084 call, you can use index-operator (operator[]) on the function call, and give
1085 the policies within the [ and ]. Like this::
1090 , new my_complex_structure(6)
1093 This tells luabind to make Lua adopt the ownership and responsibility for the
1094 pointer passed in to the lua-function.
1096 It's important that all instances of object have been destructed by the time
1097 the Lua state is closed. The object will keep a pointer to the lua state and
1098 release its Lua object in its destructor.
1100 Here's an example of how a function can use a table::
1102 void my_function(object const& table)
1104 if (type(table) == LUA_TTABLE)
1106 table["time"] = std::clock();
1107 table["name"] = std::rand() < 500 ? "unusual" : "usual";
1109 std::cout << object_cast<std::string>(table[5]) << "\n";
1113 If you take a ``luabind::object`` as a parameter to a function, any Lua value
1114 will match that parameter. That's why we have to make sure it's a table before
1119 std::ostream& operator<<(std::ostream&, object const&);
1121 There's a stream operator that makes it possible to print objects or use
1122 ``boost::lexical_cast`` to convert it to a string. This will use lua's string
1123 conversion function. So if you convert a C++ object with a ``tostring``
1124 operator, the stream operator for that type will be used.
1129 There are two kinds of iterators. The normal iterator that will use the metamethod
1130 of the object (if there is any) when the value is retrieved. This iterator is simply
1131 called ``luabind::iterator``. The other iterator is called ``luabind::raw_iterator``
1132 and will bypass the metamethod and give the true contents of the table. They have
1133 identical interfaces, which implements the ForwardIterator_ concept. Apart from
1134 the members of standard iterators, they have the following members and constructors:
1136 .. _ForwardIterator: http://www.sgi.com/tech/stl/ForwardIterator.html
1143 iterator(object const&);
1147 *standard iterator members*
1150 The constructor that takes a ``luabind::object`` is actually a template that can be
1151 used with object. Passing an object as the parameter to the iterator will
1152 construct the iterator to refer to the first element in the object.
1154 The default constructor will initialize the iterator to the one-past-end
1155 iterator. This is used to test for the end of the sequence.
1157 The value type of the iterator is an implementation defined proxy type which
1158 supports the same operations as ``luabind::object``. Which means that in most
1159 cases you can just treat it as an ordinary object. The difference is that any
1160 assignments to this proxy will result in the value being inserted at the
1161 iterators position, in the table.
1163 The ``key()`` member returns the key used by the iterator when indexing the
1164 associated Lua table.
1166 An example using iterators::
1168 for (iterator i(globals(L)["a"]), end; i != end; ++i)
1173 The iterator named ``end`` will be constructed using the default constructor
1174 and hence refer to the end of the sequence. This example will simply iterate
1175 over the entries in the global table ``a`` and set all its values to 1.
1180 There are a couple of functions related to objects and tables.
1184 int type(object const&);
1186 This function will return the lua type index of the given object.
1187 i.e. ``LUA_TNIL``, ``LUA_TNUMBER`` etc.
1191 template<class T, class K>
1192 void settable(object const& o, K const& key, T const& value);
1194 object gettable(object const& o, K const& key);
1195 template<class T, class K>
1196 void rawset(object const& o, K const& key, T const& value);
1198 object rawget(object const& o, K const& key);
1200 These functions are used for indexing into tables. ``settable`` and ``gettable``
1201 translates into calls to ``lua_settable`` and ``lua_gettable`` respectively. Which
1202 means that you could just as well use the index operator of the object.
1204 ``rawset`` and ``rawget`` will translate into calls to ``lua_rawset`` and
1205 ``lua_rawget`` respectively. So they will bypass any metamethod and give you the
1206 true value of the table entry.
1211 T object_cast<T>(object const&);
1212 template<class T, class Policies>
1213 T object_cast<T>(object const&, Policies);
1216 boost::optional<T> object_cast_nothrow<T>(object const&);
1217 template<class T, class Policies>
1218 boost::optional<T> object_cast_nothrow<T>(object const&, Policies);
1220 The ``object_cast`` function casts the value of an object to a C++ value.
1221 You can supply a policy to handle the conversion from lua to C++. If the cast
1222 cannot be made a ``cast_failed`` exception will be thrown. If you have
1223 defined LUABIND_NO_ERROR_CHECKING (see `Build options`_) no checking will occur,
1224 and if the cast is invalid the application may very well crash. The nothrow
1225 versions will return an uninitialized ``boost::optional<T>`` object, to
1226 indicate that the cast could not be performed.
1228 The function signatures of all of the above functions are really templates
1229 for the object parameter, but the intention is that you should only pass
1230 objects in there, that's why it's left out of the documentation.
1234 object globals(lua_State*);
1235 object registry(lua_State*);
1237 These functions return the global environment table and the registry table respectively.
1241 object newtable(lua_State*);
1243 This function creates a new table and returns it as an object.
1248 To set a table entry to ``nil``, you can use ``luabind::nil``. It will avoid
1249 having to take the detour by first assigning ``nil`` to an object and then
1250 assign that to the table entry. It will simply result in a ``lua_pushnil()``
1251 call, instead of copying an object.
1256 object table = newtable(L);
1257 table["foo"] = "bar";
1259 // now, clear the "foo"-field
1263 Defining classes in Lua
1264 =======================
1266 In addition to binding C++ functions and classes with Lua, luabind also provide
1267 an OO-system in Lua. ::
1269 class 'lua_testclass'
1271 function lua_testclass:__init(name)
1275 function lua_testclass:print()
1279 a = lua_testclass('example')
1283 Inheritance can be used between lua-classes::
1285 class 'derived' (lua_testclass)
1287 function derived:__init() super('derived name')
1290 function derived:print()
1291 print('Derived:print() -> ')
1292 lua_testclass.print(self)
1295 Here the ``super`` keyword is used in the constructor to initialize the base
1296 class. The user is required to call ``super`` first in the constructor.
1298 As you can see in this example, you can call the base class member functions.
1299 You can find all member functions in the base class, but you will have to give
1300 the this-pointer (``self``) as first argument.
1306 It is also possible to derive Lua classes from C++ classes, and override
1307 virtual functions with Lua functions. To do this we have to create a wrapper
1308 class for our C++ base class. This is the class that will hold the Lua object
1309 when we instantiate a Lua class.
1317 { std::cout << s << "\n"; }
1319 virtual void f(int a)
1320 { std::cout << "f(" << a << ")\n"; }
1323 struct base_wrapper : base, luabind::wrap_base
1325 base_wrapper(const char* s)
1329 virtual void f(int a)
1334 static void default_f(base* ptr, int a)
1336 return ptr->base::f(a);
1344 class_<base, base_wrapper>("base")
1345 .def(constructor<const char*>())
1346 .def("f", &base::f, &base_wrapper::default_f)
1350 Since MSVC6.5 doesn't support explicit template parameters
1351 to member functions, instead of using the member function ``call()``
1352 you call a free function ``call_member()`` and pass the this-pointer
1355 Note that if you have both base classes and a base class wrapper, you must give
1356 both bases and the base class wrapper type as template parameter to
1357 ``class_`` (as done in the example above). The order in which you specify
1358 them is not important. You must also register both the static version and the
1359 virtual version of the function from the wrapper, this is necessary in order
1360 to allow luabind to use both dynamic and static dispatch when calling the function.
1363 It is extremely important that the signatures of the static (default) function
1364 is identical to the virtual function. The fact that one of them is a free
1365 function and the other a member function doesn't matter, but the parameters
1366 as seen from lua must match. It would not have worked if the static function
1367 took a ``base_wrapper*`` as its first argument, since the virtual function
1368 takes a ``base*`` as its first argument (its this pointer). There's currently
1369 no check in luabind to make sure the signatures match.
1371 If we didn't have a class wrapper, it would not be possible to pass a Lua class
1372 back to C++. Since the entry points of the virtual functions would still point
1373 to the C++ base class, and not to the functions defined in Lua. That's why we
1374 need one function that calls the base class' real function (used if the lua
1375 class doesn't redefine it) and one virtual function that dispatches the call
1376 into luabind, to allow it to select if a Lua function should be called, or if
1377 the original function should be called. If you don't intend to derive from a
1378 C++ class, or if it doesn't have any virtual member functions, you can register
1379 it without a class wrapper.
1381 You don't need to have a class wrapper in order to derive from a class, but if
1382 it has virtual functions you may have silent errors.
1384 .. Unnecessary? The rule of thumb is:
1385 If your class has virtual functions, create a wrapper type, if it doesn't
1386 don't create a wrapper type.
1388 The wrappers must derive from ``luabind::wrap_base``, it contains a Lua reference
1389 that will hold the Lua instance of the object to make it possible to dispatch
1390 virtual function calls into Lua. This is done through an overloaded member function::
1393 Ret call(char const* name, ...)
1395 Its used in a similar way as ``call_function``, with the exception that it doesn't
1396 take a ``lua_State`` pointer, and the name is a member function in the Lua class.
1400 The current implementation of ``call_member`` is not able to distinguish const
1401 member functions from non-const. If you have a situation where you have an overloaded
1402 virtual function where the only difference in their signatures is their constness, the
1403 wrong overload will be called by ``call_member``. This is rarely the case though.
1408 When a pointer or reference to a registered class with a wrapper is passed
1409 to Lua, luabind will query for it's dynamic type. If the dynamic type
1410 inherits from ``wrap_base``, object identity is preserved.
1415 struct A_wrap : A, wrap_base { .. };
1417 A* f(A* ptr) { return ptr; }
1421 class_<A, A_wrap>("A"),
1429 > assert(x == f(x)) -- object identity is preserved when object is
1430 -- passed through C++
1432 This functionality relies on RTTI being enabled (that ``LUABIND_NO_RTTI`` is
1435 Overloading operators
1436 ---------------------
1438 You can overload most operators in Lua for your classes. You do this by simply
1439 declaring a member function with the same name as an operator (the name of the
1440 metamethods in Lua). The operators you can overload are:
1454 ``__tostring`` isn't really an operator, but it's the metamethod that is called
1455 by the standard library's ``tostring()`` function. There's one strange behavior
1456 regarding binary operators. You are not guaranteed that the self pointer you
1457 get actually refers to an instance of your class. This is because Lua doesn't
1458 distinguish the two cases where you get the other operand as left hand value or
1459 right hand value. Consider the following examples::
1463 function my_class:__init(v)
1467 function my_class:__sub(v)
1468 return my_class(self.val - v.val)
1471 function my_class:__tostring()
1475 This will work well as long as you only subtracts instances of my_class with
1476 each other. But If you want to be able to subtract ordinary numbers from your
1477 class too, you have to manually check the type of both operands, including the
1480 function my_class:__sub(v)
1481 if (type(self) == 'number') then
1482 return my_class(self - v.val)
1484 elseif (type(v) == 'number') then
1485 return my_class(self.val - v)
1488 -- assume both operands are instances of my_class
1489 return my_class(self.val - v.val)
1494 The reason why ``__sub`` is used as an example is because subtraction is not
1495 commutative (the order of the operands matters). That's why luabind cannot
1496 change order of the operands to make the self reference always refer to the
1497 actual class instance.
1499 If you have two different Lua classes with an overloaded operator, the operator
1500 of the right hand side type will be called. If the other operand is a C++ class
1501 with the same operator overloaded, it will be prioritized over the Lua class'
1502 operator. If none of the C++ overloads matches, the Lua class operator will be
1509 If an object needs to perform actions when it's collected we provide a
1510 ``__finalize`` function that can be overridden in lua-classes. The
1511 ``__finalize`` functions will be called on all classes in the inheritance
1512 chain, starting with the most derived type. ::
1516 function lua_testclass:__finalize()
1517 -- called when the an object is collected
1524 If your lua C++ classes don't have wrappers (see `Deriving in lua`_) and
1525 you derive from them in lua, they may be sliced. Meaning, if an object
1526 is passed into C++ as a pointer to its base class, the lua part will be
1527 separated from the C++ base part. This means that if you call virtual
1528 functions on that C++ object, they will not be dispatched to the lua
1529 class. It also means that if you adopt the object, the lua part will be
1534 +--------------------+
1535 | C++ object | <- ownership of this part is transferred
1536 | | to c++ when adopted
1537 +--------------------+
1538 | lua class instance | <- this part is garbage collected when
1539 | and lua members | instance is adopted, since it cannot
1540 +--------------------+ be held by c++.
1543 The problem can be illustrated by this example::
1547 A* filter_a(A* a) { return a; }
1548 void adopt_a(A* a) { delete a; }
1553 using namespace luabind;
1558 def("filter_a", &filter_a),
1559 def("adopt_a", &adopt_a, adopt(_1))
1569 In this example, lua cannot know that ``b`` actually is the same object as
1570 ``a``, and it will therefore consider the object to be owned by the C++ side.
1571 When the ``b`` pointer then is adopted, a runtime error will be raised because
1572 an object not owned by lua is being adopted to C++.
1574 If you have a wrapper for your class, none of this will happen, see
1581 If any of the functions you register throws an exception when called, that
1582 exception will be caught by luabind and converted to an error string and
1583 ``lua_error()`` will be invoked. If the exception is a ``std::exception`` or a
1584 ``const char*`` the string that is pushed on the Lua stack, as error message,
1585 will be the string returned by ``std::exception::what()`` or the string itself
1586 respectively. If the exception is unknown, a generic string saying that the
1587 function threw an exception will be pushed.
1589 Exceptions thrown from user defined functions have to be caught by luabind. If
1590 they weren't they would be thrown through Lua itself, which is usually compiled
1591 as C code and doesn't support the stack-unwinding that exceptions imply.
1593 Any function that invokes Lua code may throw ``luabind::error``. This exception
1594 means that a Lua run-time error occurred. The error message is found on top of
1595 the Lua stack. The reason why the exception doesn't contain the error string
1596 itself is because it would then require heap allocation which may fail. If an
1597 exception class throws an exception while it is being thrown itself, the
1598 application will be terminated.
1600 Error's synopsis is::
1602 class error : public std::exception
1606 lua_State* state() const throw();
1607 virtual const char* what() const throw();
1610 The state function returns a pointer to the Lua state in which the error was
1611 thrown. This pointer may be invalid if you catch this exception after the lua
1612 state is destructed. If the Lua state is valid you can use it to retrieve the
1613 error message from the top of the Lua stack.
1615 An example of where the Lua state pointer may point to an invalid state
1620 lua_state(lua_State* L): m_L(L) {}
1621 ~lua_state() { lua_close(m_L); }
1622 operator lua_State*() { return m_L; }
1630 lua_state L = lua_open();
1633 catch(luabind::error& e)
1635 lua_State* L = e.state();
1636 // L will now point to the destructed
1637 // Lua state and be invalid
1642 There's another exception that luabind may throw: ``luabind::cast_failed``,
1643 this exception is thrown from ``call_function<>`` or ``call_member<>``. It
1644 means that the return value from the Lua function couldn't be converted to
1645 a C++ value. It is also thrown from ``object_cast<>`` if the cast cannot
1648 The synopsis for ``luabind::cast_failed`` is::
1650 class cast_failed : public std::exception
1653 cast_failed(lua_State*);
1654 lua_State* state() const throw();
1655 LUABIND_TYPE_INFO info() const throw();
1656 virtual const char* what() const throw();
1659 Again, the state member function returns a pointer to the Lua state where the
1660 error occurred. See the example above to see where this pointer may be invalid.
1662 The info member function returns the user defined ``LUABIND_TYPE_INFO``, which
1663 defaults to a ``const std::type_info*``. This type info describes the type that
1664 we tried to cast a Lua value to.
1666 If you have defined ``LUABIND_NO_EXCEPTIONS`` none of these exceptions will be
1667 thrown, instead you can set two callback functions that are called instead.
1668 These two functions are only defined if ``LUABIND_NO_EXCEPTIONS`` are defined.
1672 luabind::set_error_callback(void(*)(lua_State*))
1674 The function you set will be called when a runtime-error occur in Lua code. You
1675 can find an error message on top of the Lua stack. This function is not
1676 expected to return, if it does luabind will call ``std::terminate()``.
1680 luabind::set_cast_failed_callback(void(*)(lua_State*, LUABIND_TYPE_INFO))
1682 The function you set is called instead of throwing ``cast_failed``. This function
1683 is not expected to return, if it does luabind will call ``std::terminate()``.
1689 Sometimes it is necessary to control how luabind passes arguments and return
1690 value, to do this we have policies. All policies use an index to associate
1691 them with an argument in the function signature. These indices are ``result``
1692 and ``_N`` (where ``N >= 1``). When dealing with member functions ``_1`` refers
1693 to the ``this`` pointer.
1695 .. contents:: Policies currently implemented
1699 .. include:: adopt.rst
1700 .. include:: dependency.rst
1701 .. include:: out_value.rst
1702 .. include:: pure_out_value.rst
1703 .. include:: return_reference_to.rst
1704 .. include:: copy.rst
1705 .. include:: discard_result.rst
1706 .. include:: return_stl_iterator.rst
1707 .. include:: raw.rst
1708 .. include:: yield.rst
1710 .. old policies section
1711 ===================================================
1716 This will make a copy of the parameter. This is the default behavior when
1717 passing parameters by-value. Note that this can only be used when passing from
1718 C++ to Lua. This policy requires that the parameter type has a copy
1721 To use this policy you need to include ``luabind/copy_policy.hpp``.
1727 This will transfer ownership of the parameter.
1729 Consider making a factory function in C++ and exposing it to lua::
1740 def("create_base", create_base)
1743 Here we need to make sure Lua understands that it should adopt the pointer
1744 returned by the factory-function. This can be done using the adopt-policy.
1750 def(L, "create_base", adopt(return_value))
1753 To specify multiple policies we just separate them with '+'.
1757 base* set_and_get_new(base* ptr)
1759 base_ptrs.push_back(ptr);
1765 def("set_and_get_new", &set_and_get_new,
1766 adopt(return_value) + adopt(_1))
1769 When Lua adopts a pointer, it will call delete on it. This means that it cannot
1770 adopt pointers allocated with another allocator than new (no malloc for
1773 To use this policy you need to include ``luabind/adopt_policy.hpp``.
1779 The dependency policy is used to create life-time dependencies between values.
1780 Consider the following example::
1786 const B& get_member()
1792 When wrapping this class, we would do something like::
1797 .def(constructor<>())
1798 .def("get_member", &A::get_member)
1802 However, since the return value of get_member is a reference to a member of A,
1803 this will create some life-time issues. For example::
1805 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1807 b = a:get_member() -- b points to a member of a
1809 collectgarbage(0) -- since there are no references left to a, it is
1811 -- at this point, b is pointing into a removed object
1813 When using the dependency-policy, it is possible to tell luabind to tie the
1814 lifetime of one object to another, like this::
1819 .def(constructor<>())
1820 .def("get_member", &A::get_member, dependency(result, _1))
1823 This will create a dependency between the return-value of the function, and the
1824 self-object. This means that the self-object will be kept alive as long as the
1825 result is still alive. ::
1827 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1829 b = a:get_member() -- b points to a member of a
1831 collectgarbage(0) -- a is dependent on b, so it isn't removed
1833 collectgarbage(0) -- all dependencies to a gone, a is removed
1835 To use this policy you need to include ``luabind/dependency_policy.hpp``.
1841 It is very common to return references to arguments or the this-pointer to
1842 allow for chaining in C++.
1857 When luabind generates code for this, it will create a new object for the
1858 return-value, pointing to the self-object. This isn't a problem, but could be a
1859 bit inefficient. When using the return_reference_to-policy we have the ability
1860 to tell luabind that the return-value is already on the Lua stack.
1867 .def(constructor<>())
1868 .def("set", &A::set, return_reference_to(_1))
1871 Instead of creating a new object, luabind will just copy the object that is
1872 already on the stack.
1875 This policy ignores all type information and should be used only it
1876 situations where the parameter type is a perfect match to the
1877 return-type (such as in the example).
1879 To use this policy you need to include ``luabind/return_reference_to_policy.hpp``.
1885 This policy makes it possible to wrap functions that take non const references
1886 as its parameters with the intention to write return values to them.
1890 void f(float& val) { val = val + 10.f; }
1896 void f(float* val) { *val = *val + 10.f; }
1898 Can be wrapped by doing::
1902 def("f", &f, out_value(_1))
1905 When invoking this function from Lua it will return the value assigned to its
1910 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1915 When this policy is used in conjunction with user define types we often need
1916 to do ownership transfers.
1922 void f1(A*& obj) { obj = new A(); }
1923 void f2(A** obj) { *obj = new A(); }
1925 Here we need to make sure luabind takes control over object returned, for
1926 this we use the adopt policy::
1931 def("f1", &f1, out_value(_1, adopt(_2)))
1932 def("f2", &f2, out_value(_1, adopt(_2)))
1935 Here we are using adopt as an internal policy to out_value. The index
1936 specified, _2, means adopt will be used to convert the value back to Lua.
1937 Using _1 means the policy will be used when converting from Lua to C++.
1939 To use this policy you need to include ``luabind/out_value_policy.hpp``.
1944 This policy works in exactly the same way as out_value, except that it
1945 replaces the parameters with default-constructed objects.
1949 void get(float& x, float& y)
1960 pure_out_value(_1) + pure_out_value(_2))
1965 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1970 Like out_value, it is possible to specify an internal policy used then
1971 converting the values back to Lua.
1975 void get(test_class*& obj)
1977 obj = new test_class();
1984 def("get", &get, pure_out_value(_1, adopt(_1)))
1991 This is a very simple policy which makes it possible to throw away
1992 the value returned by a C++ function, instead of converting it to
1993 Lua. This example makes sure the this reference never gets converted
2000 simple& set_name(const std::string& n)
2013 class_<simple>("simple")
2014 .def("set_name", &simple::set_name, discard_result)
2017 To use this policy you need to include ``luabind/discard_result_policy.hpp``.
2023 This policy converts an STL container to a generator function that can be used
2024 in Lua to iterate over the container. It works on any container that defines
2025 ``begin()`` and ``end()`` member functions (they have to return iterators). It
2026 can be used like this::
2030 std::vector<std::string> names;
2037 .def_readwrite("names", &A::names, return_stl_iterator)
2040 The Lua code to iterate over the container::
2044 for name in a.names do
2049 To use this policy you need to include ``luabind/iterator_policy.hpp``.
2055 This policy will cause the function to always yield the current thread when
2056 returning. See the Lua manual for restrictions on yield.
2059 Splitting up the registration
2060 =============================
2062 It is possible to split up a module registration into several
2063 translation units without making each registration dependent
2064 on the module it's being registered in.
2068 luabind::scope register_a()
2078 luabind::scope register_b()
2088 luabind::scope register_a();
2089 luabind::scope register_b();
2091 void register_module(lua_State* L)
2107 As mentioned in the `Lua documentation`_, it is possible to pass an
2108 error handler function to ``lua_pcall()``. Luabind makes use of
2109 ``lua_pcall()`` internally when calling member functions and free functions.
2110 It is possible to set the error handler function that Luabind will use
2113 typedef int(*pcall_callback_fun)(lua_State*);
2114 void set_pcall_callback(pcall_callback_fun fn);
2116 This is primarily useful for adding more information to the error message
2117 returned by a failed protected call. For more information on how to use the
2118 pcall_callback function, see ``errfunc`` under the
2119 `pcall section of the lua manual`_.
2121 For more information on how to retrieve debugging information from lua, see
2122 `the debug section of the lua manual`_.
2124 The message returned by the ``pcall_callback`` is accessable as the top lua
2125 value on the stack. For example, if you would like to access it as a luabind
2126 object, you could do like this::
2130 object error_msg(from_stack(e.state(), -1));
2131 std::cout << error_msg << std::endl;
2134 .. _Lua documentation: http://www.lua.org/manual/5.0/manual.html
2135 .. _`pcall section of the lua manual`: http://www.lua.org/manual/5.0/manual.html#3.15
2136 .. _`the debug section of the lua manual`: http://www.lua.org/manual/5.0/manual.html#4
2138 file and line numbers
2139 ---------------------
2141 If you want to add file name and line number to the error messages generated
2142 by luabind you can define your own `pcall errorfunc`_. You may want to modify
2143 this callback to better suit your needs, but the basic functionality could be
2144 implemented like this::
2146 int add_file_and_line(lua_State* L)
2149 lua_getstack(L, 1, &d);
2150 lua_getinfo(L, "Sln", &d);
2151 std::string err = lua_tostring(L, -1);
2153 std::stringstream msg;
2154 msg << d.short_src << ":" << d.currentline;
2158 msg << "(" << d.namewhat << " " << d.name << ")";
2161 lua_pushstring(L, msg.str().c_str());
2165 For more information about what kind of information you can add to the error
2166 message, see `the debug section of the lua manual`_.
2168 Note that the callback set by ``set_pcall_callback()`` will only be used when
2169 luabind executes lua code. Anytime when you call ``lua_pcall`` yourself, you
2170 have to supply your function if you want error messages translated.
2175 When lua encounters a fatal error caused by a bug from the C/C++ side, it will
2176 call its internal panic function. This can happen, for example, when you call
2177 ``lua_gettable`` on a value that isn't a table. If you do the same thing from
2178 within lua, it will of course just fail with an error message.
2180 The default panic function will ``exit()`` the application. If you want to
2181 handle this case without terminating your application, you can define your own
2182 panic function using ``lua_atpanic``. The best way to continue from the panic
2183 function is to make sure lua is compiled as C++ and throw an exception from
2184 the panic function. Throwing an exception instead of using ``setjmp`` and
2185 ``longjmp`` will make sure the stack is correctly unwound.
2187 When the panic function is called, the lua state is invalid, and the only
2188 allowed operation on it is to close it.
2190 For more information, see the `lua manual section 3.19`_.
2192 .. _`lua manual section 3.19`: http://www.lua.org/manual/5.0/manual.html#3.19
2194 structured exceptions (MSVC)
2195 ----------------------------
2197 Since lua is generally built as a C library, any callbacks called from lua
2198 cannot under any circumstance throw an exception. Because of that, luabind has
2199 to catch all exceptions and translate them into proper lua errors (by calling
2200 ``lua_error()``). This means we have a ``catch(...) {}`` in there.
2202 In Visual Studio, ``catch (...)`` will not only catch C++ exceptions, it will
2203 also catch structured exceptions, such as segmentation fault. This means that if
2204 your function, that gets called from luabind, makes an invalid memory
2205 adressing, you won't notice it. All that will happen is that lua will return
2206 an error message saying "unknown exception".
2208 To remedy this, you can create your own *exception translator*::
2210 void straight_to_debugger(unsigned int, _EXCEPTION_POINTERS*)
2214 ::_set_se_translator(straight_to_debugger);
2217 This will make structured exceptions, like segmentation fault, to actually get
2218 caught by the debugger.
2224 These are the error messages that can be generated by luabind, with a more
2225 in-depth explanation.
2227 - .. parsed-literal::
2229 the attribute '*class-name.attribute-name*' is read only
2231 There is no data member named *attribute-name* in the class *class-name*,
2232 or there's no setter-function registered on that property name. See the
2233 Properties_ section.
2235 - .. parsed-literal::
2237 the attribute '*class-name.attribute-name*' is of type: (*class-name*) and does not match (*class_name*)
2239 This error is generated if you try to assign an attribute with a value
2240 of a type that cannot be converted to the attribute's type.
2243 - .. parsed-literal::
2245 *class-name()* threw an exception, *class-name:function-name()* threw an exception
2247 The class' constructor or member function threw an unknown exception.
2248 Known exceptions are const char*, std::exception. See the
2249 `exceptions`_ section.
2251 - .. parsed-literal::
2253 no overload of '*class-name:function-name*' matched the arguments (*parameter-types*)
2254 no match for function call '*function-name*' with the parameters (*parameter-types*)
2255 no constructor of *class-name* matched the arguments (*parameter-types*)
2256 no operator *operator-name* matched the arguments (*parameter-types*)
2258 No function/operator with the given name takes the parameters you gave
2259 it. You have either misspelled the function name, or given it incorrect
2260 parameters. This error is followed by a list of possible candidate
2261 functions to help you figure out what parameter has the wrong type. If
2262 the candidate list is empty there's no function at all with that name.
2263 See the signature matching section.
2265 - .. parsed-literal::
2267 call of overloaded '*class-name:function-name*(*parameter-types*)' is ambiguous
2268 ambiguous match for function call '*function-name*' with the parameters (*parameter-types*)
2269 call of overloaded constructor '*class-name*(*parameter-types*)' is ambiguous
2270 call of overloaded operator *operator-name* (*parameter-types*) is ambiguous
2272 This means that the function/operator you are trying to call has at least
2273 one other overload that matches the arguments just as good as the first
2276 - .. parsed-literal::
2278 cannot derive from C++ class '*class-name*'. It does not have a wrapped type.
2285 There are a number of configuration options available when building luabind.
2286 It is very important that your project has the exact same configuration
2287 options as the ones given when the library was build! The exceptions are the
2288 ``LUABIND_MAX_ARITY`` and ``LUABIND_MAX_BASES`` which are template-based
2289 options and only matters when you use the library (which means they can
2290 differ from the settings of the library).
2292 The default settings which will be used if no other settings are given
2293 can be found in ``luabind/config.hpp``.
2295 If you want to change the settings of the library, you can modify the
2296 config file. It is included and used by all makefiles. You can change paths
2297 to Lua and boost in there as well.
2300 Controls the maximum arity of functions that are registered with luabind.
2301 You can't register functions that takes more parameters than the number
2302 this macro is set to. It defaults to 5, so, if your functions have greater
2303 arity you have to redefine it. A high limit will increase compilation time.
2306 Controls the maximum number of classes one class can derive from in
2307 luabind (the number of classes specified within ``bases<>``).
2308 ``LUABIND_MAX_BASES`` defaults to 4. A high limit will increase
2311 LUABIND_NO_ERROR_CHECKING
2312 If this macro is defined, all the Lua code is expected only to make legal
2313 calls. If illegal function calls are made (e.g. giving parameters that
2314 doesn't match the function signature) they will not be detected by luabind
2315 and the application will probably crash. Error checking could be disabled
2316 when shipping a release build (given that no end-user has access to write
2317 custom Lua code). Note that function parameter matching will be done if a
2318 function is overloaded, since otherwise it's impossible to know which one
2319 was called. Functions will still be able to throw exceptions when error
2320 checking is disabled.
2322 If a function throws an exception it will be caught by luabind and
2323 propagated with ``lua_error()``.
2325 LUABIND_NO_EXCEPTIONS
2326 This define will disable all usage of try, catch and throw in luabind.
2327 This will in many cases disable run-time errors, when performing invalid
2328 casts or calling Lua functions that fails or returns values that cannot
2329 be converted by the given policy. luabind requires that no function called
2330 directly or indirectly by luabind throws an exception (throwing exceptions
2331 through Lua has undefined behavior).
2333 Where exceptions are the only way to get an error report from luabind,
2334 they will be replaced with calls to the callback functions set with
2335 ``set_error_callback()`` and ``set_cast_failed_callback()``.
2338 If you want to link dynamically against Lua, you can set this define to
2339 the import-keyword on your compiler and platform. On Windows in Visual Studio
2340 this should be ``__declspec(dllimport)`` if you want to link against Lua
2343 LUABIND_EXPORT, LUABIND_IMPORT
2344 If you want to link against luabind as a dll (in Visual Studio), you can
2345 define ``LUABIND_EXPORT`` to ``__declspec(dllexport)`` and
2346 ``LUABIND_IMPORT`` to ``__declspec(dllimport)`` or
2347 ``__attribute__ ((visibility("default")))`` on GCC 4.
2348 Note that you have to link against Lua as a dll aswell, to make it work.
2351 You can define this if you don't want luabind to use ``dynamic_cast<>``.
2352 It will disable `Object identity`_.
2354 LUABIND_TYPE_INFO, LUABIND_TYPE_INFO_EQUAL(i1,i2), LUABIND_TYPEID(t), LUABIND_INVALID_TYPE_INFO
2355 If you don't want to use the RTTI supplied by C++ you can supply your own
2356 type-info structure with the ``LUABIND_TYPE_INFO`` define. Your type-info
2357 structure must be copyable and must be able to compare itself against
2358 other type-info structures. You supply the compare function through the
2359 ``LUABIND_TYPE_INFO_EQUAL()`` define. It should compare the two type-info
2360 structures it is given and return true if they represent the same type and
2361 false otherwise. You also have to supply a function to generate your
2362 type-info structure. You do this through the ``LUABIND_TYPEID()`` define.
2363 It should return your type-info structure and it takes a type as its
2364 parameter. That is, a compile time parameter.
2365 ``LUABIND_INVALID_TYPE_INFO`` macro should be defined to an invalid type.
2366 No other type should be able to produce this type info. To use it you
2367 probably have to make a traits class with specializations for all classes
2368 that you have type-info for. Like this::
2374 template<class T> struct typeinfo_trait;
2376 template<> struct typeinfo_trait<A> { enum { type_id = 0 }; };
2377 template<> struct typeinfo_trait<B> { enum { type_id = 1 }; };
2378 template<> struct typeinfo_trait<C> { enum { type_id = 2 }; };
2380 If you have set up your own RTTI system like this (by using integers to
2381 identify types) you can have luabind use it with the following defines::
2383 #define LUABIND_TYPE_INFO const std::type_info*
2384 #define LUABIND_TYPEID(t) &typeid(t)
2385 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
2386 #define LUABIND_INVALID_TYPE_INFO &typeid(detail::null_type)
2388 Currently the type given through ``LUABIND_TYPE_INFO`` must be less-than
2392 This define will disable all asserts and should be defined in a release
2396 Implementation notes
2397 ====================
2399 The classes and objects are implemented as user data in Lua. To make sure that
2400 the user data really is the internal structure it is supposed to be, we tag
2401 their metatables. A user data who's metatable contains a boolean member named
2402 ``__luabind_classrep`` is expected to be a class exported by luabind. A user
2403 data who's metatable contains a boolean member named ``__luabind_class`` is
2404 expected to be an instantiation of a luabind class.
2406 This means that if you make your own user data and tags its metatable with the
2407 exact same names, you can very easily fool luabind and crash the application.
2409 In the Lua registry, luabind keeps an entry called ``__luabind_classes``. It
2410 should not be removed or overwritten.
2412 In the global table, a variable called ``super`` is used every time a
2413 constructor in a lua-class is called. This is to make it easy for that
2414 constructor to call its base class' constructor. So, if you have a global
2415 variable named super it may be overwritten. This is probably not the best
2416 solution, and this restriction may be removed in the future.
2418 Luabind uses two upvalues for functions that it registers. The first is a
2419 userdata containing a list of overloads for the function, the other is a light
2420 userdata with the value 0x1337, this last value is used to identify functions
2421 registered by luabind. It should be virtually impossible to have such a pointer
2422 as secondary upvalue by pure chance. This means, if you are trying to replace
2423 an existing function with a luabind function, luabind will see that the
2424 secondary upvalue isn't the magic id number and replace it. If it can identify
2425 the function to be a luabind function, it won't replace it, but rather add
2426 another overload to it.
2428 Inside the luabind namespace, there's another namespace called detail. This
2429 namespace contains non-public classes and are not supposed to be used directly.
2435 What's up with __cdecl and __stdcall?
2436 If you're having problem with functions
2437 that cannot be converted from ``void (__stdcall *)(int,int)`` to
2438 ``void (__cdecl*)(int,int)``. You can change the project settings to make the
2439 compiler generate functions with __cdecl calling conventions. This is
2440 a problem in developer studio.
2442 What's wrong with functions taking variable number of arguments?
2443 You cannot register a function with ellipses in its signature. Since
2444 ellipses don't preserve type safety, those should be avoided anyway.
2446 Internal structure overflow in VC
2447 If you, in visual studio, get fatal error C1204: compiler limit :
2448 internal structure overflow. You should try to split that compilation
2449 unit up in smaller ones. See `Splitting up the registration`_ and
2450 `Splitting class registrations`_.
2452 What's wrong with precompiled headers in VC?
2453 Visual Studio doesn't like anonymous namespace's in its precompiled
2454 headers. If you encounter this problem you can disable precompiled
2455 headers for the compilation unit (cpp-file) that uses luabind.
2457 error C1076: compiler limit - internal heap limit reached in VC
2458 In visual studio you will probably hit this error. To fix it you have to
2459 increase the internal heap with a command-line option. We managed to
2460 compile the test suit with /Zm300, but you may need a larger heap then
2463 error C1055: compiler limit \: out of keys in VC
2464 It seems that this error occurs when too many assert() are used in a
2465 program, or more specifically, the __LINE__ macro. It seems to be fixed by
2466 changing /ZI (Program database for edit and continue) to /Zi
2469 How come my executable is huge?
2470 If you're compiling in debug mode, you will probably have a lot of
2471 debug-info and symbols (luabind consists of a lot of functions). Also,
2472 if built in debug mode, no optimizations were applied, luabind relies on
2473 that the compiler is able to inline functions. If you built in release
2474 mode, try running strip on your executable to remove export-symbols,
2475 this will trim down the size.
2477 Our tests suggests that cygwin's gcc produces much bigger executables
2478 compared to gcc on other platforms and other compilers.
2480 .. HUH?! // check the magic number that identifies luabind's functions
2482 Can I register class templates with luabind?
2483 Yes you can, but you can only register explicit instantiations of the
2484 class. Because there's no Lua counterpart to C++ templates. For example,
2485 you can register an explicit instantiation of std::vector<> like this::
2489 class_<std::vector<int> >("vector")
2490 .def(constructor<int>)
2491 .def("push_back", &std::vector<int>::push_back)
2494 .. Again, irrelevant to docs: Note that the space between the two > is required by C++.
2496 Do I have to register destructors for my classes?
2497 No, the destructor of a class is always called by luabind when an
2498 object is collected. Note that Lua has to own the object to collect it.
2499 If you pass it to C++ and gives up ownership (with adopt policy) it will
2500 no longer be owned by Lua, and not collected.
2502 If you have a class hierarchy, you should make the destructor virtual if
2503 you want to be sure that the correct destructor is called (this apply to C++
2506 .. And again, the above is irrelevant to docs. This isn't a general C++ FAQ. But it saves us support questions.
2508 Fatal Error C1063 compiler limit \: compiler stack overflow in VC
2509 VC6.5 chokes on warnings, if you are getting alot of warnings from your
2510 code try suppressing them with a pragma directive, this should solve the
2513 Crashes when linking against luabind as a dll in Windows
2514 When you build luabind, Lua and you project, make sure you link against
2515 the runtime dynamically (as a dll).
2517 I cannot register a function with a non-const parameter
2518 This is because there is no way to get a reference to a Lua value. Have
2519 a look at out_value_ and pure_out_value_ policies.
2525 - You cannot use strings with extra nulls in them as member names that refers
2528 - If one class registers two functions with the same name and the same
2529 signature, there's currently no error. The last registered function will
2530 be the one that's used.
2532 - In VC7, classes can not be called test.
2534 - If you register a function and later rename it, error messages will use the
2535 original function name.
2537 - luabind does not support class hierarchies with virtual inheritance. Casts are
2538 done with static pointer offsets.
2544 Written by Daniel Wallin and Arvid Norberg. © Copyright 2003.
2545 All rights reserved.
2547 Evan Wies has contributed with thorough testing, countless bug reports
2550 This library was highly inspired by Dave Abrahams' Boost.Python_ library.
2552 .. _Boost.Python: http://www.boost.org/libraries/python