Luabind 0.9

Luabind 0.9 has been sitting on the GitHub tip (http://github.com/luabind/luabind/commits/master)
for a couple months now.

I have migrated to using it and wrote up some of the differences (from Luabind 0.7).   There are a
lot of great changes, but little publicity.  Nice work, Daniel!

I hope you all find this useful.  Some of it is Debian/Ubuntu specific, but most is general.  It is
formatted in a Trac-wiki style (from our internal Trac).

-Evan


= Transitioning to Luabind 0.9 =

We recently migrated from Luabind 0.7 to Luabind 0.9 (skipping 0.8).  Under the hood, these versions
are significantly different.  There are some breaking changes, as well as improvements, which are
outlined here.

=== LUBAIND_VERSION is now 900 ===

{{{
#!cpp
// in <luabind/version.hpp>
// previous was 701
# define LUABIND_VERSION 900
}}}

=== include path is now <luabind/> ===

In our packaged version of Luabind 0.7, the include path used to be <luabind5.1/>.  To match
upstream and Debian, we now use the path <luabind/>.  So for example:

{{{
#!cpp
#include <luabind5.1/luabind.hpp>   // OLD way... will not work anymore
#include <luabind/luabind.hpp>      // NEW way... do this.
}}}

=== bool cast of luabind::object ===

In Luabind 0.7, casting a luabind::object to bool used to check to see if the underlying Lua
interpreter for the object was valid.   The new behavior is to invoke lua_toboolean on the object.

=== super() deprecation ===

When binding classes to Lua, you used to have to invoke the super().  This is deprecated and will be
removed in a future release.  (You can invoke {{{luabind::disable_super_deprecation()}}} for
compatibility.)   Instead you should call the base class !__init function yourself:

{{{
#!lua
class 'Derived' (Base)

function Derived:__init()
    Base.__init(self)
end
}}}

=== shared_ptr and casting ===

One of the most exciting changes is that shared_ptr holders (and any held pointer like
intrusive_ptr) works much better now.  There is no more need for shared_ptr_policy.  There is no
need for casting in Lua.

Here's how shared_ptr_policy used to be needed and how it is expressed now:
{{{
#!cpp
// OLD way
#include <luabind/shared_ptr_policy.hpp>
luabind::class_<DerivedClass, BaseClass, shared_ptr<BaseClass> >("BaseClass")
    .def( luabind::constructor<>() )
    .def_readwrite("a",       &Derived::m_a)
    .def_readwrite("b",       &Derived::m_b,
            luabind::shared_ptr_policy<const OtherClassB>(_2),
            luabind::shared_ptr_policy<OtherClassB>(_2))

// NEW way
luabind::class_<DerivedClass, BaseClass, shared_ptr<BaseClass> >("BaseClass")
    .def( luabind::constructor<>() )
    .def_readwrite("a",       &Derived::m_a)
    .def_readwrite("b",       &Derived::m_b)  // it "just works"

}}}

In Lua, things are much easier now.  There used to be a need to write upcasting and downcasting
functions, and shared_ptrs didn't totally work in all situations.

A note from Daniel Wallin on these features:
{{{
Most notably any smart pointer can now automatically be passed to Lua. For
instance:

  struct X
  {};

  boost::intrusive_ptr<X> make();

  class_<X>("X");

will Just Work. The default holders specification on class_<>:

  class_<X, boost::intrusive_ptr<X> >("X")

now only specifies the *default* smart pointer that objects constructed
in Lua is held by.

The other change that you may be interested in is that
shared_ptr-converter automatically works, just:

 #include <luabind/shared_ptr_converter.hpp>

to get automatic up/down-casts and lifetime management of Lua objects
for any boost::shared_ptr. No policies necessary.
}}}

=== introspection via class_info ===

There is introspection now via a function called class_info:
{{{
#!lua
c = class_info(Timeval())
print(c.name)
-- Timeval
for k,v in pairs(c.attributes) do print(k,v) end
-- 1    usec
---2    sec

-- Here is the class_info for class_info
c = class_info(class_info(Timeval()))
print(c.name)
-- class_info_data
for k,v in pairs(c.attributes) do print(k,v) end
-- 1    attributes
-- 2    name
-- 3    methods
for k,v in pairs(c.methods) do print(k,v) end
--
}}}

=== luabind::table wrapper ===

There is a new object called luabind::table that is like luabind::object, but restricts the
parameter to Lua tables.  Here's the
[http://github.com/luabind/luabind/commit/2be3bf2237c48775e62b46ab97b030cafbddbc48 Luabind
changeset].   I have not used this but I'm letting you know it is there.



------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference