|
From: Arvid N. <ar...@us...> - 2005-11-28 20:55:47
|
Update of /cvsroot/luabind/luabind/luabind/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv15879/luabind/doc Modified Files: docs.html docs.rst Added Files: changes.txt Log Message: merged in changes from beta7-devel2 (tag: beta7-devel2-merge) Index: docs.html =================================================================== RCS file: /cvsroot/luabind/luabind/luabind/doc/docs.html,v retrieving revision 1.52 retrieving revision 1.53 diff -u -d -r1.52 -r1.53 --- docs.html 10 Aug 2004 22:27:06 -0000 1.52 +++ docs.html 28 Nov 2005 20:55:33 -0000 1.53 @@ -1,13 +1,13 @@ -<?xml version="1.0" encoding="Latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> -<meta http-equiv="Content-Type" content="text/html; charset=Latin1" /> -<meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" /> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" /> <title>luabind</title> <meta name="author" content="Daniel Wallin, Arvid Norberg" /> [...2290 lines suppressed...] </div> <div class="section" id="acknowledgments"> -<h1><a name="acknowledgments">19 Acknowledgments</a></h1> -<p>Written by Daniel Wallin and Arvid Norberg. © Copyright 2003. +<h1><a name="acknowledgments">19 Acknowledgments</a></h1> +<p>Written by Daniel Wallin and Arvid Norberg. © Copyright 2003. All rights reserved.</p> <p>Evan Wies has contributed with thorough testing, countless bug reports and feature ideas.</p> <p>This library was highly inspired by Dave Abrahams' <a class="reference" href="http://www.boost.org/libraries/python">Boost.Python</a> library.</p> </div> </div> -<hr class="footer" /> -<div class="footer"> -<a class="reference" href="docs.rst">View document source</a>. -Generated on: 2004-08-10 22:26 UTC. -Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. -</div> </body> </html> Index: docs.rst =================================================================== RCS file: /cvsroot/luabind/luabind/luabind/doc/docs.rst,v retrieving revision 1.25 retrieving revision 1.26 diff -u -d -r1.25 -r1.26 --- docs.rst 19 Jan 2005 08:24:49 -0000 1.25 +++ docs.rst 28 Nov 2005 20:55:33 -0000 1.26 @@ -36,6 +36,7 @@ .. contents:: :depth: 2 + :backlinks: none .. section-numbering:: Introduction @@ -62,6 +63,11 @@ We are very interested in hearing about projects that use luabind, please let us know about your project. +The main channel for help and feedback is the `luabind mailing list`_. +There's also an IRC channel ``#luabind`` on irc.freenode.net. + +.. _`luabind mailing list`: https://lists.sourceforge.net/lists/listinfo/luabind-user + Features ======== @@ -97,7 +103,9 @@ - GCC 3.0.4 (Debian/Linux) - GCC 3.1 (SunOS 5.8) - GCC 3.2 (cygwin) - - GCC 3.3.1 (cygwin) + - GCC 3.3.1 (cygwin) + - GCC 3.3 (Apple, MacOS X) + - GCC 4.0 (Apple, MacOS X) It has been confirmed not to work with: @@ -117,8 +125,8 @@ To keep down the compilation-time luabind is built as a library. This means you have to either build it and link against it, or include its source files in your project. You also have to make sure the luabind directory is somewhere in -your compiler's include path. It requires `Boost`_ 1.31.0 to be installed (only -boost headers). It also requires that Lua is installed. +your compiler's include path. It requires `Boost`_ 1.32.0 or 1.33.0 to be +installed (only boost headers). It also requires that Lua is installed. The official way of building luabind is with `Boost.Build V2`_. To properly build luabind with Boost.Build you need to set two environment variables: @@ -132,7 +140,7 @@ ``$(LUA_PATH)/lib/.`` For backward compatibility, there is also a makefile in the root-directory that -will build the library and the test program. If you are using a UNIX-system (or +will build the library and the test programs. If you are using a UNIX-system (or cygwin) they will make it easy to build luabind as a static library. If you are using Visual Studio it may be easier to include the files in the src directory in your project. @@ -392,8 +400,8 @@ Calling Lua functions --------------------- -To call a Lua function, you can either use ``call_function()``, -an ``object`` or ``functor``. +To call a Lua function, you can either use ``call_function()`` or +an ``object``. :: @@ -432,6 +440,9 @@ int ret = call_function(L, "fun", boost::ref(val)); +If you want to use a custom error handler for the function call, see +``set_pcall_callback`` under Configuration_. + Using Lua threads ----------------- @@ -536,6 +547,39 @@ const member function (it can be called on const objects). +Overloaded member functions +--------------------------- + +When binding more than one overloads of a member function, or just binding +one overload of an overloaded member function, you have to disambiguate +the member function pointer you pass to ``def``. To do this, you can use an +ordinary C-style cast, to cast it to the right overload. To do this, you have +to know how to express member function types in C++, here's a short tutorial +(for more info, refer to your favourite book on C++). + +The syntax for member function pointer follows: + +.. parsed-literal:: + + *return-value* (*class-name*::\*)(*arg1-type*, *arg2-type*, *...*) + +Here's an example illlustrating this:: + + struct A + { + void f(int); + void f(int, int); + }; + +:: + + class_<A>() + .def("f", (void(A::*)(int))&A::f) + +This selects the first overload of the function ``f`` to bind. The second +overload is not bound. + + Properties ---------- @@ -561,9 +605,28 @@ module(L) [ class_<A>("A") - .def_readonly("a", &A::a) + .def_readonly("a", &A::a) ]; +When binding members that are a non-primitive type, the auto generated getter +function will return a reference to it. This is to allow chained .-operators. +For example, when having a struct containing another struct. Like this:: + + struct A { int m; }; + struct B { A a; }; + +When binding ``B`` to lua, the following expression code should work:: + + b = B() + b.a.m = 1 + assert(b.a.m == 1) + +This requires the first lookup (on ``a``) to return a reference to ``A``, and +not a copy. In that case, luabind will automatically use the dependency policy +to make the return value dependent on the object in which it is stored. So, if +the returned reference lives longer than all references to the object (b in +this case) it will keep the object alive, to avoid being a dangling pointer. + You can also register getter and setter functions and make them look as if they were a public data member. Consider the following class:: @@ -584,7 +647,8 @@ This way the ``get_a()`` and ``set_a()`` functions will be called instead of just writing to the data member. If you want to make it read only you can just -omit the last parameter. +omit the last parameter. Please note that the get function **has to be +const**, otherwise it won't compile. This seems to be a common source of errors. Enums @@ -621,6 +685,8 @@ Operators --------- +To bind operators you have to include ``<luabind/operator.hpp>``. + The mechanism for registering operators on your class is pretty simple. You use a global name ``luabind::self`` to refer to the class itself and then you just write the operator expression inside the ``def()`` call. This class:: @@ -643,7 +709,7 @@ This will work regardless if your plus operator is defined inside your class or as a free function. -If you operator is const (or, when defined as a free function, takes a const +If your operator is const (or, when defined as a free function, takes a const reference to the class itself) you have to use ``const_self`` instead of ``self``. Like this: @@ -659,12 +725,17 @@ .. parsed-literal:: - + - \* / == != < <= > >= + + - \* / == < <= This means, no in-place operators. The equality operator (``==``) has a little hitch; it will not be called if the references are equal. This means that the ``==`` operator has to do pretty much what's it's expected to do. +Lua does not support operators such as ``!=``, ``>`` or ``>=``. That's why you +can only register the operators listed above. When you invoke one of the +mentioned operators, lua will define it in terms of one of the avaliable +operators. + In the above example the other operand type is instantiated by writing ``int()``. If the operand type is a complex type that cannot easily be instantiated you can wrap the type in a class called ``other<>``. For example: @@ -689,7 +760,7 @@ .def(self + **other<std::string>()**) ]; -To register an application operator: +To register an application (function call-) operator: .. parsed-literal:: @@ -702,7 +773,7 @@ There's one special operator. In Lua it's called ``__tostring``, it's not really an operator. It is used for converting objects to strings in a standard way in Lua. If you register this functionality, you will be able to use the lua -standard function ``tostring()`` for converting you object to a string. +standard function ``tostring()`` for converting your object to a string. To implement this operator in C++ you should supply an ``operator<<`` for std::ostream. Like this example: @@ -737,6 +808,9 @@ def("f", &f) ]**; +In this example, ``f`` will behave like a static member function of the class +``foo``, and the class ``nested`` will behave like a nested class of ``foo``. + It's also possible to add namespace's to classes using the same syntax. @@ -798,7 +872,7 @@ namespace luabind { template<class T> - T* get_pointer(boost::shared_ptr<T> const& p) + T* get_pointer(boost::shared_ptr<T>& p) { return p.get(); } @@ -811,6 +885,11 @@ } } +The second function will only be used to get a compile time mapping +of ``boost::shared_ptr<A>`` to its const version, +``boost::shared_ptr<const A>``. It will never be called, so the +return value doesn't matter (only the return type). + The conversion that works are (given that B is a base class of A): .. topic:: From Lua to C++ @@ -840,10 +919,10 @@ ``holder_type<A const> const&`` ``holder_type<A const>`` =============================== ======================== -When using a holder type, it can be useful to know if the pointer is valid. For -example when using std::auto_ptr, the holder will be invalidated when passed as -a parameter to a function. For this purpose there is a member of all object -instances in luabind: ``__ok``. :: +When using a holder type, it can be useful to know if the pointer is valid +(i.e. not null). For example when using std::auto_ptr, the holder will be +invalidated when passed as a parameter to a function. For this purpose there +is a member of all object instances in luabind: ``__ok``. :: struct X {}; void f(std::auto_ptr<X>); @@ -865,13 +944,66 @@ false +When registering a hierarchy of classes, where all instances are to be held +by a smart pointer, all the classes should have the baseclass' holder type. +Like this: + +.. parsed-literal:: + + module(L) + [ + class_<base, boost::shared_ptr<base> >("base") + .def(constructor<>()), + class_<derived, base, **boost::shared_ptr<base>** >("base") + .def(constructor<>()) + ]; + +Internally, luabind will do the necessary conversions on the raw pointers, which +are first extracted from the holder type. + + +Splitting class registrations +----------------------------- + +In some situations it may be desirable to split a registration of a class +across different compilation units. Partly to save rebuild time when changing +in one part of the binding, and in some cases compiler limits may force you +to split it. To do this is very simple. Consider the following sample code:: + + void register_part1(class_<X>& x) + { + x.def(/*...*/); + } + + void register_part2(class_<X>& x) + { + x.def(/*...*/); + } + + void register_(lua_State* L) + { + class_<X> x("x"); + + register_part1(x); + register_part2(x); + + module(L) [ x ]; + } + +Here, the class ``X`` is registered in two steps. The two functions +``register_part1`` and ``register_part2`` may be put in separate compilation +units. + +To separate the module registration and the classes to be registered, see +`Splitting up the registration`_. + Object ====== Since functions have to be able to take Lua values (of variable type) we need a wrapper around them. This wrapper is called ``luabind::object``. If the function you register takes an object, it will match any Lua value. To use it, -you need to include ``luabind/object.hpp``. +you need to include ``<luabind/object.hpp>``. .. topic:: Synopsis @@ -880,46 +1012,26 @@ class object { public: - class iterator; - class raw_iterator; - class array_iterator; - template<class T> object(lua_State\*, T const& value); + object(from_stack const&); object(object const&); - object(lua_State\*); object(); ~object(); - - iterator begin() const; - iterator end() const; - raw_iterator raw_begin() const; - raw_iterator raw_end() const; - array_iterator abegin() const; - array_iterator aend() const; - void set(); - lua_State\* lua_state() const; - void pushvalue() const; + lua_State\* interpreter() const; + void push() const; bool is_valid() const; - operator safe_bool_type() const; + operator *safe_bool_type* () const; template<class Key> *implementation-defined* operator[](Key const&); - template<class Key> - object at(Key const&) const; - - template<class Key> - object raw_at(Key const&) const; - template<class T> object& operator=(T const&); object& operator=(object const&); - template<class T> - bool operator==(T const&) const; bool operator==(object const&) const; bool operator<(object const&) const; bool operator<=(object const&) const; @@ -927,8 +1039,10 @@ bool operator>=(object const&) const; bool operator!=(object const&) const; + template <class T> + *implementation-defined* operator[](T const& key) const + void swap(object&); - int type() const; *implementation-defined* operator()(); @@ -944,33 +1058,35 @@ When you have a Lua object, you can assign it a new value with the assignment operator (=). When you do this, the ``default_policy`` will be used to make the conversion from C++ value to Lua. If your ``luabind::object`` is a table you -can access its members through the operator[] or the iterators. The value +can access its members through the operator[] or the Iterators_. The value returned from the operator[] is a proxy object that can be used both for reading and writing values into the table (using operator=). Note that it is impossible to know if a Lua value is indexable or not (lua_gettable doesn't fail, it succeeds or crashes). This means that if you're trying to index something that cannot be indexed, you're on your own. Lua will call its ``panic()`` function (you can define your own panic function using -``lua_setpanicf``). The ``at()`` and ``raw_at()`` functions returns the value at -the given table position (like operator[] but only for reading). +``lua_setpanicf``). There are also free functions that can be used for +indexing the table, see `Related functions`_. -The ordinary ``object::iterator`` uses lua_gettable to extract the values from -the table, the standard way that will invoke metamethods if any. The -``object::raw_iterator`` uses lua_rawget and ``object::array_iterator`` uses -lua_rawgeti. The latter will only iterate over numerical keys starting at 1 -and continue until the first nil value. +The constructor that takes a ``from_stack`` object is used when you want to +initialize the object with a value from the lua stack. The ``from_stack`` +type has the following constructor:: -The ``lua_state()`` function returns the Lua state where this object is stored. + from_stack(lua_State* L, int index); + +The index is an ordinary lua stack index, negative values are indexed from the +top of the stack. You use it like this:: + + object o(from_stack(L, -1)); + +This will create the object ``o`` and copy the value from the top of the lua stack. + +The ``interpreter()`` function returns the Lua state where this object is stored. If you want to manipulate the object with Lua functions directly you can push -it onto the Lua stack by calling ``pushvalue()``. And set the object's value by -calling ``set()``, which will pop the top value from the Lua stack and assign -it to the object. +it onto the Lua stack by calling ``push()``. The operator== will call lua_equal() on the operands and return its result. -The ``type()`` member function will return the Lua type of the object. It will -return the same values as lua_type(). - The ``is_valid()`` function tells you whether the object has been initialized or not. When created with its default constructor, objects are invalid. To make an object valid, you can assign it a value. If you want to invalidate an object @@ -1024,9 +1140,9 @@ Here's an example of how a function can use a table:: - void my_function(const object& table) + void my_function(object const& table) { - if (table.type() == LUA_TTABLE) + if (type(table) == LUA_TTABLE) { table["time"] = std::clock(); table["name"] = std::rand() < 500 ? "unusual" : "usual"; @@ -1043,165 +1159,121 @@ Iterators --------- -The iterators, that are returned by ``begin()`` and ``end()`` (and their -variants) are (almost) models of the ForwardIterator concept. The exception -is that post increment doesn't exist on them. +There are two kinds of iterators. The normal iterator that will use the metamethod +of the object (if there is any) when the value is retrieved. This iterator is simply +called ``luabind::iterator``. The other iterator is called ``luabind::raw_iterator`` +and will bypass the metamethod and give the true contents of the table. They have +identical interfaces, which implements the ForwardIterator_ concept. Apart from +the members of standard iterators, they have the following members and constructors: -They look like this +.. _ForwardIterator: http://www.sgi.com/tech/stl/ForwardIterator.html .. parsed-literal:: - class object::iterator + class iterator { iterator(); - iterator(const iterator&); - - iterator& operator++(); - bool operator!=(const iterator&) const; - iterator& operator=(const iterator&); + iterator(object const&); object key() const; - *implementation-defined* operator*(); + *standard iterator members* }; -The implementation defined return value from the dereference operator is a -proxy object that can be used as if it was an object, it can also be used to -assign the specific table entry with a new value. If you want to assign a value -to an entry pointed to by an iterator, just use the assignment operator on the -dereferenced iterator:: +The constructor that takes a ``luabind::object`` is actually a template that can be +used with object. Passing an object as the parameter to the iterator will +construct the iterator to refer to the first element in the object. - *iter = 5; +The default constructor will initialize the iterator to the one-past-end +iterator. This is used to test for the end of the sequence. +The value type of the iterator is an implementation defined proxy type which +supports the same operations as ``luabind::object``. Which means that in most +cases you can just treat it as an ordinary object. The difference is that any +assignments to this proxy will result in the value being inserted at the +iterators position, in the table. + The ``key()`` member returns the key used by the iterator when indexing the associated Lua table. +An example using iterators:: -Related functions ------------------ - -There are a couple of functions related to objects and tables. :: - - T object_cast<T>(object const&); - T object_cast<T>(object const&, Policies); - - boost::optional<T> object_cast_nothrow<T>(object const&); - boost::optional<T> object_cast_nothrow<T>(object const&, Policies); - - -Functor -------- - -The ``functor`` class is similar to object, with the exception that it can only -be used to store functions. If you take it as a parameter, it will only match -functions. - -To use it you need to include its header:: - - #include <luabind/functor.hpp> - -It takes one template parameter, the return value of the Lua function it -represents. Currently the functor can have at most one return value (unlike Lua -functions). - -.. topic:: Synopsis - - .. parsed-literal:: - - template<class Ret> - class functor - { - public: - - functor(lua_State\*, char const* name); - functor(functor const&); - ~functor(); + for (iterator i(globals(L)["a"]), end; i != end; ++i) + { + *i = 1; + } - bool is_valid() const; - operator safe_bool_type() const; - void reset(); +The iterator named ``end`` will be constructed using the default constructor +and hence refer to the end of the sequence. This example will simply iterate +over the entries in the global table ``a`` and set all its values to 1. - lua_State\* lua_state() const; - void pushvalue() const; - - bool operator==(functor<Ret> const&); - bool operator!=(functor<Ret> const&); - - *implementation-defined* operator()() const; - - template<class A0> - *implementation-defined* operator()(A0 const&) const; +Related functions +----------------- - template<class A0, class A1> - *implementation-defined* operator()(A0 const&, A1 const&) const; +There are a couple of functions related to objects and tables. - /\* ... \*/ - }; +:: -The application operator takes any parameters. The parameters are converted -into Lua and the function is called. The return value will act as if it was the -type Ret, with the exception that you can use the return value to give policies -to the call. You do this the same way as you do with objects, using the -operator[], and giving the policies inside the brackets. + int type(object const&); -The ``is_valid()`` function works just like the one on object, it tells you if -the functor has been assigned with a valid Lua function. The ``operator -safe_bool_type()`` is an alias for this member function and also works just as -the one found in object. +This function will return the lua type index of the given object. +i.e. ``LUA_TNIL``, ``LUA_TNUMBER`` etc. -For example, if you have the following Lua function:: +:: - function f(a, b) - return a + b - end + template<class T, class K> + void settable(object const& o, K const& key, T const& value); + template<class K> + object gettable(object const& o, K const& key); + template<class T, class K> + void rawset(object const& o, K const& key, T const& value); + template<class K> + object rawget(object const& o, K const& key); -You can expose it to C++ like this:: +These functions are used for indexing into tables. ``settable`` and ``gettable`` +translates into calls to ``lua_settable`` and ``lua_gettable`` respectively. Which +means that you could just as well use the index operator of the object. - functor<int> f(L, "f"); +``rawset`` and ``rawget`` will translate into calls to ``lua_rawset`` and +``lua_rawget`` respectively. So they will bypass any metamethod and give you the +true value of the table entry. - std::cout << f(3, 5) << "\n"; +:: -This will print out the sum of 3 and 5. Note that you can pass any parameters -to the application operator of ``luabind::functor``, this is because lua -doesn't have signatures for its functions. All Lua functions take any number of -parameters of any type. + template<class T> + T object_cast<T>(object const&); + template<class T, class Policies> + T object_cast<T>(object const&, Policies); -If we have a C++ function that takes a ``luabind::functor`` and registers it, -it will accept Lua functions passed to it. This enables us to expose APIs that -requires you to register callbacks. For example, if your C++ API looks like -this:: + template<class T> + boost::optional<T> object_cast_nothrow<T>(object const&); + template<class T, class Policies> + boost::optional<T> object_cast_nothrow<T>(object const&, Policies); - void set_callback(void(*)(int, int)); +The ``object_cast`` function casts the value of an object to a C++ value. +You can supply a policy to handle the conversion from lua to C++. If the cast +cannot be made a ``cast_failed`` exception will be thrown. If you have +defined LUABIND_NO_ERROR_CHECKING (see configuration) no checking will occur, +and if the cast is invalid the application may very well crash. The nothrow +versions will return an uninitialized ``boost::optional<T>`` object, to +indicate that the cast could not be performed. -And you want to expose it to Lua, you have to wrap the call to the Lua -function inside a real C++ function, like this:: +The function signatures of all of the above functions are really templates +for the object parameter, but the intention is that you should only pass +objects in there, that's why it's left out of the documentation. - functor<void> lua_callback; +:: - void callback_wrapper(int a, int b) - { - lua_callback(a, b); - } + object globals(lua_State*); + object registry(lua_State*); - void set_callback_wrapper(const functor<void>& f) - { - lua_callback = f; - set_callback(&callback_wrapper); - } +These functions return the global environment table and the registry table respectively. -And then register ``set_callback_wrapper`` instead of registering -``set_callback``. This will have the effect that when one tries to register the -callback from Lua, your ``set_callback_wrapper`` will be called instead and -first set the Lua functor to the given function. It will then call the real -``set_callback`` with the ``callback_wrapper``. The ``callback_wrapper`` will -be called whenever the callback should be called, and it will simply call the -Lua function that we registered. +:: -You can also use ``object_cast`` to cast an object to a functor. + object newtable(lua_State*); -``reset`` on ``functor`` will invalidate the functor (and remove any references -to its Lua value). If the functor object has longer lifetime than the lua state -(e.g. if it's a global). +This function creates a new table and returns it as an object. Defining classes in Lua @@ -1584,10 +1656,10 @@ } There's another exception that luabind may throw: ``luabind::cast_failed``, -this exception is thrown from ``call_function<>``, ``call_member<>`` or when -``functor<>`` is invoked. It means that the return value from the Lua function -couldn't be converted to a C++ value. It is also thrown from ``object_cast<>`` -if the cast cannot be made. +this exception is thrown from ``call_function<>`` or ``call_member<>``. It +means that the return value from the Lua function couldn't be converted to +a C++ value. It is also thrown from ``object_cast<>`` if the cast cannot +be made. The synopsis for ``luabind::cast_failed`` is:: @@ -2047,8 +2119,8 @@ As mentioned in the `Lua documentation`_, it is possible to pass an error handler function to ``lua_pcall()``. Luabind makes use of -``lua_pcall()`` internally when calling methods and functions. It is -possible to set the error handler function that Luabind will use +``lua_pcall()`` internally when calling member functions and free functions. +It is possible to set the error handler function that Luabind will use globally:: typedef void(*pcall_callback_fun)(lua_State*); @@ -2099,7 +2171,7 @@ was called. Functions will still be able to throw exceptions when error checking is disabled. - If a functions throws an exception it will be caught by luabind and + If a function throws an exception it will be caught by luabind and propagated with ``lua_error()``. LUABIND_NO_EXCEPTIONS @@ -2123,7 +2195,8 @@ LUABIND_EXPORT, LUABIND_IMPORT If you want to link against luabind as a dll (in devstudio), you can define ``LUABIND_EXPORT`` to ``__declspec(dllexport)`` and - ``LUABIND_IMPORT`` to ``__declspec(dllimport)``. + ``LUABIND_IMPORT`` to ``__declspec(dllimport)`` or + ``__attribute__ ((visibility("default")))`` on GCC 4. Note that you have to link against Lua as a dll aswell, to make it work. LUABIND_NO_RTTI @@ -2216,8 +2289,8 @@ the attribute '*class-name.attribute-name*' is read only There is no data member named *attribute-name* in the class *class-name*, - or there's no setter-method registered on that property name. See the - properties section. + or there's no setter-function registered on that property name. See the + Properties_ section. - .. parsed-literal:: @@ -2282,7 +2355,8 @@ Internal structure overflow in VC If you, in visual studio, get fatal error C1204: compiler limit : internal structure overflow. You should try to split that compilation - unit up in smaller ones. + unit up in smaller ones. See `Splitting up the registration`_ and + `Splitting class registrations`_. .. the three entries above were removed, why? @@ -2340,7 +2414,7 @@ you want to be sure that the correct destructor is called (this apply to C++ in general). -.. And again, the above is irrelevant to docs. This isn't a general C++ FAQ. +.. And again, the above is irrelevant to docs. This isn't a general C++ FAQ. But it saves us support questions. Fatal Error C1063 compiler limit \: compiler stack overflow in VC VC6.5 chokes on warnings, if you are getting alot of warnings from your @@ -2353,7 +2427,7 @@ I cannot register a function with a non-const parameter This is because there is no way to get a reference to a Lua value. Have - a look at out_value and pure_out_value policies. + a look at out_value_ and pure_out_value_ policies. Known issues --- NEW FILE: changes.txt --- LUABIND BETA 7 changes ====================== We have introduced a change that may break current code, nothing will break silently however. The change is that the previous way of writing virtual class wrappers was to have it contain an object that refered to the actual lua object. This would cause a dependency cycle and result in the object never being garbage collected until the whole lua state was closed. The new way is to use a newly introduced type called weak_ref, instead of the object. See docs for more info. Changes from beta6 ------------------ * renamed get_globals() and get_registry() to globals() and registry() * rewrote object and made a few changes: * moved iterators out of the class and removed begin/end/raw_begin/raw_end/array_begin/array_end. See updated docs for how to use the iterators. * removed array_iterator alltogether * renamed pushvalue() to push() * removed set() * replaced the constructor that creates an object from a stack value (with better syntax) * moved out the member functions type(), at() and raw_at() and made them free functions. (type(), gettable(), settable(), rawget() and rawset()) * renamed lua_state() to interpreter() * object now supports nested indexing (with []-operator) as well as function calls directly on indexed values (i.e. globals(L)["my_fun"](10)). The indexing has also been made more efficient through the use of expression templates. * removed functor (use object with call_function() instead) * using boost-build, and has better support for building as a dll. The makefiles still works. * removed the option LUABIND_DONT_COPY_STRING, this means that luabind will not provide storage for name strings. i.e. the strings sent to module, namespace_ and class_ are expected to have global storage (it's no problem as long as you use string constants) wrappers ........ Wrapper classes now have to derive from wrap_base and they don't have to contain any references to the lua-part (this is done by the base class now). The overload of call_member() that previuosly took a weak_ref as first parameter is now a member function of the wrap_base class and no longer takes the self reference argument. Example: struct A { virtual ~A() {} virtual std::string f() { return "A:f()"; } }; struct A_wrap : A, wrap_base { virtual std::string f() { return call_member<std::string>("f"); } static std::string default_f(A* p) { return p->A::f(); } }; The changes when registering the virtual functions is that you now have to register both the virtual function _and_ the default implementation of the function (for static dispatch). Like this: module(L) [ class_<A, A_wrap>("A") .def(constructor<>()) .def("f", &A::f, &A_wrap::default_f) ] If you update your luabind version without changing the way you register virtual functions, it will still compile, but may give you runtime errors. With these changes adopt will work as expected on wrapped types (the weak reference will be transformed into a strong reference internally). These changes will also make dynamic function dispatch work from within lua (and not just from c++ into lua). policy placeholders ................... luabind now handles member functions in a more general way. The self reference that is passed as first parameter to member functions is now refered to using the _1 placeholder (instead of self). This means that the first argument to a member function is refered to with _2. additions ......... * added __newindex metatable entry on c++ classes * moved more code into cpp-files (hopefully reduces user compile time slightly) * the iterators are now true models of ForwardIterator * error messages when writing non-matching type to a property or attribute. * support for inner scopes * support for nil to holder_type conversion * wrappers for lua_resume() with the same syntax as call_function() (resume_function() and resume()) bugfixes ........ * bugs in the overload resolution could give internal errors in some cases. * def_readonly and def_readwrite will now return references if the type is not a primitive type. This will allow chained . operators. * object_cast() of uninitialized objects works * supports strings with extra nulls in them (not for member names though) * fixed reference leakage by reducing the amount of explicit resource management. * fixed bug where matchers for getters and setters did not propagate to derived classes. * fixed leak when using class wrappers. They had a reference cycle that wouldn't get collected (until the lua_State was closed). * lots of other fixes we can't remember |
