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
125 To keep down the compilation-time luabind is built as a library. This means you
126 have to either build it and link against it, or include its source files in
127 your project. You also have to make sure the luabind directory is somewhere in
128 your compiler's include path. It requires `Boost`_ 1.32.0 or 1.33.0 to be
129 installed (only boost headers). It also requires that Lua is installed.
131 The official way of building luabind is with `Boost.Build V2`_. To properly build
132 luabind with Boost.Build you need to set two environment variables:
135 Point this to your Boost installation.
138 Point this to your Lua directory. The build system will assume that the
139 include and library files are located in ``$(LUA_PATH)/include/`` and
140 ``$(LUA_PATH)/lib/.``. If this environment variable is not defined, the
141 Jamfile will try to invoke ``pkg-config`` in order to find lua. It will
142 look for lua 5.1 (``lua5.1`` as the package is called on debian systems).
144 For backward compatibility, there is also a makefile in the root-directory that
145 will build the library and the test programs. If you are using a UNIX-system (or
146 cygwin) they will make it easy to build luabind as a static library. If you are
147 using Visual Studio it may be easier to include the files in the src directory
150 When building luabind you have several options that may streamline the library
151 to better suit your needs. It is extremely important that your application has
152 the same settings as the library was built with. The available options are
153 found in the `Build options`_ section.
155 If you want to change the settings to differ from the default, it's recommended
156 that you define the settings on the command line of all your files (in the
157 project settings in visual studio).
159 .. _`Boost.Build V2`: http://www.boost.org/tools/build/v2/index_v2.html
165 To use luabind, you must include ``lua.h`` and luabind's main header file::
172 #include <luabind/luabind.hpp>
174 This includes support for both registering classes and functions. If you just
175 want to have support for functions or classes you can include
176 ``luabind/function.hpp`` and ``luabind/class.hpp`` separately::
178 #include <luabind/function.hpp>
179 #include <luabind/class.hpp>
181 The first thing you need to do is to call ``luabind::open(lua_State*)`` which
182 will register the functions to create classes from Lua, and initialize some
183 state-global structures used by luabind. If you don't call this function you
184 will hit asserts later in the library. There is no corresponding close function
185 because once a class has been registered in Lua, there really isn't any good
186 way to remove it. Partly because any remaining instances of that class relies
187 on the class being there. Everything will be cleaned up when the state is
190 .. Isn't this wrong? Don't we include lua.h using lua_include.hpp ?
192 Luabind's headers will never include ``lua.h`` directly, but through
193 ``<luabind/lua_include.hpp>``. If you for some reason need to include another
194 Lua header, you can modify this file.
203 #include <luabind/luabind.hpp>
207 std::cout << "hello world!\n";
210 extern "C" int init(lua_State* L)
212 using namespace luabind;
226 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
227 > loadlib('hello_world.dll', 'init')()
235 Everything that gets registered in Lua is registered in a namespace (Lua
236 tables) or in the global scope (called module). All registrations must be
237 surrounded by its scope. To define a module, the ``luabind::module`` class is
238 used. It is used like this::
245 This will register all declared functions or classes in the global namespace in
246 Lua. If you want to have a namespace for your module (like the standard
247 libraries) you can give a name to the constructor, like this::
249 module(L, "my_library")
254 Here all declarations will be put in the my_library table.
256 If you want nested namespace's you can use the ``luabind::namespace_`` class. It
257 works exactly as ``luabind::module`` except that it doesn't take a lua_State*
258 in it's constructor. An example of its usage could look like this::
260 module(L, "my_library")
266 // library-private declarations
270 As you might have figured out, the following declarations are equivalent::
274 namespace_("my_library")
283 module(L, "my_library")
288 Each declaration must be separated by a comma, like this::
295 .def(constructor<int, int>),
300 More about the actual declarations in the `Binding functions to Lua`_ and
301 `Binding classes to Lua`_ sections.
303 A word of caution, if you are in really bad need for performance, putting your
304 functions in tables will increase the lookup time.
307 Binding functions to Lua
308 ========================
310 To bind functions to Lua you use the function ``luabind::def()``. It has the
313 template<class F, class policies>
314 void def(const char* name, F f, const Policies&);
316 - name is the name the function will have within Lua.
317 - F is the function pointer you want to register.
318 - The Policies parameter is used to describe how parameters and return values
319 are treated by the function, this is an optional parameter. More on this in
320 the `policies`_ section.
322 An example usage could be if you want to register the function ``float
327 def("sin", &std::sin)
333 If you have more than one function with the same name, and want to register
334 them in Lua, you have to explicitly give the signature. This is to let C++ know
335 which function you refer to. For example, if you have two functions, ``int
336 f(const char*)`` and ``void f(int)``. ::
340 def("f", (int(*)(const char*)) &f),
341 def("f", (void(*)(int)) &f)
347 luabind will generate code that checks the Lua stack to see if the values there
348 can match your functions' signatures. It will handle implicit typecasts between
349 derived classes, and it will prefer matches with the least number of implicit
350 casts. In a function call, if the function is overloaded and there's no
351 overload that match the parameters better than the other, you have an
352 ambiguity. This will spawn a run-time error, stating that the function call is
353 ambiguous. A simple example of this is to register one function that takes an
354 int and one that takes a float. Since Lua doesn't distinguish between floats and
355 integers, both will always match.
357 Since all overloads are tested, it will always find the best match (not the
358 first match). This also means that it can handle situations where the only
359 difference in the signature is that one member function is const and the other
362 .. sidebar:: Ownership transfer
364 To correctly handle ownership transfer, create_a() would need an adopt
365 return value policy. More on this in the `Policies`_ section.
367 For example, if the following function and class is registered:
385 And the following Lua code is executed::
388 a1:f() -- the const version is called
391 a2:f() -- the non-const version is called
402 Calling Lua functions
403 ---------------------
405 To call a Lua function, you can either use ``call_function()`` or
411 Ret call_function(lua_State* L, const char* name, ...)
413 Ret call_function(object const& obj, ...)
415 There are two overloads of the ``call_function`` function, one that calls
416 a function given its name, and one that takes an object that should be a Lua
417 value that can be called as a function.
419 The overload that takes a name can only call global Lua functions. The ...
420 represents a variable number of parameters that are sent to the Lua
421 function. This function call may throw ``luabind::error`` if the function
424 The return value isn't actually Ret (the template parameter), but a proxy
425 object that will do the function call. This enables you to give policies to the
426 call. You do this with the operator[]. You give the policies within the
427 brackets, like this::
429 int ret = call_function<int>(
432 , new complex_class()
435 If you want to pass a parameter as a reference, you have to wrap it with the
438 __ http://www.boost.org/doc/html/ref.html
442 int ret = call_function(L, "fun", boost::ref(val));
445 If you want to use a custom error handler for the function call, see
446 ``set_pcall_callback`` under `pcall errorfunc`_.
451 To start a Lua thread, you have to call ``lua_resume()``, this means that you
452 cannot use the previous function ``call_function()`` to start a thread. You have
458 Ret resume_function(lua_State* L, const char* name, ...)
460 Ret resume_function(object const& obj, ...)
467 Ret resume(lua_State* L, ...)
469 The first time you start the thread, you have to give it a function to execute. i.e. you
470 have to use ``resume_function``, when the Lua function yields, it will return the first
471 value passed in to ``lua_yield()``. When you want to continue the execution, you just call
472 ``resume()`` on your ``lua_State``, since it's already executing a function, you don't pass
473 it one. The parameters to ``resume()`` will be returned by ``yield()`` on the Lua side.
475 For yielding C++-functions (without the support of passing data back and forth between the
476 Lua side and the c++ side), you can use the yield_ policy.
478 With the overload of ``resume_function`` that takes an object_, it is important that the
479 object was constructed with the thread as its ``lua_State*``. Like this:
483 lua_State* thread = lua_newthread(L);
484 object fun = get_global(**thread**)["my_thread_fun"];
485 resume_function(fun);
488 Binding classes to Lua
489 ======================
491 To register classes you use a class called ``class_``. Its name is supposed to
492 resemble the C++ keyword, to make it look more intuitive. It has an overloaded
493 member function ``def()`` that is used to register member functions, operators,
494 constructors, enums and properties on the class. It will return its
495 this-pointer, to let you register more members directly.
497 Let's start with a simple example. Consider the following C++ class::
502 testclass(const std::string& s): m_string(s) {}
503 void print_string() { std::cout << m_string << "\n"; }
506 std::string m_string;
509 To register it with a Lua environment, write as follows (assuming you are using
514 class_<testclass>("testclass")
515 .def(constructor<const std::string&>())
516 .def("print_string", &testclass::print_string)
519 This will register the class with the name testclass and constructor that takes
520 a string as argument and one member function with the name ``print_string``.
524 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
525 > a = testclass('a string')
529 It is also possible to register free functions as member functions. The
530 requirement on the function is that it takes a pointer, const pointer,
531 reference or const reference to the class type as the first parameter. The rest
532 of the parameters are the ones that are visible in Lua, while the object
533 pointer is given as the first parameter. If we have the following C++ code::
540 int plus(A* o, int v) { return o->a + v; }
542 You can register ``plus()`` as if it was a member function of A like this::
547 ``plus()`` can now be called as a member function on A with one parameter, int.
548 If the object pointer parameter is const, the function will act as if it was a
549 const member function (it can be called on const objects).
552 Overloaded member functions
553 ---------------------------
555 When binding more than one overloads of a member function, or just binding
556 one overload of an overloaded member function, you have to disambiguate
557 the member function pointer you pass to ``def``. To do this, you can use an
558 ordinary C-style cast, to cast it to the right overload. To do this, you have
559 to know how to express member function types in C++, here's a short tutorial
560 (for more info, refer to your favourite book on C++).
562 The syntax for member function pointer follows:
566 *return-value* (*class-name*::\*)(*arg1-type*, *arg2-type*, *...*)
568 Here's an example illlustrating this::
579 .def("f", (void(A::*)(int))&A::f)
581 This selects the first overload of the function ``f`` to bind. The second
582 overload is not bound.
588 To register a global data member with a class is easily done. Consider the
596 This class is registered like this::
601 .def_readwrite("a", &A::a)
604 This gives read and write access to the member variable ``A::a``. It is also
605 possible to register attributes with read-only access::
610 .def_readonly("a", &A::a)
613 When binding members that are a non-primitive type, the auto generated getter
614 function will return a reference to it. This is to allow chained .-operators.
615 For example, when having a struct containing another struct. Like this::
620 When binding ``B`` to lua, the following expression code should work::
626 This requires the first lookup (on ``a``) to return a reference to ``A``, and
627 not a copy. In that case, luabind will automatically use the dependency policy
628 to make the return value dependent on the object in which it is stored. So, if
629 the returned reference lives longer than all references to the object (b in
630 this case) it will keep the object alive, to avoid being a dangling pointer.
632 You can also register getter and setter functions and make them look as if they
633 were a public data member. Consider the following class::
638 void set_a(int x) { a = x; }
639 int get_a() const { return a; }
645 It can be registered as if it had a public data member a like this::
648 .property("a", &A::get_a, &A::set_a)
650 This way the ``get_a()`` and ``set_a()`` functions will be called instead of
651 just writing to the data member. If you want to make it read only you can just
652 omit the last parameter. Please note that the get function **has to be
653 const**, otherwise it won't compile. This seems to be a common source of errors.
659 If your class contains enumerated constants (enums), you can register them as
660 well to make them available in Lua. Note that they will not be type safe, all
661 enums are integers in Lua, and all functions that takes an enum, will accept
662 any integer. You register them like this::
670 value("my_2nd_enum", 7),
671 value("another_enum", 6)
675 In Lua they are accessed like any data member, except that they are read-only
676 and reached on the class itself rather than on an instance of the class.
680 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
683 > print(A.another_enum)
690 To bind operators you have to include ``<luabind/operator.hpp>``.
692 The mechanism for registering operators on your class is pretty simple. You use
693 a global name ``luabind::self`` to refer to the class itself and then you just
694 write the operator expression inside the ``def()`` call. This class::
698 vec operator+(int s);
701 Is registered like this:
708 .def(**self + int()**)
711 This will work regardless if your plus operator is defined inside your class or
714 If your operator is const (or, when defined as a free function, takes a const
715 reference to the class itself) you have to use ``const_self`` instead of
723 .def(**const_self** + int())
726 The operators supported are those available in Lua:
732 This means, no in-place operators. The equality operator (``==``) has a little
733 hitch; it will not be called if the references are equal. This means that the
734 ``==`` operator has to do pretty much what's it's expected to do.
736 Lua does not support operators such as ``!=``, ``>`` or ``>=``. That's why you
737 can only register the operators listed above. When you invoke one of the
738 mentioned operators, lua will define it in terms of one of the avaliable
741 In the above example the other operand type is instantiated by writing
742 ``int()``. If the operand type is a complex type that cannot easily be
743 instantiated you can wrap the type in a class called ``other<>``. For example:
745 To register this class, we don't want to instantiate a string just to register
752 vec operator+(std::string);
755 Instead we use the ``other<>`` wrapper like this:
762 .def(self + **other<std::string>()**)
765 To register an application (function call-) operator:
772 .def( **self(int())** )
775 There's one special operator. In Lua it's called ``__tostring``, it's not
776 really an operator. It is used for converting objects to strings in a standard
777 way in Lua. If you register this functionality, you will be able to use the lua
778 standard function ``tostring()`` for converting your object to a string.
780 To implement this operator in C++ you should supply an ``operator<<`` for
781 std::ostream. Like this example:
786 std::ostream& operator<<(std::ostream&, number&);
792 class_<number>("number")
793 .def(**tostring(self)**)
797 Nested scopes and static functions
798 ----------------------------------
800 It is possible to add nested scopes to a class. This is useful when you need
801 to wrap a nested class, or a static function.
806 .def(constructor<>())
809 class_<inner>("nested"),
813 In this example, ``f`` will behave like a static member function of the class
814 ``foo``, and the class ``nested`` will behave like a nested class of ``foo``.
816 It's also possible to add namespace's to classes using the same syntax.
822 If you want to register classes that derives from other classes, you can
823 specify a template parameter ``bases<>`` to the ``class_`` instantiation. The
824 following hierarchy::
829 Would be registered like this::
837 If you have multiple inheritance you can specify more than one base. If B would
838 also derive from a class C, it would be registered like this::
842 class_<B, bases<A, C> >("B")
845 Note that you can omit ``bases<>`` when using single inheritance.
848 If you don't specify that classes derive from each other, luabind will not
849 be able to implicitly cast pointers between the types.
855 When you register a class you can tell luabind that all instances of that class
856 should be held by some kind of smart pointer (boost::shared_ptr for instance).
857 You do this by giving the holder type as an extra template parameter to
858 the ``class_`` you are constructing, like this::
862 class_<A, boost::shared_ptr<A> >("A")
865 You also have to supply two functions for your smart pointer. One that returns
866 the type of const version of the smart pointer type (boost::shared_ptr<const A>
867 in this case). And one function that extracts the raw pointer from the smart
868 pointer. The first function is needed because luabind has to allow the
869 non-const -> conversion when passing values from Lua to C++. The second
870 function is needed when Lua calls member functions on held types, the this
871 pointer must be a raw pointer, it is also needed to allow the smart_pointer ->
872 raw_pointer conversion from Lua to C++. They look like this::
877 T* get_pointer(boost::shared_ptr<T>& p)
883 boost::shared_ptr<const A>*
884 get_const_holder(boost::shared_ptr<A>*)
890 The second function will only be used to get a compile time mapping
891 of ``boost::shared_ptr<A>`` to its const version,
892 ``boost::shared_ptr<const A>``. It will never be called, so the
893 return value doesn't matter (only the return type).
895 The conversion that works are (given that B is a base class of A):
897 .. topic:: From Lua to C++
899 ========================= ========================
901 ========================= ========================
902 ``holder_type<A>`` ``A*``
903 ``holder_type<A>`` ``B*``
904 ``holder_type<A>`` ``A const*``
905 ``holder_type<A>`` ``B const*``
906 ``holder_type<A>`` ``holder_type<A>``
907 ``holder_type<A>`` ``holder_type<A const>``
908 ``holder_type<A const>`` ``A const*``
909 ``holder_type<A const>`` ``B const*``
910 ``holder_type<A const>`` ``holder_type<A const>``
911 ========================= ========================
913 .. topic:: From C++ to Lua
915 =============================== ========================
917 =============================== ========================
918 ``holder_type<A>`` ``holder_type<A>``
919 ``holder_type<A const>`` ``holder_type<A const>``
920 ``holder_type<A> const&`` ``holder_type<A>``
921 ``holder_type<A const> const&`` ``holder_type<A const>``
922 =============================== ========================
924 When using a holder type, it can be useful to know if the pointer is valid
925 (i.e. not null). For example when using std::auto_ptr, the holder will be
926 invalidated when passed as a parameter to a function. For this purpose there
927 is a member of all object instances in luabind: ``__ok``. ::
930 void f(std::auto_ptr<X>);
934 class_<X, std::auto_ptr<X> >("X")
935 .def(constructor<>()),
942 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
949 When registering a hierarchy of classes, where all instances are to be held
950 by a smart pointer, all the classes should have the baseclass' holder type.
957 class_<base, boost::shared_ptr<base> >("base")
958 .def(constructor<>()),
959 class_<derived, base, **boost::shared_ptr<base>** >("base")
960 .def(constructor<>())
963 Internally, luabind will do the necessary conversions on the raw pointers, which
964 are first extracted from the holder type.
967 Splitting class registrations
968 -----------------------------
970 In some situations it may be desirable to split a registration of a class
971 across different compilation units. Partly to save rebuild time when changing
972 in one part of the binding, and in some cases compiler limits may force you
973 to split it. To do this is very simple. Consider the following sample code::
975 void register_part1(class_<X>& x)
980 void register_part2(class_<X>& x)
985 void register_(lua_State* L)
995 Here, the class ``X`` is registered in two steps. The two functions
996 ``register_part1`` and ``register_part2`` may be put in separate compilation
999 To separate the module registration and the classes to be registered, see
1000 `Splitting up the registration`_.
1005 Since functions have to be able to take Lua values (of variable type) we need a
1006 wrapper around them. This wrapper is called ``luabind::object``. If the
1007 function you register takes an object, it will match any Lua value. To use it,
1008 you need to include ``<luabind/object.hpp>``.
1018 object(lua_State\*, T const& value);
1019 object(from_stack const&);
1020 object(object const&);
1025 lua_State\* interpreter() const;
1027 bool is_valid() const;
1028 operator *safe_bool_type* () const;
1031 *implementation-defined* operator[](Key const&);
1034 object& operator=(T const&);
1035 object& operator=(object const&);
1037 bool operator==(object const&) const;
1038 bool operator<(object const&) const;
1039 bool operator<=(object const&) const;
1040 bool operator>(object const&) const;
1041 bool operator>=(object const&) const;
1042 bool operator!=(object const&) const;
1045 *implementation-defined* operator[](T const& key) const
1049 *implementation-defined* operator()();
1052 *implementation-defined* operator()(A0 const& a0);
1054 template<class A0, class A1>
1055 *implementation-defined* operator()(A0 const& a0, A1 const& a1);
1060 When you have a Lua object, you can assign it a new value with the assignment
1061 operator (=). When you do this, the ``default_policy`` will be used to make the
1062 conversion from C++ value to Lua. If your ``luabind::object`` is a table you
1063 can access its members through the operator[] or the Iterators_. The value
1064 returned from the operator[] is a proxy object that can be used both for
1065 reading and writing values into the table (using operator=).
1067 Note that it is impossible to know if a Lua value is indexable or not
1068 (``lua_gettable`` doesn't fail, it succeeds or crashes). This means that if
1069 you're trying to index something that cannot be indexed, you're on your own.
1070 Lua will call its ``panic()`` function. See `lua panic`_.
1072 There are also free functions that can be used for indexing the table, see
1073 `Related functions`_.
1075 The constructor that takes a ``from_stack`` object is used when you want to
1076 initialize the object with a value from the lua stack. The ``from_stack``
1077 type has the following constructor::
1079 from_stack(lua_State* L, int index);
1081 The index is an ordinary lua stack index, negative values are indexed from the
1082 top of the stack. You use it like this::
1084 object o(from_stack(L, -1));
1086 This will create the object ``o`` and copy the value from the top of the lua stack.
1088 The ``interpreter()`` function returns the Lua state where this object is stored.
1089 If you want to manipulate the object with Lua functions directly you can push
1090 it onto the Lua stack by calling ``push()``.
1092 The operator== will call lua_equal() on the operands and return its result.
1094 The ``is_valid()`` function tells you whether the object has been initialized
1095 or not. When created with its default constructor, objects are invalid. To make
1096 an object valid, you can assign it a value. If you want to invalidate an object
1097 you can simply assign it an invalid object.
1099 The ``operator safe_bool_type()`` is equivalent to ``is_valid()``. This means
1100 that these snippets are equivalent::
1118 The application operator will call the value as if it was a function. You can
1119 give it any number of parameters (currently the ``default_policy`` will be used
1120 for the conversion). The returned object refers to the return value (currently
1121 only one return value is supported). This operator may throw ``luabind::error``
1122 if the function call fails. If you want to specify policies to your function
1123 call, you can use index-operator (operator[]) on the function call, and give
1124 the policies within the [ and ]. Like this::
1129 , new my_complex_structure(6)
1132 This tells luabind to make Lua adopt the ownership and responsibility for the
1133 pointer passed in to the lua-function.
1135 It's important that all instances of object have been destructed by the time
1136 the Lua state is closed. The object will keep a pointer to the lua state and
1137 release its Lua object in its destructor.
1139 Here's an example of how a function can use a table::
1141 void my_function(object const& table)
1143 if (type(table) == LUA_TTABLE)
1145 table["time"] = std::clock();
1146 table["name"] = std::rand() < 500 ? "unusual" : "usual";
1148 std::cout << object_cast<std::string>(table[5]) << "\n";
1152 If you take a ``luabind::object`` as a parameter to a function, any Lua value
1153 will match that parameter. That's why we have to make sure it's a table before
1158 std::ostream& operator<<(std::ostream&, object const&);
1160 There's a stream operator that makes it possible to print objects or use
1161 ``boost::lexical_cast`` to convert it to a string. This will use lua's string
1162 conversion function. So if you convert a C++ object with a ``tostring``
1163 operator, the stream operator for that type will be used.
1168 There are two kinds of iterators. The normal iterator that will use the metamethod
1169 of the object (if there is any) when the value is retrieved. This iterator is simply
1170 called ``luabind::iterator``. The other iterator is called ``luabind::raw_iterator``
1171 and will bypass the metamethod and give the true contents of the table. They have
1172 identical interfaces, which implements the ForwardIterator_ concept. Apart from
1173 the members of standard iterators, they have the following members and constructors:
1175 .. _ForwardIterator: http://www.sgi.com/tech/stl/ForwardIterator.html
1182 iterator(object const&);
1186 *standard iterator members*
1189 The constructor that takes a ``luabind::object`` is actually a template that can be
1190 used with object. Passing an object as the parameter to the iterator will
1191 construct the iterator to refer to the first element in the object.
1193 The default constructor will initialize the iterator to the one-past-end
1194 iterator. This is used to test for the end of the sequence.
1196 The value type of the iterator is an implementation defined proxy type which
1197 supports the same operations as ``luabind::object``. Which means that in most
1198 cases you can just treat it as an ordinary object. The difference is that any
1199 assignments to this proxy will result in the value being inserted at the
1200 iterators position, in the table.
1202 The ``key()`` member returns the key used by the iterator when indexing the
1203 associated Lua table.
1205 An example using iterators::
1207 for (iterator i(globals(L)["a"]), end; i != end; ++i)
1212 The iterator named ``end`` will be constructed using the default constructor
1213 and hence refer to the end of the sequence. This example will simply iterate
1214 over the entries in the global table ``a`` and set all its values to 1.
1219 There are a couple of functions related to objects and tables.
1223 int type(object const&);
1225 This function will return the lua type index of the given object.
1226 i.e. ``LUA_TNIL``, ``LUA_TNUMBER`` etc.
1230 template<class T, class K>
1231 void settable(object const& o, K const& key, T const& value);
1233 object gettable(object const& o, K const& key);
1234 template<class T, class K>
1235 void rawset(object const& o, K const& key, T const& value);
1237 object rawget(object const& o, K const& key);
1239 These functions are used for indexing into tables. ``settable`` and ``gettable``
1240 translates into calls to ``lua_settable`` and ``lua_gettable`` respectively. Which
1241 means that you could just as well use the index operator of the object.
1243 ``rawset`` and ``rawget`` will translate into calls to ``lua_rawset`` and
1244 ``lua_rawget`` respectively. So they will bypass any metamethod and give you the
1245 true value of the table entry.
1250 T object_cast<T>(object const&);
1251 template<class T, class Policies>
1252 T object_cast<T>(object const&, Policies);
1255 boost::optional<T> object_cast_nothrow<T>(object const&);
1256 template<class T, class Policies>
1257 boost::optional<T> object_cast_nothrow<T>(object const&, Policies);
1259 The ``object_cast`` function casts the value of an object to a C++ value.
1260 You can supply a policy to handle the conversion from lua to C++. If the cast
1261 cannot be made a ``cast_failed`` exception will be thrown. If you have
1262 defined LUABIND_NO_ERROR_CHECKING (see `Build options`_) no checking will occur,
1263 and if the cast is invalid the application may very well crash. The nothrow
1264 versions will return an uninitialized ``boost::optional<T>`` object, to
1265 indicate that the cast could not be performed.
1267 The function signatures of all of the above functions are really templates
1268 for the object parameter, but the intention is that you should only pass
1269 objects in there, that's why it's left out of the documentation.
1273 object globals(lua_State*);
1274 object registry(lua_State*);
1276 These functions return the global environment table and the registry table respectively.
1280 object newtable(lua_State*);
1282 This function creates a new table and returns it as an object.
1287 To set a table entry to ``nil``, you can use ``luabind::nil``. It will avoid
1288 having to take the detour by first assigning ``nil`` to an object and then
1289 assign that to the table entry. It will simply result in a ``lua_pushnil()``
1290 call, instead of copying an object.
1295 object table = newtable(L);
1296 table["foo"] = "bar";
1298 // now, clear the "foo"-field
1302 Defining classes in Lua
1303 =======================
1305 In addition to binding C++ functions and classes with Lua, luabind also provide
1306 an OO-system in Lua. ::
1308 class 'lua_testclass'
1310 function lua_testclass:__init(name)
1314 function lua_testclass:print()
1318 a = lua_testclass('example')
1322 Inheritance can be used between lua-classes::
1324 class 'derived' (lua_testclass)
1326 function derived:__init() super('derived name')
1329 function derived:print()
1330 print('Derived:print() -> ')
1331 lua_testclass.print(self)
1334 Here the ``super`` keyword is used in the constructor to initialize the base
1335 class. The user is required to call ``super`` first in the constructor.
1337 As you can see in this example, you can call the base class member functions.
1338 You can find all member functions in the base class, but you will have to give
1339 the this-pointer (``self``) as first argument.
1345 It is also possible to derive Lua classes from C++ classes, and override
1346 virtual functions with Lua functions. To do this we have to create a wrapper
1347 class for our C++ base class. This is the class that will hold the Lua object
1348 when we instantiate a Lua class.
1356 { std::cout << s << "\n"; }
1358 virtual void f(int a)
1359 { std::cout << "f(" << a << ")\n"; }
1362 struct base_wrapper : base, luabind::wrap_base
1364 base_wrapper(const char* s)
1368 virtual void f(int a)
1373 static void default_f(base* ptr, int a)
1375 return ptr->base::f(a);
1383 class_<base, base_wrapper>("base")
1384 .def(constructor<const char*>())
1385 .def("f", &base::f, &base_wrapper::default_f)
1389 Since MSVC6.5 doesn't support explicit template parameters
1390 to member functions, instead of using the member function ``call()``
1391 you call a free function ``call_member()`` and pass the this-pointer
1394 Note that if you have both base classes and a base class wrapper, you must give
1395 both bases and the base class wrapper type as template parameter to
1396 ``class_`` (as done in the example above). The order in which you specify
1397 them is not important. You must also register both the static version and the
1398 virtual version of the function from the wrapper, this is necessary in order
1399 to allow luabind to use both dynamic and static dispatch when calling the function.
1402 It is extremely important that the signatures of the static (default) function
1403 is identical to the virtual function. The fact that one of them is a free
1404 function and the other a member function doesn't matter, but the parameters
1405 as seen from lua must match. It would not have worked if the static function
1406 took a ``base_wrapper*`` as its first argument, since the virtual function
1407 takes a ``base*`` as its first argument (its this pointer). There's currently
1408 no check in luabind to make sure the signatures match.
1410 If we didn't have a class wrapper, it would not be possible to pass a Lua class
1411 back to C++. Since the entry points of the virtual functions would still point
1412 to the C++ base class, and not to the functions defined in Lua. That's why we
1413 need one function that calls the base class' real function (used if the lua
1414 class doesn't redefine it) and one virtual function that dispatches the call
1415 into luabind, to allow it to select if a Lua function should be called, or if
1416 the original function should be called. If you don't intend to derive from a
1417 C++ class, or if it doesn't have any virtual member functions, you can register
1418 it without a class wrapper.
1420 You don't need to have a class wrapper in order to derive from a class, but if
1421 it has virtual functions you may have silent errors.
1423 .. Unnecessary? The rule of thumb is:
1424 If your class has virtual functions, create a wrapper type, if it doesn't
1425 don't create a wrapper type.
1427 The wrappers must derive from ``luabind::wrap_base``, it contains a Lua reference
1428 that will hold the Lua instance of the object to make it possible to dispatch
1429 virtual function calls into Lua. This is done through an overloaded member function::
1432 Ret call(char const* name, ...)
1434 Its used in a similar way as ``call_function``, with the exception that it doesn't
1435 take a ``lua_State`` pointer, and the name is a member function in the Lua class.
1439 The current implementation of ``call_member`` is not able to distinguish const
1440 member functions from non-const. If you have a situation where you have an overloaded
1441 virtual function where the only difference in their signatures is their constness, the
1442 wrong overload will be called by ``call_member``. This is rarely the case though.
1447 When a pointer or reference to a registered class with a wrapper is passed
1448 to Lua, luabind will query for it's dynamic type. If the dynamic type
1449 inherits from ``wrap_base``, object identity is preserved.
1454 struct A_wrap : A, wrap_base { .. };
1456 A* f(A* ptr) { return ptr; }
1460 class_<A, A_wrap>("A"),
1468 > assert(x == f(x)) -- object identity is preserved when object is
1469 -- passed through C++
1471 This functionality relies on RTTI being enabled (that ``LUABIND_NO_RTTI`` is
1474 Overloading operators
1475 ---------------------
1477 You can overload most operators in Lua for your classes. You do this by simply
1478 declaring a member function with the same name as an operator (the name of the
1479 metamethods in Lua). The operators you can overload are:
1493 ``__tostring`` isn't really an operator, but it's the metamethod that is called
1494 by the standard library's ``tostring()`` function. There's one strange behavior
1495 regarding binary operators. You are not guaranteed that the self pointer you
1496 get actually refers to an instance of your class. This is because Lua doesn't
1497 distinguish the two cases where you get the other operand as left hand value or
1498 right hand value. Consider the following examples::
1502 function my_class:__init(v)
1506 function my_class:__sub(v)
1507 return my_class(self.val - v.val)
1510 function my_class:__tostring()
1514 This will work well as long as you only subtracts instances of my_class with
1515 each other. But If you want to be able to subtract ordinary numbers from your
1516 class too, you have to manually check the type of both operands, including the
1519 function my_class:__sub(v)
1520 if (type(self) == 'number') then
1521 return my_class(self - v.val)
1523 elseif (type(v) == 'number') then
1524 return my_class(self.val - v)
1527 -- assume both operands are instances of my_class
1528 return my_class(self.val - v.val)
1533 The reason why ``__sub`` is used as an example is because subtraction is not
1534 commutative (the order of the operands matters). That's why luabind cannot
1535 change order of the operands to make the self reference always refer to the
1536 actual class instance.
1538 If you have two different Lua classes with an overloaded operator, the operator
1539 of the right hand side type will be called. If the other operand is a C++ class
1540 with the same operator overloaded, it will be prioritized over the Lua class'
1541 operator. If none of the C++ overloads matches, the Lua class operator will be
1548 If an object needs to perform actions when it's collected we provide a
1549 ``__finalize`` function that can be overridden in lua-classes. The
1550 ``__finalize`` functions will be called on all classes in the inheritance
1551 chain, starting with the most derived type. ::
1555 function lua_testclass:__finalize()
1556 -- called when the an object is collected
1563 If your lua C++ classes don't have wrappers (see `Deriving in lua`_) and
1564 you derive from them in lua, they may be sliced. Meaning, if an object
1565 is passed into C++ as a pointer to its base class, the lua part will be
1566 separated from the C++ base part. This means that if you call virtual
1567 functions on that C++ object, they will not be dispatched to the lua
1568 class. It also means that if you adopt the object, the lua part will be
1573 +--------------------+
1574 | C++ object | <- ownership of this part is transferred
1575 | | to c++ when adopted
1576 +--------------------+
1577 | lua class instance | <- this part is garbage collected when
1578 | and lua members | instance is adopted, since it cannot
1579 +--------------------+ be held by c++.
1582 The problem can be illustrated by this example::
1586 A* filter_a(A* a) { return a; }
1587 void adopt_a(A* a) { delete a; }
1592 using namespace luabind;
1597 def("filter_a", &filter_a),
1598 def("adopt_a", &adopt_a, adopt(_1))
1608 In this example, lua cannot know that ``b`` actually is the same object as
1609 ``a``, and it will therefore consider the object to be owned by the C++ side.
1610 When the ``b`` pointer then is adopted, a runtime error will be raised because
1611 an object not owned by lua is being adopted to C++.
1613 If you have a wrapper for your class, none of this will happen, see
1620 If any of the functions you register throws an exception when called, that
1621 exception will be caught by luabind and converted to an error string and
1622 ``lua_error()`` will be invoked. If the exception is a ``std::exception`` or a
1623 ``const char*`` the string that is pushed on the Lua stack, as error message,
1624 will be the string returned by ``std::exception::what()`` or the string itself
1625 respectively. If the exception is unknown, a generic string saying that the
1626 function threw an exception will be pushed.
1628 Exceptions thrown from user defined functions have to be caught by luabind. If
1629 they weren't they would be thrown through Lua itself, which is usually compiled
1630 as C code and doesn't support the stack-unwinding that exceptions imply.
1632 Any function that invokes Lua code may throw ``luabind::error``. This exception
1633 means that a Lua run-time error occurred. The error message is found on top of
1634 the Lua stack. The reason why the exception doesn't contain the error string
1635 itself is because it would then require heap allocation which may fail. If an
1636 exception class throws an exception while it is being thrown itself, the
1637 application will be terminated.
1639 Error's synopsis is::
1641 class error : public std::exception
1645 lua_State* state() const throw();
1646 virtual const char* what() const throw();
1649 The state function returns a pointer to the Lua state in which the error was
1650 thrown. This pointer may be invalid if you catch this exception after the lua
1651 state is destructed. If the Lua state is valid you can use it to retrieve the
1652 error message from the top of the Lua stack.
1654 An example of where the Lua state pointer may point to an invalid state
1659 lua_state(lua_State* L): m_L(L) {}
1660 ~lua_state() { lua_close(m_L); }
1661 operator lua_State*() { return m_L; }
1669 lua_state L = lua_open();
1672 catch(luabind::error& e)
1674 lua_State* L = e.state();
1675 // L will now point to the destructed
1676 // Lua state and be invalid
1681 There's another exception that luabind may throw: ``luabind::cast_failed``,
1682 this exception is thrown from ``call_function<>`` or ``call_member<>``. It
1683 means that the return value from the Lua function couldn't be converted to
1684 a C++ value. It is also thrown from ``object_cast<>`` if the cast cannot
1687 The synopsis for ``luabind::cast_failed`` is::
1689 class cast_failed : public std::exception
1692 cast_failed(lua_State*);
1693 lua_State* state() const throw();
1694 LUABIND_TYPE_INFO info() const throw();
1695 virtual const char* what() const throw();
1698 Again, the state member function returns a pointer to the Lua state where the
1699 error occurred. See the example above to see where this pointer may be invalid.
1701 The info member function returns the user defined ``LUABIND_TYPE_INFO``, which
1702 defaults to a ``const std::type_info*``. This type info describes the type that
1703 we tried to cast a Lua value to.
1705 If you have defined ``LUABIND_NO_EXCEPTIONS`` none of these exceptions will be
1706 thrown, instead you can set two callback functions that are called instead.
1707 These two functions are only defined if ``LUABIND_NO_EXCEPTIONS`` are defined.
1711 luabind::set_error_callback(void(*)(lua_State*))
1713 The function you set will be called when a runtime-error occur in Lua code. You
1714 can find an error message on top of the Lua stack. This function is not
1715 expected to return, if it does luabind will call ``std::terminate()``.
1719 luabind::set_cast_failed_callback(void(*)(lua_State*, LUABIND_TYPE_INFO))
1721 The function you set is called instead of throwing ``cast_failed``. This function
1722 is not expected to return, if it does luabind will call ``std::terminate()``.
1728 Sometimes it is necessary to control how luabind passes arguments and return
1729 value, to do this we have policies. All policies use an index to associate
1730 them with an argument in the function signature. These indices are ``result``
1731 and ``_N`` (where ``N >= 1``). When dealing with member functions ``_1`` refers
1732 to the ``this`` pointer.
1734 .. contents:: Policies currently implemented
1738 .. include:: adopt.rst
1739 .. include:: dependency.rst
1740 .. include:: out_value.rst
1741 .. include:: pure_out_value.rst
1742 .. include:: return_reference_to.rst
1743 .. include:: copy.rst
1744 .. include:: discard_result.rst
1745 .. include:: return_stl_iterator.rst
1746 .. include:: raw.rst
1747 .. include:: yield.rst
1749 .. old policies section
1750 ===================================================
1755 This will make a copy of the parameter. This is the default behavior when
1756 passing parameters by-value. Note that this can only be used when passing from
1757 C++ to Lua. This policy requires that the parameter type has a copy
1760 To use this policy you need to include ``luabind/copy_policy.hpp``.
1766 This will transfer ownership of the parameter.
1768 Consider making a factory function in C++ and exposing it to lua::
1779 def("create_base", create_base)
1782 Here we need to make sure Lua understands that it should adopt the pointer
1783 returned by the factory-function. This can be done using the adopt-policy.
1789 def(L, "create_base", adopt(return_value))
1792 To specify multiple policies we just separate them with '+'.
1796 base* set_and_get_new(base* ptr)
1798 base_ptrs.push_back(ptr);
1804 def("set_and_get_new", &set_and_get_new,
1805 adopt(return_value) + adopt(_1))
1808 When Lua adopts a pointer, it will call delete on it. This means that it cannot
1809 adopt pointers allocated with another allocator than new (no malloc for
1812 To use this policy you need to include ``luabind/adopt_policy.hpp``.
1818 The dependency policy is used to create life-time dependencies between values.
1819 Consider the following example::
1825 const B& get_member()
1831 When wrapping this class, we would do something like::
1836 .def(constructor<>())
1837 .def("get_member", &A::get_member)
1841 However, since the return value of get_member is a reference to a member of A,
1842 this will create some life-time issues. For example::
1844 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1846 b = a:get_member() -- b points to a member of a
1848 collectgarbage(0) -- since there are no references left to a, it is
1850 -- at this point, b is pointing into a removed object
1852 When using the dependency-policy, it is possible to tell luabind to tie the
1853 lifetime of one object to another, like this::
1858 .def(constructor<>())
1859 .def("get_member", &A::get_member, dependency(result, _1))
1862 This will create a dependency between the return-value of the function, and the
1863 self-object. This means that the self-object will be kept alive as long as the
1864 result is still alive. ::
1866 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1868 b = a:get_member() -- b points to a member of a
1870 collectgarbage(0) -- a is dependent on b, so it isn't removed
1872 collectgarbage(0) -- all dependencies to a gone, a is removed
1874 To use this policy you need to include ``luabind/dependency_policy.hpp``.
1880 It is very common to return references to arguments or the this-pointer to
1881 allow for chaining in C++.
1896 When luabind generates code for this, it will create a new object for the
1897 return-value, pointing to the self-object. This isn't a problem, but could be a
1898 bit inefficient. When using the return_reference_to-policy we have the ability
1899 to tell luabind that the return-value is already on the Lua stack.
1906 .def(constructor<>())
1907 .def("set", &A::set, return_reference_to(_1))
1910 Instead of creating a new object, luabind will just copy the object that is
1911 already on the stack.
1914 This policy ignores all type information and should be used only it
1915 situations where the parameter type is a perfect match to the
1916 return-type (such as in the example).
1918 To use this policy you need to include ``luabind/return_reference_to_policy.hpp``.
1924 This policy makes it possible to wrap functions that take non const references
1925 as its parameters with the intention to write return values to them.
1929 void f(float& val) { val = val + 10.f; }
1935 void f(float* val) { *val = *val + 10.f; }
1937 Can be wrapped by doing::
1941 def("f", &f, out_value(_1))
1944 When invoking this function from Lua it will return the value assigned to its
1949 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1954 When this policy is used in conjunction with user define types we often need
1955 to do ownership transfers.
1961 void f1(A*& obj) { obj = new A(); }
1962 void f2(A** obj) { *obj = new A(); }
1964 Here we need to make sure luabind takes control over object returned, for
1965 this we use the adopt policy::
1970 def("f1", &f1, out_value(_1, adopt(_2)))
1971 def("f2", &f2, out_value(_1, adopt(_2)))
1974 Here we are using adopt as an internal policy to out_value. The index
1975 specified, _2, means adopt will be used to convert the value back to Lua.
1976 Using _1 means the policy will be used when converting from Lua to C++.
1978 To use this policy you need to include ``luabind/out_value_policy.hpp``.
1983 This policy works in exactly the same way as out_value, except that it
1984 replaces the parameters with default-constructed objects.
1988 void get(float& x, float& y)
1999 pure_out_value(_1) + pure_out_value(_2))
2004 Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2009 Like out_value, it is possible to specify an internal policy used then
2010 converting the values back to Lua.
2014 void get(test_class*& obj)
2016 obj = new test_class();
2023 def("get", &get, pure_out_value(_1, adopt(_1)))
2030 This is a very simple policy which makes it possible to throw away
2031 the value returned by a C++ function, instead of converting it to
2032 Lua. This example makes sure the this reference never gets converted
2039 simple& set_name(const std::string& n)
2052 class_<simple>("simple")
2053 .def("set_name", &simple::set_name, discard_result)
2056 To use this policy you need to include ``luabind/discard_result_policy.hpp``.
2062 This policy converts an STL container to a generator function that can be used
2063 in Lua to iterate over the container. It works on any container that defines
2064 ``begin()`` and ``end()`` member functions (they have to return iterators). It
2065 can be used like this::
2069 std::vector<std::string> names;
2076 .def_readwrite("names", &A::names, return_stl_iterator)
2079 The Lua code to iterate over the container::
2083 for name in a.names do
2088 To use this policy you need to include ``luabind/iterator_policy.hpp``.
2094 This policy will cause the function to always yield the current thread when
2095 returning. See the Lua manual for restrictions on yield.
2098 Splitting up the registration
2099 =============================
2101 It is possible to split up a module registration into several
2102 translation units without making each registration dependent
2103 on the module it's being registered in.
2107 luabind::scope register_a()
2117 luabind::scope register_b()
2127 luabind::scope register_a();
2128 luabind::scope register_b();
2130 void register_module(lua_State* L)
2146 As mentioned in the `Lua documentation`_, it is possible to pass an
2147 error handler function to ``lua_pcall()``. Luabind makes use of
2148 ``lua_pcall()`` internally when calling member functions and free functions.
2149 It is possible to set the error handler function that Luabind will use
2152 typedef int(*pcall_callback_fun)(lua_State*);
2153 void set_pcall_callback(pcall_callback_fun fn);
2155 This is primarily useful for adding more information to the error message
2156 returned by a failed protected call. For more information on how to use the
2157 pcall_callback function, see ``errfunc`` under the
2158 `pcall section of the lua manual`_.
2160 For more information on how to retrieve debugging information from lua, see
2161 `the debug section of the lua manual`_.
2163 The message returned by the ``pcall_callback`` is accessable as the top lua
2164 value on the stack. For example, if you would like to access it as a luabind
2165 object, you could do like this::
2169 object error_msg(from_stack(e.state(), -1));
2170 std::cout << error_msg << std::endl;
2173 .. _Lua documentation: http://www.lua.org/manual/5.0/manual.html
2174 .. _`pcall section of the lua manual`: http://www.lua.org/manual/5.0/manual.html#3.15
2175 .. _`the debug section of the lua manual`: http://www.lua.org/manual/5.0/manual.html#4
2177 file and line numbers
2178 ---------------------
2180 If you want to add file name and line number to the error messages generated
2181 by luabind you can define your own `pcall errorfunc`_. You may want to modify
2182 this callback to better suit your needs, but the basic functionality could be
2183 implemented like this::
2185 int add_file_and_line(lua_State* L)
2188 lua_getstack(L, 1, &d);
2189 lua_getinfo(L, "Sln", &d);
2190 std::string err = lua_tostring(L, -1);
2192 std::stringstream msg;
2193 msg << d.short_src << ":" << d.currentline;
2197 msg << "(" << d.namewhat << " " << d.name << ")";
2200 lua_pushstring(L, msg.str().c_str());
2204 For more information about what kind of information you can add to the error
2205 message, see `the debug section of the lua manual`_.
2207 Note that the callback set by ``set_pcall_callback()`` will only be used when
2208 luabind executes lua code. Anytime when you call ``lua_pcall`` yourself, you
2209 have to supply your function if you want error messages translated.
2214 When lua encounters a fatal error caused by a bug from the C/C++ side, it will
2215 call its internal panic function. This can happen, for example, when you call
2216 ``lua_gettable`` on a value that isn't a table. If you do the same thing from
2217 within lua, it will of course just fail with an error message.
2219 The default panic function will ``exit()`` the application. If you want to
2220 handle this case without terminating your application, you can define your own
2221 panic function using ``lua_atpanic``. The best way to continue from the panic
2222 function is to make sure lua is compiled as C++ and throw an exception from
2223 the panic function. Throwing an exception instead of using ``setjmp`` and
2224 ``longjmp`` will make sure the stack is correctly unwound.
2226 When the panic function is called, the lua state is invalid, and the only
2227 allowed operation on it is to close it.
2229 For more information, see the `lua manual section 3.19`_.
2231 .. _`lua manual section 3.19`: http://www.lua.org/manual/5.0/manual.html#3.19
2233 structured exceptions (MSVC)
2234 ----------------------------
2236 Since lua is generally built as a C library, any callbacks called from lua
2237 cannot under any circumstance throw an exception. Because of that, luabind has
2238 to catch all exceptions and translate them into proper lua errors (by calling
2239 ``lua_error()``). This means we have a ``catch(...) {}`` in there.
2241 In Visual Studio, ``catch (...)`` will not only catch C++ exceptions, it will
2242 also catch structured exceptions, such as segmentation fault. This means that if
2243 your function, that gets called from luabind, makes an invalid memory
2244 adressing, you won't notice it. All that will happen is that lua will return
2245 an error message saying "unknown exception".
2247 To remedy this, you can create your own *exception translator*::
2249 void straight_to_debugger(unsigned int, _EXCEPTION_POINTERS*)
2253 ::_set_se_translator(straight_to_debugger);
2256 This will make structured exceptions, like segmentation fault, to actually get
2257 caught by the debugger.
2263 These are the error messages that can be generated by luabind, with a more
2264 in-depth explanation.
2266 - .. parsed-literal::
2268 the attribute '*class-name.attribute-name*' is read only
2270 There is no data member named *attribute-name* in the class *class-name*,
2271 or there's no setter-function registered on that property name. See the
2272 Properties_ section.
2274 - .. parsed-literal::
2276 the attribute '*class-name.attribute-name*' is of type: (*class-name*) and does not match (*class_name*)
2278 This error is generated if you try to assign an attribute with a value
2279 of a type that cannot be converted to the attribute's type.
2282 - .. parsed-literal::
2284 *class-name()* threw an exception, *class-name:function-name()* threw an exception
2286 The class' constructor or member function threw an unknown exception.
2287 Known exceptions are const char*, std::exception. See the
2288 `exceptions`_ section.
2290 - .. parsed-literal::
2292 no overload of '*class-name:function-name*' matched the arguments (*parameter-types*)
2293 no match for function call '*function-name*' with the parameters (*parameter-types*)
2294 no constructor of *class-name* matched the arguments (*parameter-types*)
2295 no operator *operator-name* matched the arguments (*parameter-types*)
2297 No function/operator with the given name takes the parameters you gave
2298 it. You have either misspelled the function name, or given it incorrect
2299 parameters. This error is followed by a list of possible candidate
2300 functions to help you figure out what parameter has the wrong type. If
2301 the candidate list is empty there's no function at all with that name.
2302 See the signature matching section.
2304 - .. parsed-literal::
2306 call of overloaded '*class-name:function-name*(*parameter-types*)' is ambiguous
2307 ambiguous match for function call '*function-name*' with the parameters (*parameter-types*)
2308 call of overloaded constructor '*class-name*(*parameter-types*)' is ambiguous
2309 call of overloaded operator *operator-name* (*parameter-types*) is ambiguous
2311 This means that the function/operator you are trying to call has at least
2312 one other overload that matches the arguments just as good as the first
2315 - .. parsed-literal::
2317 cannot derive from C++ class '*class-name*'. It does not have a wrapped type.
2324 There are a number of configuration options available when building luabind.
2325 It is very important that your project has the exact same configuration
2326 options as the ones given when the library was build! The exceptions are the
2327 ``LUABIND_MAX_ARITY`` and ``LUABIND_MAX_BASES`` which are template-based
2328 options and only matters when you use the library (which means they can
2329 differ from the settings of the library).
2331 The default settings which will be used if no other settings are given
2332 can be found in ``luabind/config.hpp``.
2334 If you want to change the settings of the library, you can modify the
2335 config file. It is included and used by all makefiles. You can change paths
2336 to Lua and boost in there as well.
2339 Controls the maximum arity of functions that are registered with luabind.
2340 You can't register functions that takes more parameters than the number
2341 this macro is set to. It defaults to 5, so, if your functions have greater
2342 arity you have to redefine it. A high limit will increase compilation time.
2345 Controls the maximum number of classes one class can derive from in
2346 luabind (the number of classes specified within ``bases<>``).
2347 ``LUABIND_MAX_BASES`` defaults to 4. A high limit will increase
2350 LUABIND_NO_ERROR_CHECKING
2351 If this macro is defined, all the Lua code is expected only to make legal
2352 calls. If illegal function calls are made (e.g. giving parameters that
2353 doesn't match the function signature) they will not be detected by luabind
2354 and the application will probably crash. Error checking could be disabled
2355 when shipping a release build (given that no end-user has access to write
2356 custom Lua code). Note that function parameter matching will be done if a
2357 function is overloaded, since otherwise it's impossible to know which one
2358 was called. Functions will still be able to throw exceptions when error
2359 checking is disabled.
2361 If a function throws an exception it will be caught by luabind and
2362 propagated with ``lua_error()``.
2364 LUABIND_NO_EXCEPTIONS
2365 This define will disable all usage of try, catch and throw in luabind.
2366 This will in many cases disable run-time errors, when performing invalid
2367 casts or calling Lua functions that fails or returns values that cannot
2368 be converted by the given policy. luabind requires that no function called
2369 directly or indirectly by luabind throws an exception (throwing exceptions
2370 through Lua has undefined behavior).
2372 Where exceptions are the only way to get an error report from luabind,
2373 they will be replaced with calls to the callback functions set with
2374 ``set_error_callback()`` and ``set_cast_failed_callback()``.
2377 If you want to link dynamically against Lua, you can set this define to
2378 the import-keyword on your compiler and platform. On Windows in Visual Studio
2379 this should be ``__declspec(dllimport)`` if you want to link against Lua
2382 LUABIND_EXPORT, LUABIND_IMPORT
2383 If you want to link against luabind as a dll (in Visual Studio), you can
2384 define ``LUABIND_EXPORT`` to ``__declspec(dllexport)`` and
2385 ``LUABIND_IMPORT`` to ``__declspec(dllimport)`` or
2386 ``__attribute__ ((visibility("default")))`` on GCC 4.
2387 Note that you have to link against Lua as a dll aswell, to make it work.
2390 You can define this if you don't want luabind to use ``dynamic_cast<>``.
2391 It will disable `Object identity`_.
2393 LUABIND_TYPE_INFO, LUABIND_TYPE_INFO_EQUAL(i1,i2), LUABIND_TYPEID(t), LUABIND_INVALID_TYPE_INFO
2394 If you don't want to use the RTTI supplied by C++ you can supply your own
2395 type-info structure with the ``LUABIND_TYPE_INFO`` define. Your type-info
2396 structure must be copyable and must be able to compare itself against
2397 other type-info structures. You supply the compare function through the
2398 ``LUABIND_TYPE_INFO_EQUAL()`` define. It should compare the two type-info
2399 structures it is given and return true if they represent the same type and
2400 false otherwise. You also have to supply a function to generate your
2401 type-info structure. You do this through the ``LUABIND_TYPEID()`` define.
2402 It should return your type-info structure and it takes a type as its
2403 parameter. That is, a compile time parameter.
2404 ``LUABIND_INVALID_TYPE_INFO`` macro should be defined to an invalid type.
2405 No other type should be able to produce this type info. To use it you
2406 probably have to make a traits class with specializations for all classes
2407 that you have type-info for. Like this::
2413 template<class T> struct typeinfo_trait;
2415 template<> struct typeinfo_trait<A> { enum { type_id = 0 }; };
2416 template<> struct typeinfo_trait<B> { enum { type_id = 1 }; };
2417 template<> struct typeinfo_trait<C> { enum { type_id = 2 }; };
2419 If you have set up your own RTTI system like this (by using integers to
2420 identify types) you can have luabind use it with the following defines::
2422 #define LUABIND_TYPE_INFO const std::type_info*
2423 #define LUABIND_TYPEID(t) &typeid(t)
2424 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
2425 #define LUABIND_INVALID_TYPE_INFO &typeid(detail::null_type)
2427 Currently the type given through ``LUABIND_TYPE_INFO`` must be less-than
2431 This define will disable all asserts and should be defined in a release
2435 Implementation notes
2436 ====================
2438 The classes and objects are implemented as user data in Lua. To make sure that
2439 the user data really is the internal structure it is supposed to be, we tag
2440 their metatables. A user data who's metatable contains a boolean member named
2441 ``__luabind_classrep`` is expected to be a class exported by luabind. A user
2442 data who's metatable contains a boolean member named ``__luabind_class`` is
2443 expected to be an instantiation of a luabind class.
2445 This means that if you make your own user data and tags its metatable with the
2446 exact same names, you can very easily fool luabind and crash the application.
2448 In the Lua registry, luabind keeps an entry called ``__luabind_classes``. It
2449 should not be removed or overwritten.
2451 In the global table, a variable called ``super`` is used every time a
2452 constructor in a lua-class is called. This is to make it easy for that
2453 constructor to call its base class' constructor. So, if you have a global
2454 variable named super it may be overwritten. This is probably not the best
2455 solution, and this restriction may be removed in the future.
2457 Luabind uses two upvalues for functions that it registers. The first is a
2458 userdata containing a list of overloads for the function, the other is a light
2459 userdata with the value 0x1337, this last value is used to identify functions
2460 registered by luabind. It should be virtually impossible to have such a pointer
2461 as secondary upvalue by pure chance. This means, if you are trying to replace
2462 an existing function with a luabind function, luabind will see that the
2463 secondary upvalue isn't the magic id number and replace it. If it can identify
2464 the function to be a luabind function, it won't replace it, but rather add
2465 another overload to it.
2467 Inside the luabind namespace, there's another namespace called detail. This
2468 namespace contains non-public classes and are not supposed to be used directly.
2474 What's up with __cdecl and __stdcall?
2475 If you're having problem with functions
2476 that cannot be converted from ``void (__stdcall *)(int,int)`` to
2477 ``void (__cdecl*)(int,int)``. You can change the project settings to make the
2478 compiler generate functions with __cdecl calling conventions. This is
2479 a problem in developer studio.
2481 What's wrong with functions taking variable number of arguments?
2482 You cannot register a function with ellipses in its signature. Since
2483 ellipses don't preserve type safety, those should be avoided anyway.
2485 Internal structure overflow in VC
2486 If you, in visual studio, get fatal error C1204: compiler limit :
2487 internal structure overflow. You should try to split that compilation
2488 unit up in smaller ones. See `Splitting up the registration`_ and
2489 `Splitting class registrations`_.
2491 What's wrong with precompiled headers in VC?
2492 Visual Studio doesn't like anonymous namespace's in its precompiled
2493 headers. If you encounter this problem you can disable precompiled
2494 headers for the compilation unit (cpp-file) that uses luabind.
2496 error C1076: compiler limit - internal heap limit reached in VC
2497 In visual studio you will probably hit this error. To fix it you have to
2498 increase the internal heap with a command-line option. We managed to
2499 compile the test suit with /Zm300, but you may need a larger heap then
2502 error C1055: compiler limit \: out of keys in VC
2503 It seems that this error occurs when too many assert() are used in a
2504 program, or more specifically, the __LINE__ macro. It seems to be fixed by
2505 changing /ZI (Program database for edit and continue) to /Zi
2508 How come my executable is huge?
2509 If you're compiling in debug mode, you will probably have a lot of
2510 debug-info and symbols (luabind consists of a lot of functions). Also,
2511 if built in debug mode, no optimizations were applied, luabind relies on
2512 that the compiler is able to inline functions. If you built in release
2513 mode, try running strip on your executable to remove export-symbols,
2514 this will trim down the size.
2516 Our tests suggests that cygwin's gcc produces much bigger executables
2517 compared to gcc on other platforms and other compilers.
2519 .. HUH?! // check the magic number that identifies luabind's functions
2521 Can I register class templates with luabind?
2522 Yes you can, but you can only register explicit instantiations of the
2523 class. Because there's no Lua counterpart to C++ templates. For example,
2524 you can register an explicit instantiation of std::vector<> like this::
2528 class_<std::vector<int> >("vector")
2529 .def(constructor<int>)
2530 .def("push_back", &std::vector<int>::push_back)
2533 .. Again, irrelevant to docs: Note that the space between the two > is required by C++.
2535 Do I have to register destructors for my classes?
2536 No, the destructor of a class is always called by luabind when an
2537 object is collected. Note that Lua has to own the object to collect it.
2538 If you pass it to C++ and gives up ownership (with adopt policy) it will
2539 no longer be owned by Lua, and not collected.
2541 If you have a class hierarchy, you should make the destructor virtual if
2542 you want to be sure that the correct destructor is called (this apply to C++
2545 .. And again, the above is irrelevant to docs. This isn't a general C++ FAQ. But it saves us support questions.
2547 Fatal Error C1063 compiler limit \: compiler stack overflow in VC
2548 VC6.5 chokes on warnings, if you are getting alot of warnings from your
2549 code try suppressing them with a pragma directive, this should solve the
2552 Crashes when linking against luabind as a dll in Windows
2553 When you build luabind, Lua and you project, make sure you link against
2554 the runtime dynamically (as a dll).
2556 I cannot register a function with a non-const parameter
2557 This is because there is no way to get a reference to a Lua value. Have
2558 a look at out_value_ and pure_out_value_ policies.
2564 - You cannot use strings with extra nulls in them as member names that refers
2567 - If one class registers two functions with the same name and the same
2568 signature, there's currently no error. The last registered function will
2569 be the one that's used.
2571 - In VC7, classes can not be called test.
2573 - If you register a function and later rename it, error messages will use the
2574 original function name.
2576 - luabind does not support class hierarchies with virtual inheritance. Casts are
2577 done with static pointer offsets.
2583 Written by Daniel Wallin and Arvid Norberg. © Copyright 2003.
2584 All rights reserved.
2586 Evan Wies has contributed with thorough testing, countless bug reports
2589 This library was highly inspired by Dave Abrahams' Boost.Python_ library.
2591 .. _Boost.Python: http://www.boost.org/libraries/python