5 .. _MIT license: http://www.opensource.org/licenses/mit-license.php
6 .. _Boost: http://www.boost.org
8 Note: This library is currently in public beta phase. This documentation
9 should be considered beta as well. Please report any grammatical
10 corrections/spelling corrections.
14 .. section-numbering::
19 Luabind is a library that helps you create bindings between C++ and lua. It has
20 the ability to expose functions and classes, written in C++, to lua. It will
21 also supply the functionality to define classes in lua and let them derive from
22 other lua classes or C++ classes. Lua classes can override virtual functions
23 from their C++ base classes. It is written towards lua 5.0, and does not work
26 It is implemented utilizing template meta programming. That means that you
27 don't need an extra preprocess pass to compile your project (it is done by the
28 compiler). It also means you don't (usually) have to know the exact signatureof
29 each function you register, since the library will generate code depending on
30 the compile-time type of the function (which includes the signature). The main
31 drawback of this approach is that the compilation time will increase for the
32 file that does the registration, it is therefore recommended that you register
33 everything in the same cpp-file.
35 luabind is released under the terms of the `MIT license`_.
37 We are very interested in hearing about projects that use luabind, please let
38 us know about your project.
46 - Overloaded free functions
48 - Overloaded member functions
52 - Lua functions in C++
54 - Lua classes (single inheritance)
55 - Derives from lua or C++ classes
56 - O verride virtual functions from C++ classes
57 - Implicit casts between registered types
58 - Best match signature matching
59 - Return value policies and parameter policies
65 Luabind has been tested to work on the following compilers:
69 - Visual Studio 6.0 (sp 5)
70 - Intel C++ 6.0 (Windows)
72 - GCC 3.0.4 (Debian/Linux)
77 It has been confirmed not to work with:
79 - GCC 2.95.2 (SunOS 5.8)
81 Metrowerks 8.3 (Windows) compiles but fails the const-test. This
82 means that const member functions are treated as non-const member
85 If you have tried luabind with a compiler not listed here, let us know
92 To keep down the compilation-time luabind is built as a library. This means you
93 have to either build it and lika against it, or include its source files in
94 your project. You also have to make sure the luabind directory is somewhere in
95 your compiler's include path. It requires `Boost`_ 1.31.0 to be installed (only
96 boost headers). It also requires that lua is installed.
98 The official way of building luabind is with `Boost.Build V2`_. To properly build
99 luabind with Boost.Build you need to set two environment variables:
102 Point this to your Boost installation.
105 Point this to your lua directory. The build system will assume that the
106 include and library files are located in ``$(LUA_PATH)/include/`` and
107 ``$(LUA_PATH)/lib/.``
109 For backward compatibility, there is also a makefile in the root-directory that
110 will build the library and the test program. If you are using a UNIX-system (or
111 cygwin) they will make it easy to build luabind as a static library. If you are
112 using Visual Studio it may be easier to include the files in the src directory
115 When building luabind you have several options that may streamline the library
116 to better suit your needs. It is extremely important that your application has
117 the same settings as the library was built with. The available options are
118 found in the `Configuration`_ section.
120 If you want to change the settings to differ from the default, it's recommended
121 that you define the settings on the commandline of all your files (in the
122 project settings in visual studio).
124 .. _`Boost.Build V2`: http://www.boost.org/tools/build/v2/index_v2.html
130 To use luabind, you must include ``lua.h`` and luabind's main header file::
137 #include <luabind/luabind.hpp>
139 This includes support for both registering classes and functions. If you just
140 want to have support for functions or classes you can include
141 ``luabind/function.hpp`` and ``luabind/class.hpp`` separately::
143 #include <luabind/function.hpp>
144 #include <luabind/class.hpp>
146 The first thing you need to do is to call ``luabind::open(lua_State*)`` which
147 will register the functions to create classes from lua, and initialize some
148 state-global structures used by luabind. If you don't call this function you
149 will hit asserts later in the library. There is no corresponding close function
150 because once a class has been registered in lua, there really isn't any good
151 way to remove it. Partly because any remaining instances of that class relies
152 on the class being there. Everything will be cleaned up when the state is
155 .. Isn't this wrong? Don't we include lua.h using lua_include.hpp ?
157 Note that no luabind header will include ``lua.h``, this is up to you. You have
158 to include it before any luabind header is included.
167 #include <luabind/luabind.hpp>
171 std::cout << "hello world!\n";
174 extern "C" int init(lua_State* L)
176 using namespace luabind;
190 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
191 > loadlib('hello_world.dll', 'init')()
199 Everything that gets registered in lua is registered in a namespace (lua
200 tables) or in the global scope (called module). All registrations must be
201 surrounded by its scope. To define a module, the ``luabind::module`` class is
202 used. It is used like this::
209 This will register all declared functions or classes in the global namespace in
210 lua. If you want to have a namespace for your module (like the standard
211 libraries) you can give a name to the constructor, like this::
213 module(L, "my_library")
218 Here all declarations will be put in the my_library table.
220 If you want nested namespaces you can use the ``luabind::namespace_`` class. It
221 works exactly as ``luabind::module`` except that it doesn't take a lua_State*
222 in it's constructor. An example of its usage could look like this::
224 module(L, "my_library")
230 // library-private declarations
234 As you might have figured out, the following declarations are equivalent::
238 namespace_("my_library")
247 module(L, "my_library")
252 Each declaration must be separated by a comma, like this::
259 .def(constructor<int, int>),
264 More about the actual declarations in the `Binding functions to lua`_ and
265 `Binding classes to lua`_ sections.
267 A word of caution, if you are in really bad need for performance, putting your
268 functions in tables will increase the lookup time.
271 Binding functions to lua
272 ========================
274 To bind functions to lua you use the function ``luabind::def()``. It has the
277 template<class F, class policies>
278 void def(const char* name, F f, const Policies&);
280 - name is the name the function will have within lua.
281 - F is the function pointer you want to register.
282 - The Policies parameter is used to describe how parameters and return values
283 are treated by the function, this is an optional parameter. More on this in
284 the `policies`_ section.
286 An example usage could be if you want to register the function ``float
291 def("sin", &std::sin)
297 If you have more than one function with the same name, and want to register
298 them in lua, you have to explicitly give the signature. This is to let C++ know
299 which function you refer to. For example, if you have two functions, ``int
300 f(const char*)`` and ``void f(int)``. ::
304 def("f", (int(*)(const char*)) &f),
305 def("f", (void(*)(int)) &f)
311 luabind will generate code that checks the lua stack to see if the values there
312 can match your functions' signatures. It will handle implicit typecasts between
313 derived classes, and it will prefer matches with the least number of implicit
314 casts. In a function call, if the function is overloaded and there's no
315 overload that match the parameters better than the other, you have an
316 ambiguity. This will spawn a run-time error, stating that the function call is
317 ambiguous. A simple example of this is to register one function that takes an
318 int and one that takes a float. Since lua don't distinguish between floats and
319 integers, both will always match.
321 Since all overloads are tested, it will always find the best match (not the
322 first match). This also means that it can handle situations where the only
323 difference in the signature is that one member function is const and the other
326 .. sidebar:: Ownership transfer
328 To correctly handle ownership transfer, create_a() would need an adopt
329 return value policy. More on this in the `Policies`_ section.
331 For example, if the following function and class is registered:
349 And the following lua code is executed::
352 a1:f() -- the const version is called
355 a2:f() -- the non-const version is called
366 Calling lua functions
367 ---------------------
369 To call a lua function, you can either use ``call_function()``,
370 ``call_member()``, an ``object`` or ``functor``.
375 Ret call_function(lua_State* L, const char* name, ...)
377 This calls the global function called name. This function can only call global
378 lua functions. The ... represents a variable number of parameters that are sent
379 to the lua function. This function call may throw ``luabind::error`` if the
382 The return value isn't actually Ret (the template parameter), but a proxy
383 object that will do the function call. This enables you to give policies to the
384 call. You do this with the operator[]. You give the policies within the
385 brackets, like this::
387 int ret = call_function<int>(
390 , new complex_class()
396 Ret call_member(object&, const char* name, ...)
398 This treats the given object as an instance of a class. The given name is the
399 name of a member function to call. The ... represents a variable number of
400 parameters given to the function. This function may throw ``luabind::error`` if
401 the function call fails.
403 You can give policies to a member function call the same way as you do with
407 Binding classes to lua
408 ======================
410 To register classes you use a class called ``class_``. Its name is supposed to
411 resemble the C++ keyword, to make it look more intuitive. It has an overloaded
412 member function ``def()`` that is used to register member functions, operators,
413 constructors, enums and properties on the class. It will return its
414 this-pointer, to let you register more members directly.
416 Let's start with a simple example. Consider the following C++ class::
421 testclass(const std::string& s): m_string(s) {}
422 void print_string() { std::cout << m_string << "\n"; }
425 std::string m_string;
428 To register it with a lua environment, write as follows (assuming you are using
433 class_<testclass>("testclass")
434 .def(constructor<const std::string&>())
435 .def("print_string", &testclass::print_string)
438 This will register the class with the name testclass and constructor that takes
439 a string as argument and one member function with the name ``print_string``.
443 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
444 > a = testclass('a string')
448 It is also possible to register free functions as member functions. The
449 requirement on the function is that it takes a pointer, const pointer,
450 reference or const reference to the class type as the first parameter. The rest
451 of the parameters are the ones that are visible in lua, while the object
452 pointer is given as the first parameter. If we have the following C++ code::
459 int plus(A* o, int v) { return o->a + v; }
461 You can register ``plus()`` as if it was a member function of A like this::
466 ``plus()`` can now be called as a member function on A with one parameter, int.
467 If the object pointer parameter is const, the function will act as if it was a
468 const member function (it can be called on const objects).
474 To register a global data member with a class is easily done. Consider the
482 This class is registered like this::
487 .def_readwrite("a", &A::a)
490 This gives read and write access to the member variable ``A::a``. It is also
491 possible to register attributes with read-only access::
496 .def_readonly("a", &A::a)
499 You can also register getter and setter functions and make them look as if they
500 were a public data member. Consider the following class::
505 void set_a(int x) { a = x; }
506 int get_a() const { return a; }
512 It can be registered as if it had a public data member a like this::
515 .property("a", &A::get_a, &A::set_a)
517 This way the ``get_a()`` and ``set_a()`` functions will be called instead of
518 just writing to the data member. If you want to make it read only you can just
519 omit the last parameter.
525 If your class contains enumerated constants (enums), you can register them as
526 well to make them available in lua. Note that they will not be type safe, all
527 enums are integers in lua, and all functions that takes an enum, will accept
528 any integer. You register them like this::
536 value("my_2nd_enum", 7),
537 value("another_enum", 6)
541 In lua they are accessed like any data member, except that they are read-only
542 and reached on the class itself rather than on an instance of the class.
546 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
549 > print(A.another_enum)
556 The mechanism for registering operators on your class is pretty simple. You use
557 a global name ``luabind::self`` to refer to the class itself and then you just
558 write the operator expression inside the ``def()`` call. This class::
562 vec operator+(int s);
565 Is registered like this::
573 This will work regardless if your plus operator is defined inside your class or
576 If you operator is const (or, when defined as a free function, takes a const
577 reference to the class itself) you have to use ``const_self`` instead of
578 ``self``. Like this::
583 .def(const_self + int())
586 The operators supported are those available in lua:
595 This means, no in-place operators. The equality operator (==) has a little
596 hatch, it will not be called if the references are equal. This means that the
597 == operator has to do pretty much what's it's expected to do.
599 In the above example the other operand type is instantiated by writing
600 ``int()``. If the operand type is a complex type that cannot easily be
601 instantiated you can wrap the type in a class called ``other<>``. For example:
603 To register this class, we don't want to instantiate a string just to register
610 vec operator+(std::string);
613 Instead we use the other ``wrapper`` like this::
618 .def(self + other<std::string>())
621 To register an application operator::
629 There's one special operator. In lua it's called ``__tostring``, it's not
630 really an operator. It is used for converting objects to strings in a standard
631 way in lua. If you register this functionality, you will be able to use the lua
632 standard function ``tostring()`` for converting you object to a string.
634 To implement this operator in C++ you should supply an ``operator<<`` for
635 ostream. Like this example::
638 std::ostream& operator<<(std::ostream&, number&);
644 class_<number>("number")
649 Nested scopes and static functions
650 ----------------------------------
652 It is possible to add nested scopes to a class. This is useful when you need
653 to wrap a nested class, or a static function. ::
660 class_<inner>("nested"),
664 It's also possible to add namespaces to classes using the same syntax.
670 If you want to register classes that derives from other classes, you can
671 specify a template parameter ``bases<>`` to the ``class_`` instantiation. The
672 following hierarchy::
677 Would be registered like this::
685 If you have multiple inheritance you can specify more than one base. If B would
686 also derive from a class C, it would be registered like this::
690 class_<B, bases<A, C> >("B")
693 Note that you can omit ``bases<>`` when using single inheritance.
696 If you don't specify that classes derive from each other, luabind will not
697 be able to implicitly cast pointers between the types.
703 When you register a class you can tell luabind that all instances of that class
704 should be held by some kind of smart pointer (boost::shared_ptr for instance).
705 You do this by giving the holder type as an extra template parameter to
706 the``class_``your constructing, like this::
710 class_<A, boost::shared_ptr<A> >("A")
713 You also have to supply two functions for your smart pointer. One that returns
714 the type of const version of the smart pointer type (boost::shared_ptr<const A>
715 in this case). And one function that extracts the raw pointer from the smart
716 pointer. The first function is needed because luabind has to allow the
717 non-const -> conversion when passing values from lua to C++. The second
718 function is needed when lua calls member functions on held types, the this
719 pointer must be a raw pointer, it is also needed to allow the smart_pointer ->
720 raw_pointer conversion from lua to C++. They look like this::
725 T* get_pointer(boost::shared_ptr<T>& p)
731 boost::shared_ptr<const A>*
732 get_const_holder(boost::shared_ptr<A>*)
738 The conversion that works are (given that B is a base class of A):
740 +----------------------------------------------+
742 +======================+=======================+
743 | holder_type<A> | A* |
744 +----------------------+-----------------------+
745 | holder_type<A> | A* |
746 +----------------------+-----------------------+
747 | holder_type<A> | const A* |
748 +----------------------+-----------------------+
749 | holder_type<A> | const B* |
750 +----------------------+-----------------------+
751 | holder_type<A> | holder_type<A> |
752 +----------------------+-----------------------+
753 | holder_type<A> | holder_type<const A> |
754 +----------------------+-----------------------+
755 | holder_type<const A> | const A* |
756 +----------------------+-----------------------+
757 | holder_type<const A> | const B* |
758 +----------------------+-----------------------+
759 | holder_type<const A> | holder_type<const A> |
760 +----------------------+-----------------------+
762 +-----------------------------------------------------+
764 +=============================+=======================+
765 | holder_type<A> | holder_type<A> |
766 +-----------------------------+-----------------------+
767 | holder_type<const A> | holder_type<const A> |
768 +-----------------------------+-----------------------+
769 | const holder_type<A>& | holder_type<A> |
770 +-----------------------------+-----------------------+
771 | const holder_type<const A>& | holder_type<const A> |
772 +-----------------------------+-----------------------+
774 When using a holder type, it can be useful to know if the pointer is valid. For
775 example when using std::auto_ptr, the holder will be invalidated when passed as
776 a parameter to a function. For this purpose there is a member of all object
777 instances in luabind: ``__ok``. ::
780 void f(std::auto_ptr<test>);
785 .def(constructor<>()),
792 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
802 Since functions have to be able to take lua values (of variable type) we need a
803 wrapper around them. This wrapper is called ``luabind::object``. If the
804 function you register takes an object, it will match any lua value. To use it,
805 you need to include ``luabind/object.hpp``. The object class has the following
813 class array_iterator;
816 object(lua_State*, const T& value);
817 object(const object&);
823 iterator begin() const;
824 iterator end() const;
825 raw_iterator raw_begin() const;
826 raw_iterator raw_end() const;
827 array_iterator abegin() const;
828 array_iterator aend() const;
831 lua_State* lua_state() const;
832 void pushvalue() const;
833 bool is_valid() const;
834 operator safe_bool_type() const;
837 <implementation-defined> operator[](const Key&);
840 object at(const Key&) const;
843 object raw_at(const Key&) const;
846 object& operator=(const T&);
847 object& operator=(const object&);
850 bool operator==(const T&) const;
851 bool operator==(const object&) const;
852 bool operator<(const object&) const;
853 bool operator<=(const object&) const;
854 bool operator>(const object&) const;
855 bool operator>=(const object&) const;
856 bool operator!=(const object&) const;
861 <implementation-defined> operator()();
864 <implementation-defined> operator()(const A0& a0);
866 template<class A0, class A1>
867 <implementation-defined> operator()(const A0& a0, const A1& a1);
873 When you have a lua object, you can assign it a new value with the assignment
874 operator (=). When you do this, the ``default_policy`` will be used to make the
875 conversion from C++ value to lua. If your ``luabind::object`` is a table you
876 can access its members through the operator[] or the iterators. The value
877 returned from the operator[] is a proxy object that can be used both for
878 reading and writing values into the table (using operator=). Note that it is
879 impossible to know if a lua value is indexable or not (lua_gettable doesn't
880 fail, it succeeds or crashes). This means that if you're trying to index
881 something that cannot be indexed, you're on your own. Lua will call its
882 ``panic()`` function (you can define your own panic function using
883 lua_setpanicf). The ``at()`` and ``raw_at()`` functions returns the value at
884 the given table position (like operator[] but only for reading).
886 The ordinary ``object::iterator`` uses lua_gettable to extract the values from
887 the table, the standard way that will invoke metamethods if any. The
888 ``object::raw_iterator`` uses lua_rawget and ``object::array_iterator`` uses
889 lua_rawgeti. The latter will only iterate over numberical keys starting at 1
890 and continue until the first nil value.
892 The ``lua_state()`` function returns the lua state where this object is stored.
893 If you want to manipulate the object with lua functions directly you can push
894 it onto the lua stack by calling ``pushvalue()``. And set the object's value by
895 calling ``set()``, which will pop the top value from the lua stack and assign
898 The operator== will call lua_equal() on the operands and return its result.
900 The ``type()`` member function will return the lua type of the object. It will
901 return the same values as lua_type().
903 The ``is_valid()`` function tells you whether the object has been initialized
904 or not. When created with its default constructor, objects are invalid. To make
905 an object valid, you can assign it a value. If you want to invalidate an object
906 you can simply assign it an invalid object.
908 .. So what? implementation detail, leave out of docs
909 isn't really an implicit cast to bool, but an implicit cast
910 to a member pointer, since member pointers don't have any arithmetic operators
911 on them (which can cause hard to find errors). The functionality of the cast
914 The ``operator safe_bool_type()`` is equivalent to ``is_valid()``. This means
915 that these snippets are equivalent::
933 The application operator will call the value as if it was a function. You can
934 give it any number of parameters (currently the ``default_policy`` will be used
935 for the conversion). The returned object refers to the return value (currently
936 only one return value is supported). This operator may throw ``luabind::error``
937 if the function call fails. If you want to specify policies to your function
938 call, you can use index-operator (operator[]) on the function call, and give
939 the policies within the [ and ]. Like this::
944 , new my_complex_structure(6)
947 This tells luabind to make lua adopt the ownership and responsibility for the
948 pointer passed in to the lua-function.
950 It's important that all instances of object have been destructed by the time
951 the lua state is closed. The object will keep a pointer to the lua state and
952 release its lua object in its destructor.
954 Here's an example of how a function can use a table::
956 void my_function(const object& table)
958 if (table.type() == LUA_TTABLE)
960 table["time"] = std::clock();
961 table["name"] = std::rand() < 500 ? "unusual" : "usual";
963 std::cout << object_cast<std::string>(table[5]) << "\n";
967 If you take a ``luabind::object`` as a parameter to a function, any lua value
968 will match that parameter. That's why we have to make sure it's a table before
975 The iterators, that are returned by ``begin() and ``end()`` (and their
976 variants) are (almost) models of the ForwardIterator concept. The exception
977 is that post increment doesn't exist on them.
979 They look like this::
981 class object::iterator
984 iterator(const iterator&);
986 iterator& operator++();
987 bool operator!=(const iterator&) const;
988 iterator& operator=(const iterator&);
992 implementation-defined operator*();
995 The implementation defined return value from the dereference operator is a
996 proxy object that can be used as if it was an object, it can also be used to
997 assign the specific table entry with a new value. If you want to assign a value
998 to an entry pointed to by an iterator, just use the assignment operator on the
999 dereferenced iterator::
1003 The ``key()`` member returns the key used by the iterator when indexing the
1004 associated lua table.
1010 There are a couple of functions related to objects and tables. ::
1012 T object_cast<T>(const object&);
1013 T object_cast<T>(const object&, const Policies&);
1016 object_cast_nothrow<T>(const object&);
1019 object_cast_nothrow<T>(const object&, const Policies&);
1025 The ``functor`` class is similar to object, with the exception that it can only
1026 be used to store functions. If you take it as a parameter, it will only match
1029 To use it you need to include its header::
1031 #include <luabind/functor.hpp>
1033 It takes one template parameter, the return value of the lua function it
1034 represents. Currently the functor can have at most one return value (unlike lua
1035 functions). It has the following synopsis::
1042 functor(lua_State*, const char* name);
1043 functor(const functor&);
1047 bool is_valid() const;
1048 operator safe_bool_type() const;
1050 lua_State* lua_state() const;
1051 void pushvalue() const;
1053 bool operator==(const functor<Ret>&);
1054 bool operator!=(const functor<Ret>&);
1056 <implementation-defined> operator()() const;
1059 <implementation-defined> operator()(const A0&) const;
1061 template<class A0, class A1>
1062 <implementation-defined> operator()(const A0&, const A1&) const;
1067 The application operator takes any parameters. The parameters are converted
1068 into lua and the function is called. The return value will act as if it was the
1069 type Ret, with the exception that you can use the return value to give policies
1070 to the call. You do this the same way as you do with objects, using the
1071 operator[], and giving the policies inside the brackets.
1073 The ``is_valid()`` function works just like the one on object, it tells you if
1074 the functor has been assigned with a valid lua function. The ``operator
1075 safe_bool_type()`` is an alias for this member function and also works just as
1076 the one found in object.
1078 For example, if you have the following lua function::
1084 You can expose it to C++ like this::
1086 functor<int> f(L, "f");
1088 std::cout << f(3, 5) << "\n";
1090 This will print out the sum of 3 and 5. Note that you can pass any parameters
1091 to the application operator of ``luabind::functor``, this is because lua
1092 doesn't have signatures for its functions. All lua functions take any number of
1093 parameters of any type.
1095 If we have a C++ function that takes a ``luabind::functor`` and registers it,
1096 it will accept lua functions passed to it. This enables us to expose APIs that
1097 requires you to register callbacks. For example, if your C++ API looks like
1100 void set_callback(void(*)(int, int));
1102 And you want to expose it to lua, you have to wrap the call to the lua
1103 function inside a real C++ function, like this::
1105 functor<void> lua_callback;
1107 void callback_wrapper(int a, int b)
1112 void set_callback_wrapper(const functor<void>& f)
1115 set_callback(&callback_wrapper);
1118 And then register ``set_callback_wrapper`` instead of registering
1119 ``set_callback``. This will have the effect that when one tries to register the
1120 callback from lua, your ``set_callback_wrapper`` will be called instead and
1121 first set the lua functor to the given function. It will then call the real
1122 ``set_callback`` with the ``callback_wrapper``. The ``callback_wrapper`` will
1123 be called whenever the callback should be called, and it will simply call the
1124 lua function that we registered.
1126 You can also use ``object_cast`` to cast an object to a functor.
1129 Defining classes in lua
1130 =======================
1132 In addition to binding C++ functions and classes with lua, luabind also provide
1133 an OO-system in lua. ::
1135 class 'lua_testclass'
1137 function lua_testclass:__init(name)
1141 function lua_testclass:print()
1145 a = lua_testclass('example')
1149 Inheritance can be used between lua-classes::
1151 class 'derived' (lua_testclass)
1153 function derived:__init() super('derived name')
1156 function derived:print()
1157 print('Derived:print() -> ')
1158 lua_testclass.print(self)
1161 Here the ``super`` keyword is used in the constructor to initialize the base
1162 class. The user is required to call ``super`` first in the constructor.
1164 As you can see in this example, you can call the base class member functions.
1165 You can find all member functions in the base class, but you will have to give
1166 the this-pointer (``self``) as first argument.
1172 It is also possible to derive lua classes from C++ classes, and override
1173 virtual functions with lua functions. To do this we have to create a wrapper
1174 class for our C++ base class. This is the class that will hold the lua object
1175 when we instantiate a lua class.
1177 The wrapper class has to provide the same constructors as the base class, with
1178 the addition of one extra parameter: ``luabind::object``. This is the reference
1179 to the lua object that should be held by the wrapper, and should be stored in a
1180 member variable as done in the sample below. ::
1186 { std::cout << s << "\n"; }
1188 virtual void f(int a)
1189 { std::cout << "f(" << a << ")\n"; }
1192 struct base_wrapper : base
1195 base_wrapper(object self_, const char* s)
1196 : base(s), self(self_)
1199 virtual void f(int a)
1201 call_member<void>(self, "f", a);
1204 static void f_static(base* ptr, int a)
1206 return ptr->base::f(a);
1214 class_<base, base_wrapper>("base")
1215 .def(constructor<const char*>())
1216 .def("f", &base_wrapper::f_static)
1219 Note that if you have both base classes and a base class wrapper, you must give
1220 both bases and the base class wrapper type as template parameter to
1221 ´´class_´´. The order in which you specify them is not important.
1223 If we didn't have a class wrapper, it would not be possible to pass a lua class
1224 back to C++. Since the entry points of the virtual functions would still point
1225 to the C++ base class, and not to the functions defined in lua. That's why we
1226 need one function that calls the base class' real function (used if the lua
1227 class doesn't redefine it) and one virtual function that dispatches the call
1228 into luabind, to allow it to select if a lua function should be called, or if
1229 the original function should be called. If you don't intend to derive from a
1230 C++ class, or if it doesn't have any virtual member functions, you can register
1231 it without a class wrapper.
1233 You don't need to have a class wrapper in order to derive from a class, but if
1234 it has virtual functions you may have silent errors.
1236 .. Unnecessary? The rule of thumb is:
1237 If your class has virtual functions, create a wrapper type, if it doesn't
1238 don't create a wrapper type.
1241 Overloading operators
1242 ---------------------
1244 You can overload most operators in lua for your classes. You do this by simply
1245 declaring a member function with the same name as an operator (the name of the
1246 metamethods in lua). The operators you can overload are:
1260 ``__tostring`` isn't really an operator, but it's the metamethod that is called
1261 by the standard library's ``tostring()`` function. There's one strange behavior
1262 regarding binary operators. You are not guaranteed that the self pointer you
1263 get actually refers to an instance of your class. This is because lua doesn't
1264 distinguish the two cases where you get the other operand as left hand value or
1265 right hand value. Consider the following examples::
1269 function my_class:__init(v)
1273 function my_class:__sub(v)
1274 return my_class(self.val - v.val)
1277 function my_class:__tostring()
1281 This will work well as long as you only subtracts instances of my_class with
1282 each other. But If you want to be able to subtract ordinary numbers from your
1283 class too, you have to manually check the type of both operands, including the
1286 function my_class:__sub(v)
1287 if (type(self) == 'number') then
1288 return my_class(self - v.val)
1290 elseif (type(v) == 'number') then
1291 return my_class(self.val - v)
1294 -- assume both operands are instances of my_class
1295 return my_class(self.val - v.val)
1300 The reason why ``__sub`` is used as an example is because subtraction is not
1301 commutative (the order of the operands matter). That's why luabind cannot
1302 change order of the operands to make the self reference always refer to the
1303 actual class instance.
1305 If you have two different lua classes with an overloaded operator, the operator
1306 of the right hand side type will be called. If the other operand is a C++ class
1307 with the same operator overloaded, it will be prioritized over the lua class'
1308 operator. If none of the C++ overloads matches, the lua class operator will be
1315 If an object needs to perform actions when it's collected we provide a
1316 ``__finalize`` function that can be overridden in lua-classes. The
1317 ``__finalize`` functions will be called on all classes in the inheritance
1318 chain, starting with the most derived type. ::
1322 function lua_testclass:__finalize()
1323 -- called when the an object is collected
1330 If any of the functions you register throws an exception when called, that
1331 exception will be caught by luabind and converted to an error string and
1332 ``lua_error()`` will be invoked. If the exception is a ``std::exception`` or a
1333 ``const char*`` the string that is pushed on the lua stack, as error message,
1334 will be the string returned by ``std::exception::what()`` or the string itself
1335 respectively. If the exception is unknown, a generic string saying that the
1336 function threw an exception will be pushed.
1338 Exceptions thrown from user defined functions have to be caught by luabind. If
1339 they weren't they would be thrown through lua itself, which is usually compiled
1340 as C code and doesn't support the stack-unwinding that exceptions imply.
1342 Any function that invokes lua code may throw ``luabind::error``. This exception
1343 means that a lua run-time error occurred. The error message is found on top of
1344 the lua stack. The reason why the exception doesn't contain the error string
1345 itself is because it would then require heap allocation which may fail. If an
1346 exception class throws an exception while it is being thrown itself, the
1347 application will be terminated.
1349 Error's synopsis is::
1351 class error : public std::exception
1355 lua_State* state() const throw();
1356 virtual const char* what() const throw();
1359 The state function returns a pointer to the lua state in which the error was
1360 thrown. This pointer may be invalid if you catch this exception after the lua
1361 state is destructed. If the lua state is valid you can use it to retrieve the
1362 error message from the top of the lua stack.
1364 An example of where the lua state pointer may point to an invalid state
1369 lua_state(lua_State* L): m_L(L) {}
1370 ~lua_state() { lua_close(m_L); }
1371 operator lua_State*() { return m_L; }
1379 lua_state L = lua_open();
1382 catch(luabind::error& e)
1384 lua_State* L = e.state();
1385 // L will now point to the destructed
1386 // lua state and be invalid
1391 There's another exception that luabind may throw: ``luabind::cast_failed``,
1392 this exception is thrown from ``call_function<>``, ``call_member<>`` or when
1393 ``functor<>`` is invoked. It means that the return value from the lua function
1394 couldn't be converted to a C++ value. It is also thrown from ``object_cast<>``
1395 if the cast cannot be made.
1397 The synopsis for ``luabind::cast_failed`` is::
1399 class cast_failed : public std::exception
1402 cast_failed(lua_State*);
1403 lua_State* state() const throw();
1404 LUABIND_TYPE_INFO info() const throw();
1405 virtual const char* what() const throw();
1408 Again, the state member function returns a pointer to the lua state where the
1409 error occurred. See the example above to see where this pointer may be invalid.
1411 The info member function returns the user defined ``LUABIND_TYPE_INFO``, which
1412 defaults to a ``const std::type_info*``. This type info describes the type that
1413 we tried to cast a lua value to.
1415 If you have defined ``LUABIND_NO_EXCEPTIONS`` none of these exceptions will be
1416 thrown, instead you can set two callback functions that are called instead.
1417 These two functions are only defined if ``LUABIND_NO_EXCEPTIONS`` are defined.
1421 luabind::set_error_callback(void(*)(lua_State*))
1423 The function you set will be called when a runtime-error occur in lua code. You
1424 can find an error message on top of the lua stack. This function is not
1425 expected to return, if it does luabind will call ``std::terminate()``.
1429 luabind::set_cast_failed_callback(void(*)(lua_State*, LUABIND_TYPE_INFO))
1431 The function you set is called instead of throwing ``cast_failed``. This function
1432 is not expected to return, if it does luabind will call ``std::terminate()``.
1438 Sometimes it is necessary to control how luabind passes arguments and return
1439 value, to do this we have policies. These are the policies that can be used:
1444 This will make a copy of the parameter. This is the default behavior when
1445 passing parameters by-value. Note that this can only be used when passing from
1446 C++ to lua. This policy requires that the parameter type has a copy
1449 To use this policy you need to include ``luabind/copy_policy.hpp``.
1455 This will transfer ownership of the parameter.
1457 Consider making a factory function in C++ and exposing it to lua::
1468 def("create_base", create_base)
1471 Here we need to make sure lua understands that it should adopt the pointer
1472 returned by the factory-function. This can be done using the adopt-policy.
1478 def(L, "create_base", adopt(return_value))
1481 To specify multiple policies we just separate them with '+'.
1485 base* set_and_get_new(base* ptr)
1487 base_ptrs.push_back(ptr);
1493 def("set_and_get_new", &set_and_get_new,
1494 adopt(return_value) + adopt(_1))
1497 When lua adopts a pointer, it will call delete on it. This means that it cannot
1498 adopt pointers allocated with another allocator than new (no malloc for
1501 To use this policy you need to include ``luabind/adopt_policy.hpp``.
1507 The dependency policy is used to create life-time dependencies between values.
1508 Consider the following example::
1514 const B& get_member()
1520 When wrapping this class, we would do something like::
1525 .def(constructor<>())
1526 .def("get_member", &A::get_member)
1530 However, since the return value of get_member is a reference to a member of A,
1531 this will create some life-time issues. For example::
1533 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1535 b = a:get_member() -- b points to a member of a
1537 collectgarbage(0) -- since there are no references left to a, it is
1539 -- at this point, b is pointing into a removed object
1541 When using the dependency-policy, it is possible to tell luabind to tie the
1542 lifetime of one object to another, like this::
1547 .def(constructor<>())
1548 .def("get_member", &A::get_member, dependency(result, self))
1551 This will create a dependency between the return-value of the function, and the
1552 self-object. This means that the self-object will be kept alive as long as the
1553 result is still alive. ::
1555 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1557 b = a:get_member() -- b points to a member of a
1559 collectgarbage(0) -- a is dependent on b, so it isn't removed
1561 collectgarbage(0) -- all dependencies to a gone, a is removed
1563 To use this policy you need to include ``luabind/dependency_policy.hpp``.
1569 It is very common to return references to arguments or the this-pointer to
1570 allow for chaining in C++.
1585 When luabind generates code for this, it will create a new object for the
1586 return-value, pointing to the self-object. This isn't a problem, but could be a
1587 bit inefficient. When using the return_reference_to-policy we have the ability
1588 to tell luabind that the return-value is already on the lua stack.
1595 .def(constructor<>())
1596 .def("set", &A::set, return_reference_to(self))
1599 Instead of creating a new object, luabind will just copy the object that is
1600 already on the stack.
1603 This policy ignores all type information and should be used only it
1604 situations where the parameter type is a perfect match to the
1605 return-type (such as in the example).
1607 To use this policy you need to include ``luabind/return_reference_to_policy.hpp``.
1613 This policy makes it possible to wrap functions that take non const references
1614 as its parameters with the intention to write return values to them.
1618 void f(float& val) { val = val + 10.f; }
1624 void f(float* val) { *val = *val + 10.f; }
1626 Can be wrapped by doing::
1630 def("f", &f, out_value(_1))
1633 When invoking this function from lua it will return the value assigned to its
1638 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1643 When this policy is used in conjunction with user define types we often need
1644 to do ownership transfers.
1650 void f1(A*& obj) { obj = new A(); }
1651 void f2(A** obj) { *obj = new A(); }
1653 Here we need to make sure luabind takes control over object returned, for
1654 this we use the adopt policy::
1659 def("f1", &f1, out_value(_1, adopt(_2)))
1660 def("f2", &f2, out_value(_1, adopt(_2)))
1663 Here we are using adopt as an internal policy to out_value. The index
1664 specified, _2, means adopt will be used to convert the value back to lua.
1665 Using _1 means the policy will be used when converting from lua to C++.
1667 To use this policy you need to include ``luabind/out_value_policy.hpp``.
1672 This policy works in exactly the same way as out_value, except that it
1673 replaces the parameters with default-constructed objects.
1677 void get(float& x, float& y)
1688 pure_out_value(_1) + pure_out_value(_2))
1693 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1698 Like out_value, it is possible to specify an internal policy used then
1699 converting the values back to lua.
1703 void get(test_class*& obj)
1705 obj = new test_class();
1712 def("get", &get, pure_out_value(_1, adopt(_1)))
1719 This is a very simple policy which makes it possible to throw away
1720 the value returned by a C++ function, instead of converting it to
1721 lua. This example makes sure the this reference never gets converted
1728 simple& set_name(const std::string& n)
1741 class_<simple>("simple")
1742 .def("set_name", &simple::set_name, discard_result)
1745 To use this policy you need to include ``luabind/discard_result_policy.hpp``.
1751 This policy converts an STL container to a generator function that can be used
1752 in lua to iterate over the container. It works on any container that defines
1753 ``begin()`` and ``end()`` member functions (they have to return iterators). It
1754 can be used like this::
1758 std::vector<std::string> names;
1765 .def_readwrite("names", &A::names, return_stl_iterator)
1768 The lua code to iterate over the container::
1772 for name in a.names do
1777 To use this policy you need to include ``luabind/iterator_policy.hpp``.
1783 This policy will cause the function to always yield the current thread when
1784 returning. See the lua manual for restrictions on yield.
1787 Splitting up the registration
1788 =============================
1792 luabind::scope register_a()
1802 luabind::scope register_b()
1812 luabind::scope register_a();
1813 luabind::scope register_b();
1815 void register_module(lua_State* L)
1828 There are a number of configuration options available when building luabind.
1829 It is very important that your project has the exact same conmfiguration
1830 options as the ones given when the library was build! The exceptions are the
1831 ``LUABIND_MAX_ARITY`` and ``LUABIND_MAX_BASES`` which are template-based
1832 options and only matters when you use the library (which means they can
1833 differ from the settings of the library).
1835 The default settings which will be used if no other settings are given
1836 can be found in ``luabind/config.hpp``.
1838 If you want to change the settings of the library, you can modify the
1839 config file. It is included and used by all makefiles. You can change paths
1840 to lua and boost in there as well.
1843 Controls the maximum arity of functions that are registered with luabind.
1844 You can't register functions that takes more parameters than the number
1845 this macro is set to. It defaults to 5, so, if your functions have greater
1846 arity you have to redefine it. A high limit will increase compilation time.
1849 Controls the maximum number of classes one class can derive from in
1850 luabind (the number of classes specified within ``bases<>``).
1851 ``LUABIND_MAX_BASES`` defaults to 4. A high limit will increase
1854 LUABIND_NO_ERROR_CHECKING
1855 If this macro is defined, all the lua code is expected only to make legal
1856 calls. If illegal function calls are made (e.g. giving parameters that
1857 doesn't match the function signature) they will not be detected by luabind
1858 and the application will probably crash. Error checking could be disabled
1859 when shipping a release build (given that no end-user has access to write
1860 custom lua code). Note that function parameter matching will be done if a
1861 function is overloaded, since otherwise it's impossible to know which one
1862 was called. Functions will still be able to throw exceptions when error
1863 checking is disabled.
1865 If a functions throws an exception it will be caught by luabind and
1866 propagated with ``lua_error()``.
1868 LUABIND_DONT_COPY_STRINGS
1869 If this macro is defined, luabind will expect that all strings given to
1870 the ``def()`` functions are static constant strings (given as string
1871 constants for example). luabind will not copy the strings if you enable
1872 this setting, but just keep the char pointers.
1873 This may be especially useful for embedded systems or consoles where
1874 heap allocations should be minimized.
1876 LUABIND_NO_EXCEPTIONS
1877 This define will disable all usage of try, catch and throw in luabind.
1878 This will in many cases disable run-time errors, when performing invalid
1879 casts or calling lua functions that fails or returns values that cannot
1880 be converted by the given policy. luabind requires that no function called
1881 directly or indirectly by luabind throws an exception (throwing exceptions
1882 through lua has undefined behavior).
1884 Where exceptions are the only way to get an error report from luabind,
1885 they will be replaced with calls to the callback functions set with
1886 ``set_error_callback()`` and ``set_cast_failed_callback()``.
1889 If you want to link dynamically against lua, you can set this define to
1890 the import-keyword on your compiler and platform. On windows in devstudio
1891 this should be ``__declspec(dllimport)`` if you want to link against lua
1894 LUABIND_EXPORT, LUABIND_IMPORT
1895 If you want to link against luabind as a dll (in devstudio), you can
1896 define ``LUABIND_EXPORT`` to ``__declspec(dllexport)`` and
1897 ``LUABIND_IMPORT`` to ``__declspec(dllimport)``.
1898 Note that you have to link against lua as a dll aswell, to make it work.
1900 LUABIND_TYPE_INFO, LUABIND_TYPE_INFO_EQUAL(i1,i2), LUABIND_TYPEID(t), LUABIND_INVALID_TYPE_INFO
1901 If you don't want to use the RTTI supplied by C++ you can supply your own
1902 type-info structure with the ``LUABIND_TYPE_INFO`` define. Your type-info
1903 structure must be copyable and must be able to compare itself against
1904 other type-info structures. You supply the compare function through the
1905 ``LUABIND_TYPE_INFO_EQUAL()`` define. It should compare the two type-info
1906 structures it is given and return true if they represent the same type and
1907 false otherwise. You also have to supply a function to generate your
1908 type-info structure. You do this through the ``LUABIND_TYPEID()`` define.
1909 It should return your type-info structure and it takes a type as its
1910 parameter. That is, a compile time parameter.
1911 ``LUABIND_INVALID_TYPE_INFO`` macro should be defined to an invalid type.
1912 No other type should be able to produce this type info. To use it you
1913 probably have to make a traits class with specializations for all classes
1914 that you have type-info for. Like this::
1920 template<class T> struct typeinfo_trait;
1922 template<> struct typeinfo_trait<A> { enum { type_id = 0 }; };
1923 template<> struct typeinfo_trait<B> { enum { type_id = 1 }; };
1924 template<> struct typeinfo_trait<C> { enum { type_id = 2 }; };
1926 If you have set up your own RTTI system like this (by using integers to
1927 identify types) you can have luabind use it with the following defines::
1929 #define LUABIND_TYPE_INFO const std::type_info*
1930 #define LUABIND_TYPEID(t) &typeid(t)
1931 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
1932 #define LUABIND_INVALID_TYPE_INFO &typeid(detail::null_type)
1934 Currently the type given through ``LUABIND_TYPE_INFO`` must be less-than
1938 This define will disable all asserts and should be defined in a release
1942 Implementation notes
1943 ====================
1945 The classes and objects are implemented as user data in lua. To make sure that
1946 the user data really is the internal structure it is supposed to be, we tag
1947 their metatables. A user data who's metatable contains a boolean member named
1948 ``__luabind_classrep`` is expected to be a class exported by luabind. A user
1949 data who's metatable contains a boolean member named ``__luabind_class`` is
1950 expected to be an instantiation of a luabind class.
1952 This means that if you make your own user data and tags its metatable with the
1953 exact same names, you can very easily fool luabind and crash the application.
1955 In the lua registry, luabind keeps an entry called ``__luabind_classes``. It
1956 should not be removed or overwritten.
1958 In the global table, a variable called ``super`` is used every time a
1959 constructor in a lua-class is called. This is to make it easy for that
1960 constructor to call its base class' constructor. So, if you have a global
1961 variable named super it may very well be overwritten. This is probably not the
1962 best solution, and this restriction may very well be removed in the future.
1964 Luabind uses two upvalues for functions that it registers. The first is a
1965 userdata containing a list of overloads for the function, the other is a light
1966 userdata with the value 0x1337, this last value is used to identify functions
1967 registered by luabind. It should be virtually impossible to have such a pointer
1968 as secondary upvalue by pure chance. This means, if you are trying to replace
1969 an existing function with a luabind function, luabind will see that the
1970 secondary upvalue isn't the magic id number and replace it. If it can identify
1971 the function to be a luabind function, it won't replace it, but rather add
1972 another overload to it.
1974 Inside the luabind namespace, there's another namespace called detail. This
1975 namespace contains non-public classes and are not supposed to be used directly.
1981 - `the attribute '<class-name>.<attribute-name>' is read only`
1983 There is no data member named <attribute-name> in the class <class-name>,
1984 or there's no setter-method registered on that property name. See the
1987 - `the attribute '<class-name>.<attribute-name>' is of type: (<class-name>)
1988 and does not match (<class_name>)`
1990 This error is generated if you try to assign an attribute with a value
1991 of a type that cannot be converted to the attribute's type.
1993 - `<class-name>() threw an exception, <class-name>:<function-name>() threw an
1996 The class' constructor or member function threw an unknown exception.
1997 Known exceptions are const char*, std::exception. See the
1998 `exceptions`_ section.
2000 - `no overload of '<class-name>:<function-name>' matched the arguments
2001 (<parameter-types>)`
2002 - `no match for function call '<function-name>' with the parameters
2003 (<parameter-types>)`
2004 - `no constructor of <class-name> matched the arguments (<parameter-types>)`
2005 - `no operator <operator-name> matched the arguments (<parameter-types>)`
2007 No function/operator with the given name takes the parameters you gave
2008 it. You have either misspelled the function name, or given it incorrect
2009 parameters. This error is followed by a list of possible candidate
2010 functions to help you figure out what parameter has the wrong type. If
2011 the candidate list is empty there's no function at all with that name.
2012 See the signature matching section.
2014 - `call of overloaded '<class-name>:<function-name>(<parameter-types>)' is
2016 - `ambiguous match for function call '<function-name>' with the parameters
2017 (<parameter-types>)`
2018 - `call of overloaded constructor '<class-name>(<parameter-types>)' is
2020 - `call of overloaded operator <operator-name> (<parameter-types>) is
2023 This means that the function/operator you are trying to call has at least
2024 one other overload that matches the arguments just as good as the first
2027 - `cannot derive from C++ class '<class-name>'. It does not have a wrapped
2030 You are trying to derive a lua class from a C++ class that doesn't have a
2031 wrapped type. You have to give your C++ class a wrapped type when you
2032 register it with lua. See the deriving in lua section.
2034 - `derived class must call super on base`
2035 - `cannot set property '<class-name>.<attribute_name>' because it's read only`
2037 The attribute you are trying to set is registered as read only. If you want
2038 it to be writeable you have to change your class registration and use
2039 def_readwrite() instead of def_readonly(). Alternatively (if your
2040 attribute is a property with getter and setter functions), you have to
2041 give a setter function when declaring your attribute. See the properties section.
2043 - `no static '<enum-name>' in class '<class-name>'`
2045 You will get this error message if you are trying to access an enum that
2046 doesn't exist. Read about how to declare enums.
2048 - `expected base class`
2050 You have written a malformed class definition in lua. The format is: class
2051 '<class-name>' [<base-class>]. If you don't want to derive from a base
2052 class, you have to break the line directly after the class declaration.
2054 - `invalid construct, expected class name`
2056 You have written a malformed class definition in lua. The class function
2057 expects a string as argument. That string is the name of the lua class to
2064 What's up with __cdecl and __stdcall?
2065 If you're having problem with functions
2066 that cannot be converted from 'void (__stdcall *)(int,int)' to 'void
2067 (__cdecl*)(int,int)'. You can change the project settings to make the
2068 compiler generate functions with __cdecl calling conventions. This is
2069 a problem in developer studio.
2071 What's wrong with functions taking variable number of arguments?
2072 You cannot register a function with ellipses in its signature. Since
2073 ellipses don't preserve type safety, those should be avoided anyway.
2075 Internal structure overflow in VC
2076 If you, in visual studio, get fatal error C1204: compiler limit :
2077 internal structure overflow. You should try to split that compilation
2078 unit up in smaller ones.
2080 What's wrong with precompiled headers in VC?
2081 Visual Studio doesn't like anonymous namespaces in its precompiled
2082 headers. If you encounter this problem you can disable precompiled
2083 headers for the compilation unit (cpp-file) that uses luabind.
2085 error C1076: compiler limit - internal heap limit reached in VC
2086 In visual studio you will probably hit this error. To fix it you have to
2087 increase the internal heap with a command-line option. We managed to
2088 compile the test suit with /Zm300, but you may need a larger heap then
2091 error C1055: compiler limit : out of keys in VC
2092 It seems that this error occurs when too many assert() are used in a
2093 program, or more specifically, the __LINE__ macro. It seems to be fixed by
2094 changing /ZI (Program database for edit and continue) to /Zi
2097 How come my executable is huge?
2098 If you're compiling in debug mode, you will probably have a lot of
2099 debug-info and symbols (luabind consists of a lot of functions). Also,
2100 if built in debug mode, no optimizations were applied, luabind relies on
2101 that the compiler is able to inline functions. If you built in release
2102 mode, try running strip on your executable to remove export-symbols,
2103 this will trim down the size.
2105 Our tests suggests that cygwin's gcc produces much bigger executables
2106 compared to gcc on other platforms and other compilers.
2108 .. HUH?! // check the magic number that identifies luabind's functions
2110 Can I register class templates with luabind?
2111 Yes you can, but you can only register explicit instantiations of the
2112 class. Because there's no lua counterpart to C++ templates. For example,
2113 you can register an explicit instantiation of std::vector<> like this::
2117 class_<std::vector<int> >("vector")
2118 .def(constructor<int>)
2119 .def("push_back", &std::vector<int>::push_back)
2122 .. Again, irrelevant to docs: Note that the space between the two > is required by C++.
2124 Do I have to register destructors for my classes?
2125 No, the destructor of a class is always called by luabind when an
2126 object is collected. Note that lua has to own the object to collect it.
2127 If you pass it to C++ and gives up ownership (with adopt policy) it will
2128 no longer be owned by lua, and not collected.
2130 If you have a class hierarchy, you should make the destructor virtual if
2131 you want to be sure that the correct destructor is called (this apply to C++
2134 .. And again, the above is irrelevant to docs. This isn't a general C++ FAQ.
2136 Fatal Error C1063 compiler limit : compiler stack overflow in VC
2137 VC6.5 chokes on warnings, if you are getting alot of warnings from your
2138 code try suppressing them with a pragma directive, this should solve the
2141 Crashes when linking against luabind as a dll in windows
2142 When you build luabind, lua and you project, make sure you link against
2143 the runtime dynamically (as a dll).
2145 I cannot register a function with a non-const parameter
2146 This is because there is no way to get a reference to a lua value. Have
2147 a look at out_value and pure_out_value policies.
2153 - You cannot use strings with extra nulls in them as member names that refers
2156 - If one class registers two functions with the same name and the same
2157 signature, there's currently no error. The last registered function will
2158 be the one that's used.
2160 - In vc7, classes can not be called test.
2162 .. remove? - Visual studio have problems selecting the correct overload of std::swap()
2163 for luabind::object.
2165 - If you register a function and later rename it, error messages will use the
2166 original function name.
2172 This library was written by Daniel Wallin and Arvid Norberg. © Copyright 2003.
2173 All rights reserved.
2175 This library was inspired by Dave Abrahams' Boost.Python library which can be
2176 found in the boost_ library.
2178 Evan Wies has contributed with thorough testing and countless bug reports and