doc/docs.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
   2
   3 <html>
   4 <head>
   5         <title>luabind beta documentation</title>
   6         <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   7         <link href="style.css" type="text/css" rel="stylesheet">
   8 </head>
   9
  10 <body>
  11
  12 <p>This library is currently in public beta phase. This documentation should be considered beta as well.
  13 Please report any grammatic corrections/spelling corrections.</p>
  14
  15 <h1>Table of contents</h1>
  16
  17 <ol>
  18         <li><a href="#intro">Introduction</a>
  19         <ul>
  20                 <li><a href="#features">features</a>
  21                 <li><a href="#compilers">tested compilers</a>
  22         </ul>
  23         <li><a href="#basic">Basic usage</a>
  24         <li><a href="#fun">Binding functions to lua</a>
  25         <ul>
  26                 <li><a href="#fun_overload">overloaded functions</a>
  27                 <li><a href="#fun_sigmatch">signature matching</a>
  28                 <li><a href="#fun_exception">exceptions</a>
  29                 <li><a href="#lua_fun">calling lua functions</a>
  30         </ul>
  31         <li><a href="#bind_classes">Binding classes to lua</a>
  32         <ul>
  33                 <li><a href="#class_property">properties</a>
  34                 <li><a href="#class_enum">enums</a>
  35                 <li><a href="#class_operator">operators</a>
  36                 <li><a href="#class_derived">derived classes</a>
  37         </ul>
  38         <li><a href="#object">Value wrapper</a>
  39         <ul>
  40                 <li><a href="#wrap_fun">related functions</a>
  41                 <li><a href="#functor">functor</a>
  42         </ul>
  43         <li><a href="#class_lua" >Defining classes in lua</a>
  44         <ul>
  45                 <li><a href="#class_lua_derive">deriving in lua</a>
  46         </ul>
  47         <li><a href="#policies" >Parameter policies</a>
  48         <ul>
  49                 <li><a href="#policies_copy">copy</a>
  50                 <li><a href="#policies_adopt">adopt</a>
  51                 <li><a href="#policies_dependency">dependency</a>
  52                 <li><a href="#policies_return_ref">return_reference_to</a>
  53                 <li><a href="#policies_out">out_value</a>
  54                 <li><a href="#policies_pure_out">pure_out_value</a>
  55                 <li><a href="#policies_discard_result">discard_result</a>
  56                 <li><a href="#policies_custom">custom</a>
  57                 <li><a href="#policies_user_converter">user defined converter</a>
  58         </ul>
  59         <li><a href="#config">Configuration</a>
  60         <li><a href="#implementation_notes">Implementation notes</a>
  61         <li><a href="#error_messages">Error messages</a>
  62         <li><a href="#faq">FAQ</a>
  63         <li><a href="#future">Future additions</a>
  64         <li><a href="#issues">Known issues</a>
  65         <li><a href="#acknowledgments">Acknowledgments</a>
  66 </ol>
  67
  68 <h1><a name="intro"></a>Introduction</h1>
  69
  70 <p>Luabind is a library that helps you create bindings
  71 between C++ and <a href="http://www.lua.org">lua</a>. It
  72 has the ability to expose functions and classes, written in C++, to lua. It will
  73 also supply the functionality to define classes in lua and let them derive from
  74 other lua classes or C++ classes. Lua classes can override virtual functions
  75 from their C++ baseclasses. It is written towards lua 5.0b, and does not work
  76 with lua 4.</p>
  77
  78 <p>It is implemented utilizing template meta programming.
  79 That means that you don't need an extra preprocess pass to compile your project
  80 (it is done by the compiler). It also means you don't (usually) have to know the
  81 exact signature of each function you register, since the library will generate
  82 code depending on the compile-time type of the function (which includes the
  83 signature). The main drawback of this approach is that the compilation time will
  84 increase for the file that does the registration, it is therefore recommended
  85 that you register everything in the same cpp-file.</p>
  86
  87 <p>luabind is released under the terms of the
  88 <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</p>
  89
  90 <p>We are very interested in hearing about projects that use luabind, please let
  91 us know about your project.</p>
  92
  93 <h2><a name="features"></a>features</h2>
  94
  95 <p>Luabind supports:</p>
  96 <ul>
  97         <li>overloaded free functions
  98         <li>C++ classes in lua
  99         <ul>
 100                 <li>overloaded member functions
 101                 <li>operators
 102                 <li>properties
 103                 <li>enums
 104         </ul>
 105         <li>lua functions in C++
 106         <li>lua classes in C++
 107         <li>lua classes (single inheritance)
 108         <ul>
 109                 <li>derives from lua or C++ classes
 110                 <li>override virtual functions from C++ classes
 111         </ul>
 112         <li>implicit casts between registered types
 113         <li>best match signature matching
 114         <li>return value policies and parameter policies
 115 </ul>
 116
 117 <h2><a name="compilers"></a>tested compilers</h2>
 118
 119 <p>Luabind has been tested to work on the following
 120 compilers:</p>
 121
 122 <ul>
 123         <li>Visual Studio 7.0
 124         <li>Visual Studio 6.0 (sp 5)
 125         <li>Intel C++ 6.0
 126         <li>GCC 2.95.3 (cygwin)
 127         <li>GCC 3.0.4 (Debian/Linux)
 128         <li>GCC 3.1 (SunOS 5.8)
 129         <li>GCC 3.2 (cygwin)
 130 </ul>
 131
 132 <p>It has been confirmed not to work with:</p>
 133
 134 <ul>
 135         <li>GCC 2.95.2 (SunOS 5.8)
 136         <li>Metrowerks 8.3
 137 </ul>
 138
 139 <p>If you have tried luabind with a compiler not listed here, let us know
 140 your result with it.</p>
 141
 142 <h1><a name="basic"></a>Basic usage</h1>
 143
 144 <p>To keep luabind easy to use, it's implemented in headers
 145 only, this means you don't have to install it nor build it to use it. You just
 146 have to make sure the <tt>luabind</tt> directory is
 147 somewhere in your compilers include path. It requires <a href="http://www.boost.org">
 148 boost</a> to be installed (only boost headers). It also requires that lua is installed, or
 149 at least that <tt>lua.h</tt> is available in the user include path.</p>
 150
 151 <p>To use luabind, you must include its main header file.</p>
 152
 153 <pre>
 154 #include &lt;luabind/luabind.hpp&gt;
 155 </pre>
 156
 157 <p>This includes support for both registering classes and functions. If you just want to
 158 have support for functions or classes you can include <tt>&lt;luabind/function.hpp&gt;</tt>
 159 and <tt>&lt;luabind/class.hpp&gt;</tt> separately.</p>
 160
 161 <pre>
 162 #include &lt;luabind/function.hpp&gt;
 163 #include &lt;luabind/class.hpp&gt;
 164 </pre>
 165
 166 <p>The first thing you need to do is to call <tt>luabind::open(lua_State*)</tt> which will
 167 register the functions to create classes from lua, and initialize some state-global
 168 structures used by luabind. If you don't call this function you will hit asserts later in
 169 the library. There is no corresponding close function because once a class has been registered
 170 in lua, there really isn't any good way to remove it. Partly because any remaining instances
 171 of that class relies on the class being there. Everything will be cleaned up when the state
 172 is closed though.</p>
 173
 174 <p>Note that no luabind header will include <tt>"lua.h"</tt>, this is up to you. You have to include
 175 it before any luabind header is included.</p>
 176
 177
 178 <h1><a name="fun"></a>Binding functions to lua</h1>
 179
 180 <p>To bind functions to lua you use the function <tt>luabind::function()</tt>. It has the following
 181 synopsis:</p>
 182
 183 <pre>
 184 template&lt;class F, class policies&gt;
 185 void function(lua_State* L, const char* name, F f, const Policies&amp;);
 186 </pre>
 187
 188 <ul>
 189         <li>L is the lua state you want this function registered
 190         in.
 191         <li>name is the name the function will have within lua.
 192         <li>F is the function pointer you want to register.
 193         <li>The Policies parameter is used to describe how
 194         parameters and return values are treated by the function, this is an optional
 195         parameter. More on this in <a href="#policies" >parameter policies</a>.
 196 </ul>
 197
 198 <p>An example usage could be if you want to register the
 199 function <tt>float std::sin(float)</tt>:</p>
 200
 201 <pre>
 202 luabind::function(L, "sin", &amp;std::sin);
 203 </pre>
 204
 205 <h2><a name="fun_overload"></a>overloaded functions</h2>
 206
 207 <p>If you have more than one function with the same name,
 208 and want to register them in lua, you have to explicitly give the signature.
 209 This is to let C++ know which function you refer to. For example, if you have
 210 two functions, <tt>int&nbsp;f(const&nbsp;char*)</tt> and <tt>void&nbsp;f(int)</tt>.</p>
 211
 212 <pre>
 213 luabind::function(L, "f", (int(*)(const char*)) &amp;f);
 214 luabind::function(L, "f", (void(*)(int)) &amp;f);
 215 </pre>
 216
 217 <h2><a name="fun_sigmatch"></a>signature matching</h2>
 218
 219 <p>Luabind will generate code that checks the lua stack to
 220 see if the values there can match your functions' signatures. It will handle
 221 implicit typecasts between derived classes, and it will prefer matches with the
 222 least number of implicit casts. In a function call, if the function is
 223 overloaded and there's no overload that match the parameters better than the
 224 other, you have an ambiguity. This will spawn a run-time error, stating that the
 225 function call is ambiguous. A simple example of this is to register one function
 226 that takes an <tt>int</tt> and one that takes a <tt>float</tt>. Since lua don't distinguish between floats and
 227 integers, both will always match.</p>
 228
 229 <p>Since all overloads are tested, it will always find the
 230 best match (not the first match). This also means that it can handle situations
 231 where the only difference in the signature is that one member function is const
 232 and the other isn't. For example, if the following function and class is
 233 registered:</p>
 234
 235 <pre>
 236 struct A
 237 {
 238         void f();
 239         void f() const;
 240 };
 241
 242 const A* create_a();
 243
 244 struct B: A {};
 245 struct C: B {};
 246
 247 void g(A*);
 248 void g(B*);
 249 </pre>
 250
 251 <p>(note that <tt>create_a()</tt> would need an <a href="#policies_adopt" >adopt return value policy</a>. How to register classes is
 252 described in <a href="#bind_classes" >Binding classes to lua</a>).</p>
 253
 254 <p>And the following lua code is executed:</p>
 255
 256 <pre>
 257 a1 = create_a()
 258 a1:f() -- the const version is called
 259
 260 a2 = A()
 261 a2:f() -- the non-const version is called
 262
 263 a = A()
 264 b = B()
 265 c = C()
 266
 267 g(a) -- calls g(A*)
 268 g(b) -- calls g(B*)
 269 g(c) -- calls g(B*)
 270 </pre>
 271
 272 <h2><a name="fun_exception"></a>exceptions</h2>
 273 <p>If any of the functions you register throws an exception when called, that exception will be caught
 274 by luabind and converted to an error string and <tt>lua_error</tt> will be invoked. If the exception
 275 is a <tt>std::exception</tt> or a <tt>const&nbsp;char*</tt> the string that is pushed on the lua stack,
 276 as error message, will be the <tt>what()</tt> or the string itself respectively. If the exception
 277 is unkown, a generic string saying that the function threw an exception will be pushed.</p>
 278
 279 <p>Exceptions thrown from user defined functions have to be caught by luabind. If they weren't they
 280 would be thrown through lua itself, which is usually compiled as C code and doesn't support the
 281 stack-unwinding that exceptions imply.</p>
 282
 283 <p>Any function that invokes lua code may throw <tt>luabind::error</tt>. This exception means that a lua
 284 run-time error occured. The error message is found on top of the lua stack. The reason why the
 285 exception doesn't contain the error string itself is because it would the require heap allocation
 286 which may fail. If an exception class throws an exception while it is being thrown itself, the
 287 application will be terminated.</p>
 288
 289 <h2><a name="lua_fun"></a>calling lua functions</h2>
 290
 291 <p>To call a lua function, you can either use <tt>call_function()</tt>, <tt>call_member()</tt>, an
 292 <a href="#object"><tt>object</tt></a> or <a href="#functor"><tt>functor</tt></a>.</p>
 293
 294 <h3><tt>template&lt;class Ret&gt;<br>
 295 Ret call_function(lua_State* L, const char* name, ...)</tt></h3>
 296 <p>Calls the global function called <tt>name</tt>. This function can only call global lua functions. The
 297 ... represents variable number of parameters that's sent to the lua function. This function call may
 298 throw <tt>luabind::error</tt> if the function call fails.</p>
 299
 300 <p>The return value isn't actually <tt>Ret</tt> (the template parameter), but a proxy object that will do
 301 the function call. This enables you to give policies to the call. You do this with the operator[]. You
 302 give the policies within the brackets, like this:</p>
 303
 304 <pre>
 305 int ret = call_function&lt;int&gt;(L, "a_lua_function", new complex_class())[ adopt(_1) ];
 306 </pre>
 307
 308 <h3><tt>template&lt;class Ret&gt;<br>
 309 Ret call_member(object&amp;, const char* name, ...)</tt></h3>
 310 <p>This treats the given <tt>object</tt> as an instance of a class. The given name is the name of a member
 311 function to call. The ... represents variable number of parameters given to the function. This function may
 312 throw <tt>luabind::error</tt> if the function call fails.</p>
 313
 314 <p>You can give policies to a member function call the same way as you do with <tt>call_function</tt>.</p>
 315
 316 <h1><a name="bind_classes"></a>Binding classes to lua</h1>
 317
 318 <p>To register classes you use a class called <tt>class_</tt>. It's name is supposed to resemble the C++
 319 keyword, to make it look more intuitive. It has an overloaded member function
 320 <tt>def()</tt> that is used to register member functions,
 321 operators, constructors, enums and properties on the class. It will return a
 322 this pointer, to let you register more members directly.</p>
 323
 324 <p>Let's start with a simple example. Consider the
 325 following C++ class:</p>
 326
 327 <pre>
 328 class testclass
 329 {
 330 public:
 331         testclass(const std::string&amp; s): m_string(s) {}
 332         void print_string() { std::cout &lt;&lt; m_string &lt;&lt; "\n"; }
 333 private:
 334         std::string m_string;
 335 };
 336 </pre>
 337
 338 <p>To register it with a lua environment, write as follows
 339 (assuming you are <tt>using namespace luabind</tt>):</p>
 340
 341 <pre>
 342 class_&lt;testclass&gt;(L, "testclass")
 343         .def(constructor&lt;const std::string&amp;&gt;())
 344         .def("print_string", &amp;testclass::print_string)
 345         ;
 346 </pre>
 347
 348 <p>This will register the class with the name <tt>testclass</tt> and constructor that takes a string as
 349 argument and one member function with the name <tt>print_string</tt>. You can then use this class in lua like
 350 this.</p>
 351
 352 <pre>
 353 -- instantiate the class
 354 a = testclass('a string')
 355
 356 -- call the member function print_string on it
 357 -- this will print 'a string' on stdout
 358 a:print_string()
 359 </pre>
 360
 361 <p>It is also possible to register free functions as member
 362 functions. The requirement on the function is that it takes a pointer, const
 363 pointer, reference or const reference to the class type as the first parameter.
 364 The rest of the parameters are the ones that are visible in lua, while the
 365 object pointer is given as the first parameter. If we have the following C++
 366 code:</p>
 367
 368 <pre>
 369 struct A
 370 {
 371         int a;
 372 };
 373
 374 int plus(A* o, int v) { return o-&gt;a + v; }
 375 </pre>
 376
 377 <p>You can register the plus, function as if it was a
 378 member function on <tt>A</tt> like this:</p>
 379
 380 <pre>
 381 class_&lt;A&gt;(L, "A")
 382         .def("plus", &amp;plus)
 383         ;
 384 </pre>
 385
 386 <p><tt>plus</tt> can now be called as
 387 a member function on A with one parameter, <tt>int</tt>. If
 388 the object pointer parameter is const, the function will act as if it was a
 389 const member function (it can be called on const objects).</p>
 390
 391 <h2><a name="class_property"></a>properties</h2>
 392
 393 <p>To register a global data member with a class is easily
 394 done. Consider the following class:</p>
 395
 396 <pre>
 397 struct A
 398 {
 399         int a;
 400 };
 401 </pre>
 402
 403 <p>This class is registered like this:</p>
 404
 405 <pre>
 406 class_&lt;A&gt;(L, "A")
 407         .def_readwrite("a", &amp;A::a)
 408         ;
 409 </pre>
 410
 411 <p>If it's supposed to be readable and writable. You can
 412 also register attributes as read-only.</p>
 413
 414 <pre>class_&lt;A&gt;(L, "A")
 415         .def_readonly("a", &amp;A::a)
 416         ;
 417 </pre>
 418
 419 <p>You can also register getter and setter functions and
 420 make them look as if they were a public data member. Consider the following
 421 class:</p>
 422
 423 <pre>
 424 class A
 425 {
 426         void set_a(int x) { a_ = x; }
 427         int get_a() const { return a_; }
 428 private:
 429         int a_;
 430 };
 431 </pre>
 432
 433 <p>It can be registered as if it had a public data member
 434 <tt>a</tt> like this:</p>
 435
 436 <pre>
 437 class_&lt;A&gt;(L, "A")
 438         .property("a", &amp;A::get_a, &amp;A::set_a)
 439         ;
 440 </pre>
 441
 442 <p>This way the <tt>get_a()</tt> and
 443 <tt>set_a()</tt> functions will be called instead of just
 444 writing to the data member. If you want to make it read only you can just omit
 445 the last parameter.</p>
 446
 447 <h2><a name="class_enum"></a>enums</h2>
 448
 449 <p>If your class contains enumerated constants (enums), you
 450 can register them as well to make them available in lua. Note that they will not
 451 be type safe, all enums are integers in lua, and all functions that takes an
 452 enum, will accept any integer. You register them like this:</p>
 453
 454 <pre>
 455 class_&lt;A&gt;(L, "A")
 456         .enum_("constants")
 457         [
 458                 value("my_enum", 4),
 459                 value("my_2nd_enum", 7),
 460                 value("another_enum", 6)
 461         ];
 462 </pre>
 463
 464 <p>In lua they are reached like any data member, except
 465 that they are read-only and reached on the class itself rather than on an
 466 instance of the class.</p>
 467
 468 <pre>
 469 print(A.my_enum)
 470 print(A.another_enum)
 471 </pre>
 472
 473 <p>In this example the numbers 4 and 6 are printed.</p>
 474
 475 <h2><a name="class_operator"></a>operators</h2>
 476
 477 <p>The mechanism for registering operators on your class is
 478 pretty simple. You use a global name <tt>luabind::self</tt>
 479 to refer to the class itself and then you just write the operator expression
 480 inside the <tt>def()</tt> call. This class:</p>
 481
 482 <pre>
 483 struct vec
 484 {
 485         vec operator+(int s);
 486 };
 487 </pre>
 488
 489 <p>Is registered like this:</p>
 490
 491 <pre>
 492 class_&lt;vec&gt;(L, "vec")
 493         .def(self + int())
 494         ;
 495 </pre>
 496
 497 <p>This will work regardless if your plus operator is
 498 defined inside your class or as a free function.</p>
 499
 500 <p>If you operator is <tt>const</tt> (or, when defined as a free function,
 501 takes a const reference to the class itself) you have to use <tt>const_self</tt>
 502 instead of <tt>self</tt>. Like this:</p>
 503
 504 <pre>
 505 class_&lt;vec&gt;(L, "vec")
 506         .def(const_self + int())
 507         ;
 508 </pre>
 509
 510 <p>The operators supported are those available in lua:</p>
 511
 512 <ul>
 513         <li>+
 514         <li>-
 515         <li>*
 516         <li>/
 517         <li>^
 518         <li>&lt;
 519         <li>&lt;=
 520         <li>==
 521         <li>unary -
 522         <li>operator()
 523 </ul>
 524
 525 <p>This means, no in-place operators. The equality operator (==) has a little
 526 hatch, it will not be called if the references are equal. This means that
 527 the == operator has to do pretty much what's it's expected to do.</p>
 528
 529 <p>In the above example the other operand type is
 530 instantiated by writing <tt>int()</tt>. If the operand type
 531 is a complex type that cannot easily be instantiated you can wrap the type in a
 532 class called <tt>other</tt>. For example:</p>
 533
 534 <p>To register this class, we don't want to instantiate a
 535 string just to register the operator.</p>
 536
 537 <pre>
 538 struct vec
 539 {
 540         vec operator+(std::string);
 541 };
 542 </pre>
 543
 544 <p>Instead we use the <tt>other</tt>
 545 wrapper like this:</p>
 546
 547 <pre>
 548 class_&lt;vec&gt;(L, "vec")
 549         .def(self + other&lt;std::string&gt;())
 550         ;
 551 </pre>
 552
 553 <p>To register an application operator:</p>
 554
 555 <pre>
 556 class_&lt;vec&gt;(L, "vec")
 557         .def( self(int()) )
 558         ;
 559 </pre>
 560
 561 <p>There's one special operator. In lua it's called <tt>__tostring</tt>,
 562 it's not really an operator. It is used for converting objects to strings
 563 in a standard way in lua. If you register this functionality, you will
 564 be able to use the lua standard function <tt>tostring()</tt> for converting
 565 you object to a string.</p>
 566
 567 <p>To implement this operator in C++ you should supply an
 568 operator<tt>&lt;&lt;</tt> for <tt>ostream</tt>. Like this example:</p>
 569
 570 <pre>
 571 class number {};
 572
 573 std::ostream&amp; operator&lt;&lt;(ostream&amp;, number&amp;);
 574 </pre>
 575
 576 <pre>
 577 class_&lt;number&gt;()
 578         .def(tostring(self))
 579         ;
 580 </pre>
 581
 582
 583 <h2><a name="class_derived"></a>derived classes</h2>
 584
 585 <p>If you want to register classes that derives from other
 586 classes, you can specify a template parameter <tt>bases&lt;&gt;</tt> to
 587 the <tt>class_</tt> instantiation. The following hierarchy:</p>
 588
 589 <pre>
 590 struct A {};
 591 struct B: A{};
 592 </pre>
 593
 594 <p>Would be registered like this:</p>
 595
 596 <pre>
 597 class_&lt;A&gt;(L, "A");
 598 class_&lt;B, A&gt;(L, "B");
 599 </pre>
 600
 601 <p>If you have multiple inheritance you can specify more
 602 than one base. If <tt>B</tt> would also derive from a class
 603 <tt>C</tt>, it would be registered like this:</p>
 604
 605 <pre>
 606 class_&lt;B, bases&lt;A, C&gt; &gt;(L, "B");
 607 </pre>
 608
 609 <p>Note that you can omit <tt>bases&lt;..&gt;</tt> when using single inheritance.</p>
 610
 611 <p>If you don't specify that classes derive from each
 612 other, luabind will not be able to implicitly cast pointers between the types.
 613 If for example, you forget to tell that <tt>B</tt> derives
 614 from <tt>A</tt> and we have a function with the following
 615 signature:</p>
 616
 617 <pre>
 618 void f(A*);
 619 </pre>
 620
 621 <p>The following code will not run:</p>
 622
 623 <pre>
 624 b = B()
 625 f(b) -- error, no function 'f' matches the arguments (B)
 626 </pre>
 627
 628 <p>Because luabind doesn't know that a <tt>B*</tt> can be cast to an <tt>A*</tt>.</p>
 629
 630 <h1><a name="object"></a>Value wrapper</h1>
 631
 632 <p>Since functions have to be able to take lua values (of variable type) we need a wrapper
 633 around them. This wrapper is called <tt>luabind::object</tt>. If the function you register
 634 takes an <tt>object</tt>, it will match any lua value. To use it, you need to include
 635 <tt>&lt;luabind/object.hpp&gt;</tt>. The <tt>object</tt> class has the following synopsis:</p>
 636
 637 <pre>
 638 class object
 639 {
 640 public:
 641         class iterator;
 642         class raw_iterator;
 643         class array_iterator;
 644
 645         template&lt;class T&gt;
 646         object(lua_State*, const T&amp; value);
 647         object(const object&amp;);
 648         object(lua_State*);
 649         object();
 650
 651         ~object();
 652
 653         iterator begin() const;
 654         iterator end() const;
 655         raw_iterator raw_begin() const;
 656         raw_iterator raw_end() const;
 657         array_iterator abegin() const;
 658         array_iterator aend() const;
 659
 660         lua_State* lua_state() const;
 661         void pushvalue() const;
 662         bool is_valid() const;
 663         operator bool() const;
 664
 665         template&lt;class Key&gt;
 666         <i>&lt;implementation-defined&gt;</i> operator[](const Key&amp;);
 667
 668         template&lt;class Key&gt;
 669         object at(const Key&amp;) const;
 670
 671         template&lt;class Key&gt;
 672         object raw_at(const Key&amp;) const;
 673
 674         template&lt;class T&gt;
 675         object&amp; operator=(const T&amp;);
 676         object&amp; operator=(const object&amp;);
 677
 678         void swap(object&amp;);
 679         int type() const;
 680
 681         template&lt;class T&gt;
 682         bool operator==(const T&amp;) const;
 683         bool operator==(const object&amp;) const;
 684
 685         <i>&lt;implementation-defined&gt;</i> operator()();
 686
 687         template&lt;class A0&gt;
 688         <i>&lt;implementation-defined&gt;</i> operator()(const A0&amp; a0);
 689
 690         template&lt;class A0, class A1&gt;
 691         <i>&lt;implementation-defined&gt;</i> operator()(const A0&amp; a0, const A1&amp; a1);
 692
 693         /* ... */
 694
 695 };
 696 </pre>
 697
 698 <p>When you have a lua object, you can assign it a new value with the assignment operator (=). When
 699 you do this, the <tt>default_policy</tt> will be used to make the conversion from C++ value to lua.
 700 If your <tt>luabind::object</tt> is a table you can access its members through the operator[] or
 701 the iterators. The value returned from the operator[] is a proxy object that can be used both
 702 for reading and writing values into the table (using operator=). Note that it is impossible
 703 to know if a lua value is indexable or not (lua_gettable doesn't fail, it succeeds or crashes).
 704 This means that if you're trying to index something that can be indexed, you're on your own. Lua
 705 will call its <tt>panic()</tt> function (you can define your own panic function using
 706 <tt>lua_setpanicf</tt>). The <tt>at()</tt> and <tt>raw_at()</tt> functions returns the value
 707 at the given table position (like operator[] but only for reading). The first uses <tt>lua_gettable</tt>
 708 and the latter uses <tt>lua_rawget</tt>.</p>
 709
 710 <p>The iterators are (almost) models of the <a href="http://www.sgi.com/tech/stl/ForwardIterator.html">
 711 ForwardIterator</a> concept. The exceptions are that operator-&gt; and postincrement doesn't exist on
 712 them.</p>
 713
 714 <p>The operator== will run <tt>lua_equal()</tt>
 715 on the operands and return its result.</p>
 716
 717 <p>The <tt>int type()</tt> member function will return the lua type of the object. It will return
 718 the same values as <tt>lua_type()</tt>.</p>
 719
 720 <p>The <tt>is_valid</tt> function tells you wether the object has been initialized or not. When created
 721 with its default constructor, objects are invalid. To make an object valid, you can assign it a value. If
 722 you want to invalidate an object you can simply assign it an invalid object.</p>
 723
 724 <p>The <tt>operator bool()</tt>
 725 isn't really an implicit cast to bool, but an implicit cast to a member pointer, since member pointers
 726 don't have any arithmetic operators on them (which can cause hard to find errors). The functionality of
 727 the cast-operator is equivalent to <tt>is_valid()</tt>. This means that:</p>
 728
 729 <pre>
 730 object o;
 731 // ...
 732 if (o.is_valid())
 733 {
 734         // ...
 735 }
 736 </pre>
 737
 738 <p>is equivalent to:</p>
 739
 740 <pre>
 741 object o;
 742 // ...
 743 if (o)
 744 {
 745         // ...
 746 }
 747 </pre>
 748
 749 <p>The application operator will call the value as if it was a function. You can give it any number
 750 of parameters (currently the <tt>default_policy</tt> will be used for the conversion). The returned
 751 object refers to the return value (currently only one return value is supported). This operator may
 752 throw <tt>luabind::error</tt> if the function call fails. If you want to specify
 753 <a href="#policies">policies</a> to your function call, you can use index-operator (operator[]) on
 754 the function call, and give the policies within the [ and ]. Like this:</p>
 755
 756 <pre>
 757 my_function_object(2, 8, new my_complex_structure(6)) [ adopt(_3) ];
 758 </pre>
 759
 760 <p>This tells luabind to make lua adopt the ownership and responsibility for the pointer passed in
 761 to the lua-function.</p>
 762
 763 <p>It's important that all instances of <tt>object</tt> has been destructed by the time the lua state
 764 is closed. The object will keep a pointer to the lua state and release its lua object in its
 765 destructor.</p>
 766
 767 <p>Here's an example of how a function can use a table.</p>
 768
 769 <pre>
 770 void my_function(const object&amp; table)
 771 {
 772         if (table.type() == LUA_TTABLE)
 773         {
 774                 table["time"] = std::clock();
 775                 table["name"] = std::rand() &lt; 500 ? "unusual" : "usual";
 776
 777                 std::cout &lt;&lt; object_cast&lt;std::string&gt;(table[5]) &lt;&lt; "\n";
 778         }
 779 }
 780 </pre>
 781
 782 <p>If you take a <tt>luabind::object</tt> as a parameter to a function, any lua value will match that parameter.
 783 That's why we have to make sure it's a table before we index into it.</p>
 784
 785 <h2><a name="wrap_fun"></a>related functions</h2>
 786
 787 <p>
 788 There are a couple of functions related to objects and tables.
 789 </p>
 790
 791 <h3><tt>T object_cast&lt;<i>Type</i>&gt;(const&nbsp;object&amp;);</tt><br>
 792 <tt>T object_cast&lt;<i>Type</i>&gt;(const&nbsp;object&amp;, const&nbsp;Policies&amp;);</tt><br>
 793 <tt>boost::optional&lt;T&gt; object_cast_nothrow&lt;<i>Type</i>&gt;(const&nbsp;object&amp;);</tt><br>
 794 <tt>boost::optional&lt;T&gt; object_cast_nothrow&lt;<i>Type</i>&gt;(const&nbsp;object&amp;, const&nbsp;Policies&amp;);</tt></h3>
 795 <p>The <tt>object_cast</tt> function casts the value of an <tt>object</tt> to a C++ value. You
 796 can supply a policy to handle the conversion from lua to C++. If the cast cannot be made a
 797 <tt>cast_failed</tt> exception will be thrown. If you have defined <tt>LUABIND_NO_ERROR_CHECKING</tt>
 798 (see <a href="#config">configuration</a>) no checking will occur, and if the cast is invalid the
 799 application may very well crash. The nothrow versions will return an uninitialized <tt>boost::optional&lt;T&gt;</tt>
 800 object, to indicate that the cast could not be performed.</p>
 801
 802 <h3><tt>object get_globals(lua_State*);</tt><br>
 803 <tt>object get_registry(lua_State*);</tt></h3>
 804 <p>These functions returns the global environment table and the registry table respectively.</p>
 805
 806 <h3><tt>object newtable(lua_State*);</tt></h3>
 807 <p>This function creates a new table and return an object to it.</p>
 808
 809 <h2><a name="functor"></a>functor</h2>
 810
 811 <p>The <tt>functor</tt> class is similar to <tt>object</tt>, with the exception that it can
 812 only be used to store functions. If you take it as a parameter, it will only match functions.</p>
 813
 814 <p>To use it you need to include its header:</p>
 815
 816 <pre>
 817 #include &lt;luabind/functor.hpp&gt;
 818 </pre>
 819
 820 <p>It takes one template parameter, the return value of the lua function it represents.
 821 Currently the functor can have at most one return value (unlike lua funcions). It has the
 822 following synopsis:</p>
 823
 824 <pre>
 825 template&lt;class Ret&gt;
 826 class functor
 827 {
 828 public:
 829
 830         functor(lua_State*, const char* name);
 831         functor(const functor&amp;);
 832
 833         ~functor();
 834
 835         bool is_valid() const;
 836         operator bool() const;
 837
 838         <i>&lt;implementation-defined&gt;</i> operator()() const;
 839
 840         template&lt;class A0&gt;
 841         <i>&lt;implementation-defined&gt;</i> operator()(const A0&amp;) const;
 842
 843         template&lt;class A0, class A1&gt;
 844         <i>&lt;implementation-defined&gt;</i> operator()(const A0&amp;, const A1&amp;) const;
 845
 846         /* ... */
 847 };
 848 </pre>
 849
 850 <p>The application operator takes any parameters. The parameters are converted into lua and the
 851 function is called. The return value will act as if it was the type <tt>Ret</tt>, with the exception that you can use the
 852 return value to give policies to the call. You do this the same way as you do with <a href="#object">objects</a>,
 853 using the operator[], and giving the policies inside the brackets.</p>
 854
 855 <p>The <tt>is_valid()</tt> function works just like the one on <a href="#object"><tt>object</tt></a>, it tells you if
 856 the functor has been assigned with a valid lua function. The <tt>operator bool()</tt> is an alias for this member function
 857 and also works just as the one found in <a href="#object"><tt>object</tt></a>.</p>
 858
 859 <p>For example, if you have the following lua function:</p>
 860
 861 <pre>
 862 function f(a, b)
 863         return a + b
 864 end
 865 </pre>
 866
 867 <p>You can expose it to C++ like this:</p>
 868
 869 <pre>
 870 functor&lt;int&gt; f(L, "f");
 871
 872 std::cout &lt;&lt; f(3, 5) &lt;&lt; "\n";
 873 </pre>
 874
 875 <p>Which will print out the sum of 3 and 5. Note that you can pass any parameters to the
 876 application operator of <tt>luabind::functor</tt>, this is because lua doesn't have
 877 signatures for its functions. All lua functions take any number of parameters
 878 of any type.</p>
 879
 880 <p>If we have a C++ function that takes a <tt>luabind::functor</tt> and registers it, it will accept lua
 881 functions passed to it. This enables us to expose APIs that requires you to
 882 register callbacks. For example, if your C++ API looks like this:</p>
 883
 884 <pre>
 885 void set_callback(void(*)(int, int));
 886 </pre>
 887
 888 <pre>
 889 object o;
 890 // ...
 891 if (o.is_valid())
 892 {
 893         // ...
 894 }
 895 </pre>
 896
 897
 898 <p>And you want to expose it to lua, you have to wrap the
 899 call to the lua function inside a real C++ function, like this:</p>
 900
 901 <pre>
 902 functor&lt;void&gt; lua_callback;
 903
 904 void callback_wrapper(int a, int b)
 905 {
 906         lua_callback(a, b);
 907 }
 908
 909 void set_callback_wrapper(const functor&lt;void&gt;&amp; f)
 910 {
 911         lua_callback = f;
 912         set_callback(&amp;callback_wrapper);
 913 }
 914 </pre>
 915
 916 <p>And then register <tt>set_callback_wrapper</tt> instead of registering <tt>set_callback</tt>.
 917 This will have the effect that when one tries to register the callback from lua, your
 918 <tt>set_callback_wrapper</tt> will be called instead and first set the lua fuctor to the given function.
 919 It will the call the real <tt>set_callback</tt> with the <tt>callback_wrapper</tt>. The
 920 <tt>callback_wrapper</tt> will be called whenever the callback should be called, and it will simply
 921 call the lua function that we registered.</p>
 922
 923 <p>You can also use <a href="#wrap_fun"><tt>object_cast</tt></a> to cast an object to a <tt>functor</tt>.</p>
 924
 925 <h1><a name="class_lua"></a>Defining classes in lua</h1>
 926
 927 <p>In addition to binding C++ functions and classes with
 928 lua, luabind also provide an oo-system in lua.</p>
 929
 930 <pre>
 931 class 'lua_testclass'
 932
 933 function lua_testclass:__init(name)
 934         self.name = name
 935 end
 936
 937 function lua_testclass:print()
 938         print(self.name)
 939 end
 940
 941 a = lua_testclass('example')
 942 a:print()
 943 </pre>
 944
 945 <p>Inheritance can be used between lua-classes:</p>
 946
 947 <pre>
 948 class 'derived' (lua_testclass)
 949
 950 function derived:__init() super('derived name')
 951 end
 952
 953 function derived:print()
 954         print('Derived:print() -&gt; ')
 955         lua_testclass.print(self)
 956 end
 957 </pre>
 958
 959 <p>Here the <tt>super</tt> keyword is
 960 used in the constructor to initialize the baseclass. The user is required to
 961 call <tt>super</tt> first in the constructor.</p>
 962
 963 <p>As you can see in this example, you can call the
 964 baseclass' member functions. You can find all member functions in the baseclass,
 965 but you will have to give the this-pointer as first argument (<tt>self</tt> that is).</p>
 966
 967 <h2><a name="class_lua_derive"></a>deriving in lua</h2>
 968
 969 <p>It is also possible to derive lua classes from C++
 970 classes, and override virtual functions with lua functions. To do this we have
 971 to create a wrapper class for our C++ baseclass. This is the class that will
 972 hold the lua object when we instantiate a lua class.</p>
 973
 974 <p>The wrapper class has to provide the same constructors
 975 as the baseclass, with the addition of one extra parameter: <tt>luabind::object</tt>.
 976 This is the reference to the lua object that should be held by the wrapper, and should
 977 be stored in a member variable as done in the sample below.</p>
 978
 979 <pre>
 980 class baseclass
 981 {
 982 public:
 983         baseclass(const char* s)        { std::cout &lt;&lt; s &lt;&lt; "\n"; }
 984         virtual void f(int a) { std::cout &lt;&lt; "f(" &lt;&lt; a &lt;&lt; ")\n"; }
 985 };
 986
 987 struct baseclass_wrapper: baseclass
 988 {
 989         luabind::object m_l;
 990         baseclass_wrapper(luabind::object l, const char* s): baseclass(s), m_l(l) {}
 991
 992         virtual void f(int a) { call_member&lt;void&gt;(m_l, "f", a); }
 993         static void f_static(baseclass* ptr, int a)
 994         {
 995                 return ptr-&gt;baseclass::f(a);
 996         }
 997 };
 998 </pre>
 999 <pre>
1000 class_&lt;baseclass, baseclass_wrapper&gt;(L, "baseclass")
1001         .def(constructor&lt;const char*&gt;())
1002         .def("f", &amp;baseclass_wrapper::f_static)
1003         ;
1004 </pre>
1005
1006 <p>Note that if you have both baseclasses and a baseclass
1007 wrapper, you must give both <tt>bases</tt> and the
1008 baseclass wrapper type as template parameter to <tt>class_</tt>. The order
1009 in which you specify them is not important.</p>
1010
1011 <p>If we didn't have a class wrapper, it would not be possible to pass a lua class
1012 back to C++. Since the entrypoints of the virtual functions would still point to
1013 the C++ baseclass, and not to the functions defined in lua. That's why we need
1014 one function that calls the baseclass' real functon (used if the lua class
1015 doesn't redefine it) and one virtual function that dispatches the call into lubind,
1016 to allow it to select if a lua function should be called, or if the original
1017 function should be called. If you don't intend to derive from a C++ class, or if
1018 it doesn't have any virtual member functions, you can register it without a
1019 class wrapper.</p>
1020
1021 <p>You don't need to have a class wrapper in order to derive from a class,
1022 but if it has virtual functions you may have silent errors. The rule of thumb is:
1023 If your class has virtual functions, create a wrapper type, if it doesn't don't create
1024 a wrapper type.</p>
1025
1026 <h1><a name="policies"></a>Parameter policies</h1>
1027
1028 <p>Sometimes it is necessary to control how luabind passes
1029 arguments and return value, to do this we have policies. These are the
1030 policies that can be used:</p>
1031
1032 <h2><a name="policies_copy"></a>copy</h2>
1033
1034 <p>This will make a copy of the parameter. This is the
1035 default behavior when passing parameters by-value. Note that this can only be
1036 used when passing from C++ to lua. This policy requires that the parameter
1037 type has a copy constructor.</p>
1038
1039 <p>To use this policy you need to include <tt>&lt;luabind/copy_policy.hpp&gt;</tt>.</p>
1040
1041 <h2><a name="policies_adopt"></a>adopt</h2>
1042
1043 <p>This will transfer ownership of the parameter.</p>
1044 <p>Consider making a factory function in C++ and exposing
1045 it to lua:</p><pre>base* create_base()
1046 {
1047         return new base();
1048 }
1049 </pre>
1050
1051 <pre>
1052 function(L, "create_base", create_base);
1053 </pre>
1054
1055 <p>Here we need to make sure lua understands that it should
1056 adopt the pointer returned by the factory-function. This can be done using the
1057 adopt-policy.</p>
1058
1059 <pre>
1060 function(L, "create_base", adopt(return_value));
1061 </pre>
1062
1063 <p>To specify multiple policies we just separate them with '+'.</p>
1064
1065 <pre>
1066 base* set_and_get_new(base* ptr)
1067 {
1068         base_ptrs.push_back(ptr);
1069         return new base();
1070 }
1071 </pre>
1072
1073 <pre>
1074 function(L, "set_and_get_new", &amp;set_and_get_new, adopt(return_value) + adopt(_1));
1075 </pre>
1076
1077 <p>To use this policy you need to include <tt>&lt;luabind/adopt_policy.hpp&gt;</tt>.</p>
1078
1079 <h2><a name="policies_dependency"></a>depedency</h2>
1080
1081 <p>The dependency policy is used to create life-time dependencies between values. Consider the following example:</p>
1082
1083 <pre>
1084 struct A
1085 {
1086         B m_member;
1087
1088         const B&amp; get_member()
1089         {
1090                 return m_member;
1091         }
1092 };
1093 </pre>
1094
1095 <p>When wrapping this class, we would do something like:</p>
1096
1097 <pre>
1098 class_&lt;A&gt;(L, "A")
1099         .def(constructor&lt;&gt;())
1100         .def("get_member", &amp;A::get_member)
1101         ;
1102 </pre>
1103
1104 <p>However, since the return value of get_member is a reference to a member of A, this will create
1105 some life-time issues. For example:</p>
1106
1107 <pre>
1108 a = A()
1109 b = a:get_member() -- b points to a member of a
1110 a = nil
1111 collectgarbage(0)  -- since there are no references left to a, it is removed
1112                    -- at this point, b is pointing into a removed object
1113 </pre>
1114
1115 <p>When using the dependency-policy, it is possible to tell luabind to tie the lifetime of one
1116 object to another, like this:</p>
1117
1118 <pre>
1119 class_&lt;A&gt;(L, "A")
1120         .def(constructor&lt;&gt;())
1121         .def("get_member", &amp;A::get_member, dependency(result, self))
1122         ;
1123 </pre>
1124
1125 <p>This will create a dependency between the return-value of the function, and the self-object. This means
1126 that the self-object will be kept alive as long as the result is still alive.</p>
1127
1128 <pre>
1129 a = A()
1130 b = a:get_member() -- b points to a member of a
1131 a = nil
1132 collectgarbage(0)  -- a is dependent on b, so it isn't removed
1133 b = nil
1134 collectgarbage(0)  -- all dependencies to a gone, a is removed
1135 </pre>
1136
1137 <p>To use this policy you need to include <tt>&lt;luabind/dependency_policy.hpp&gt;</tt>.</p>
1138
1139 <h2><a name="policies_return_ref"></a>return_reference_to</h2>
1140
1141 <p>It is very common to return references to arguments or the this-pointer to allow for chaining in C++.</p>
1142 <pre>
1143 struct A
1144 {
1145         float m_val;
1146
1147         A&amp; set(float v)
1148         {
1149                 m_val = v;
1150                 return *this;
1151         }
1152 };
1153 </pre>
1154
1155 <p>When luabind generates code for this, it will create a new object for the return-value, pointing to the self-object. This
1156 isn't a problem, but could be a bit inefficient. When using the return_reference_to-policy we have the ability to tell
1157 luabind that the return-value is already on the lua stack.</p>
1158
1159 <pre>
1160 class_&lt;A&gt;(L, "A")
1161         .def(constructor&lt;&gt;())
1162         .def("set", &amp;A::set, return_reference_to(self))
1163         ;
1164 </pre>
1165
1166 <p>Instead of creating a new object, luabind will just copy the object that is already on the stack.</p>
1167 <p>NOTE! This policy ignores all type information and should be used only it situations where the parameter type
1168 is a perfect match to the return-type (such as in the example).</p>
1169
1170 <p>To use this policy you need to include <tt>&lt;luabind/return_reference_to_policy.hpp&gt;</tt>.</p>
1171
1172 <h2><a name="policies_out"></a>out_value</h2>
1173
1174 <p>This policy makes it possible to wrap functions that take non const references as its parameters with the intention to write returnvalues to them.</p>
1175
1176 <pre>
1177 void f(float&amp; val) { val = val + 10.f; }
1178 or
1179 void f(float* val) { *val = *val + 10.f; }
1180 </pre>
1181
1182 <p>Can be wrapped by doing:</p>
1183
1184 <pre>
1185 function(L, "f", &amp;f, out_value(_1))
1186 </pre>
1187
1188 <p>When invoking this function from lua it will return the value assigned to its parameter.</p>
1189
1190 <pre>
1191 a = f(10) -- a is now 20
1192 </pre>
1193
1194 <p>When this policy is used in conjunction with user define types we often need to do ownership transfers.</p>
1195
1196 <pre>
1197 struct A
1198 {
1199 };
1200
1201 void f(A*&amp; obj) { obj = new A(); }
1202 or
1203 void f(A** obj) { *obj = new A(); }
1204 </pre>
1205
1206 <p>Here we need to make sure luabind takes control over object returned, for this we use the <tt>adopt</tt> policy</p>
1207
1208 <pre>
1209 class_&lt;A&gt;(L, "A");
1210
1211 function(L, "f", &amp;f, out_value(_1, adopt(_2)));
1212 </pre>
1213
1214 <p>Here we are using <tt>adopt</tt> as an internal policy to <tt>out_value</tt>. The index specified, <tt>_2</tt>, means adopt will be used to convert the value back to lua. Using <tt>_1</tt> means the policy will be used when converting from lua to C++.</p>
1215
1216 <p>To use this policy you need to include <tt>&lt;luabind/out_value_policy.hpp&gt;</tt>.</p>
1217
1218 <h2><a name="policies_pure_out"></a>pure_out_value</h2>
1219
1220 <p>This policy works in exactly the same way as <tt>out_value</tt>, except that it replaces the parameters with default-constructed
1221 objects.</p>
1222
1223 <pre>
1224 void get(float&amp; x, float&amp; y)
1225 {
1226         x = 3.f;
1227         y = 4.f;
1228 }
1229
1230 function(L, "get", &amp;get, pure_out_value(_1) + pure_out_value(_2));
1231 </pre>
1232 <pre>
1233 x,y = get()
1234 print(x,y)  -- prints '3   4'
1235 </pre>
1236
1237 <p>Like out_value, it is possible to specify an internal policy used then converting the values back to lua.</p>
1238
1239 <pre>
1240 void get(test_class*&amp; obj)
1241 {
1242         obj = new test_class();
1243 }
1244
1245 function(L, "get", &amp;get, pure_out_value(_1, adopt(_1)));
1246 </pre>
1247
1248 <h2><a name="policies_discard_result"></a>discard_result</h2>
1249
1250 <p>This is a very simple policy which makes it possible to throw away the value returned by a C++ function, instead of converting it to lua. This example makes sure the <tt>this</tt> reference never gets converted to lua</p>
1251
1252 <pre>
1253 struct simple
1254 {
1255         simple&amp; set_name(const std::string&amp; n)
1256         {
1257                 name = n;
1258                 return *this;
1259         }
1260
1261         std::string name;
1262 };
1263
1264 class_&lt;simple&gt;(L, "simple")
1265         .def("set_name", &amp;simple::set_name, discard_result)
1266         ;
1267 </pre>
1268
1269 <p>To use this policy you need to include <tt>&lt;luabind/discard_result.hpp&gt;</tt>.</p>
1270
1271 <h2><a name="policies_custom"></a>custom</h2>
1272
1273 <p>The policies don't have a stable API yet.</p>
1274
1275 <h2><a name="policies_user_converter"></a>user defined converter</h2>
1276
1277 <p>The policies don't have a stable API yet.</p>
1278
1279 <h1><a name="config"></a>Configuration</h1>
1280
1281 <p>You can configure luabind by defining macros before you include any of luabind's headers.
1282 The available configuration options follows:</p>
1283
1284 <table border="1" cellspacing="0" cellpadding="10">
1285         <tr>
1286                 <td valign="top"><tt>LUABIND_MAX_ARITY</tt></td>
1287                 <td>
1288                         <p>Controls the maximum arity of functions that are registered
1289                         with luabind. You can't register functions that takes more
1290                         parameters than the number this macro is set to. It defaults
1291                         to 4, so, if your functions have greater arity you have to
1292                         redefine it. A high limit will increase compilation times.</p>
1293                 </td>
1294         </tr>
1295         <tr>
1296                 <td valign="top"><tt>LUABIND_MAX_BASES</tt></td>
1297                 <td>
1298                         <p>Controls the maximum number of classes one class can derive from
1299                         in luabind (the number of classes specified within
1300                         <tt>bases&lt;&gt;</tt>). <tt>LUABIND_MAX_BASES</tt> defaults to 4.
1301                         A high limit will increase compilation times.</p>
1302                 </td>
1303         </tr>
1304         <tr>
1305                 <td valign="top"><tt>LUABIND_NO_ERROR_CHECKING</tt></td>
1306                 <td>
1307                         <p>If this macro is defined, all the lua code is expected only to make
1308                         legal calls. If illegal function calls are made (eg. giving parameters
1309                         that doesn't match the function signature) they will not be detected
1310                         by luabind and the application will probably crash. Error checking
1311                         could be disabled when shipping a release build (given that no end-user
1312                         has access to write custom lua code). Note that function parameter
1313                         matching will be done if a function is overloaded, since otherwise it's
1314                         impossible to know which one was called. Functions will still be able
1315                         to throw exceptions when error checking is disabled.</p>
1316
1317                         <p>Functions will still be able to throw exceptions, they will be
1318                         caught by luabind and propagated with <tt>lua_error()</tt>.</p>
1319                 </td>
1320         </tr>
1321         <tr>
1322                 <td valign="top"><tt>LUABIND_DONT_COPY_STRINGS</tt></td>
1323                 <td>
1324                         <p>If this macro is defined, luabind will expect that all strings given
1325                         to the def() methods are static constant strings (given as string
1326                         constants for example). luabind will not copy the strings if you
1327                         enable this setting, but just keep the char pointers. This may be
1328                         especially useful for embedded systems or consoles where heap
1329                         allocations should be minimized.</p>
1330                 </td>
1331         </tr>
1332         <tr>
1333                 <td valign="top"><tt>LUABIND_NO_EXCEPTIONS</tt></td>
1334                 <td>
1335                         <p>This define will disable all usage of try, catch and throw in
1336                         luabind. This will in many cases disable run-time errors, when
1337                         performing invalid casts or calling lua-functions that fails or
1338                         returns values that cannot be converted by the given policy.
1339                         luabind requires that no function called directly or indirectly
1340                         by luabind throws an exception (throwing exceptions through
1341                         lua has undefined behavior).</p>
1342
1343                         <p>Where exceptions are the onlyway to get an error report from
1344                         luabind, they will be replaced with an assert.</p>
1345                 </td>
1346         </tr>
1347         <tr>
1348                 <td valign="top">
1349                         <p><tt>LUABIND_TYPE_INFO</tt><br>
1350                         <tt>LUABIND_TYPE_INFO_EQUAL(i1,i2)</tt><br>
1351                         <tt>LUABIND_TYPEID(t)</tt><br>
1352                         <tt>LUABIND_INVALID_TYPE_INFO</tt></p>
1353                 </td>
1354                 <td>
1355                         <p>If you don't want to use the rtti supplied by C++
1356                         you can supply your own type-info structure with the
1357                         LUABIND_TYPE_INFO define. Your type-info structure must
1358                         be copyable and must be able to compare itself against
1359                         other type-info structures. You supply the compare
1360                         function through the LUABIND_TYPE_INFO_EQUAL()
1361                         define. It should compare the two type-info structures
1362                         it is given and return true if they represent the same type
1363                         and false otherwise. You also have to supply a function
1364                         to generate your type-info structure. You do this through
1365                         the LUABIND_TYPEID() define. It should return your type-info
1366                         structure and it takes a type as its parameter. That is,
1367                         a compile time parameter. LUABIND_INVALID_TYPE_INFO macro
1368                         should be defined to an invalid type. No other type should
1369                         be able tp produce this type info. To use it you probably
1370                         have to make a traits class with specializations for all
1371                         classes that you have type-info for. Like this:</p>
1372
1373                         <pre>
1374 class A;
1375 class B;
1376 class C;
1377
1378 template&lt;class T&gt; struct typeinfo_trait;
1379
1380 template&lt;&gt; struct typeinfo_trait&lt;A&gt; { enum { type_id = 0 }; };
1381 template&lt;&gt; struct typeinfo_trait&lt;B&gt; { enum { type_id = 1 }; };
1382 template&lt;&gt; struct typeinfo_trait&lt;C&gt; { enum { type_id = 2 }; };
1383                         </pre>
1384
1385                         <p>If you have set up your own rtti system like this (by using integers to identify types)
1386                         you can have luabind use it with the following defines</p>
1387
1388                         <pre>
1389 #define LUABIND_TYPE_INFO int
1390 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) i1 == i2
1391 #define LUABIND_TYPEID(t) typeinfo_trait&lt;t&gt;::type_id
1392 #define LUABIND_INVALID_TYPE_INFO -1
1393                         </pre>
1394
1395                         <p>The default behaviour, if you don't define any of these three, is to use the builtin
1396                         rtti support in C++.</p>
1397
1398                         <pre>
1399 #define LUABIND_TYPE_INFO const std::type_info*
1400 #define LUABIND_TYPEID(t) &amp;typeid(t)
1401 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
1402 #define LUABIND_INVALID_TYPE_INFO &amp;typeid(detail::null_type)
1403                         </pre>
1404
1405                         <p>currently the type given through LUABIND_TYPE_INFO must be less-than comparable!</p>
1406                 </td>
1407         </tr>
1408 </table>
1409
1410 <h1><a name="implementation_notes"></a>Implementation notes</h1>
1411
1412 <p>The classes and objects are implemented as userdata in lua. To make sure that
1413 the user data really is the internal structure it is supposed to be, we tag their
1414 metatables. A userdata who's metatable contains a boolean member named
1415 <tt>"__luabind_classrep"</tt> is expected to be a class exported by luabind.
1416 A userdata who's metatable contains a boolean member named <tt>"__luabind_class"</tt>
1417 is expected to be an instantiation of a luabind class.</p>
1418
1419 <p>This means that if you make your own userdata and tags its metatable with the
1420 exact same names, you can very easily fool luabind and crash the application.</p>
1421
1422 <p>In the lua registry, luabind keeps an entry called "<tt>__luabind_classes</tt>"
1423 and "<tt>__luabind_free_functions</tt>". These should not be removed or overwritten.</p>
1424
1425 <p>In the global table, a variable called <tt>super</tt> is used every time a constructor
1426 in a lua-class is called. This is to make it easy for that constructor to call its base
1427 class' constructor. So, if you have a global variable named <tt>super</tt> it may very
1428 well be overwritten. This is probably not the best solution, and this restriction may very
1429 well be removed in the future.</p>
1430
1431 <p>Inside the <tt>luabind</tt> namespace, there's another namespace called <tt>detail</tt>.
1432 This namespace contains non-public classes and are not supposed to be used directly.</p>
1433
1434 <h1><a name="error_messages"></a>Error messages</h1>
1435
1436 <ul>
1437         <li>cannot set attribute '<i>&lt;class-name&gt;</i>.<i>&lt;attribute-name&gt;</i>'
1438         <p>There is no data member named <i>&lt;attribute-name&gt;</i> in the class <i>&lt;class-name&gt;</i>, or
1439         there's no setter-method registered on that property name. See the <a href="#class_property">properties</a> section.</p>
1440
1441         <li><i>&lt;class-name&gt;</i>() threw an exception
1442         <li><i>&lt;class-name&gt;</i>:<i>&lt;function-name&gt;</i>() threw an exception
1443         <p>The class' constructor or member function threw an unknown exception. Known exceptions are <tt>const&nbsp;char*</tt>,
1444         <tt>std::exception</tt>. See the <a href="#fun_exception">exceptions</a> section.</p>
1445
1446         <li>no overload of '<i>&lt;class-name&gt;</I>:<i>&lt;function-name&gt;</i>' matched the arguments (&lt;<i>parameter-types&gt;)</i>
1447         <li>no match for function call '<i>&lt;function-name&gt;</i>' with the parameters (<i>&lt;parameter-types&gt;</i>)
1448         <li>no constructor of <i>&lt;class-name&gt;</i> matched the arguments (<i>&lt;parameter-types&gt;</i>)
1449         <li>no operator <i>&lt;operator-name&gt;</i> matched the arguments (<i>&lt;parameter-types&gt;</i>)
1450         <p>No function/operator with the given name takes the parameters you gave it. You have either misspelled the function name,
1451         or given it incorrect parameters. This error is followed by a list of possible candidate functions to help you figure out what
1452         parameter has the wrong type. If the candidate list is empty there's no function at all with that name. See the
1453         <a href="#fun_sigmatch">signature matching</a> section.</p>
1454
1455         <li>call of overloaded '<i>&lt;class-name&gt;</i>:<i>&lt;function-name&gt;</i>(&lt;<i>parameter-types&gt;</i>)' is ambiguous
1456         <li>ambiguous match for function call '<i>&lt;function-name&gt;</i>' with the parameters (<i>&lt;parameter-types&gt;</i>)
1457         <li>call of overloaded constructor '<i>&lt;class-name&gt;</i>(<i>&lt;parameter-types&gt;</i>)' is ambiguous
1458         <li>call of overloaded operator <i>&lt;operator-name&gt;</i> (<i>&lt;parameter-types&gt;</i>) is ambiguous
1459         <p>This means that the function/operator you are trying to call has at least one other overload that matches the arguments
1460         just as good as the first overload.</p>
1461
1462         <li>cannot derive from C++ class '<i>&lt;class-name&gt;</i>'. It does not have a wrapped type.
1463         <p>You are trying to derive a lua class from a C++ class that doesn't have a wrapped type. You have to give
1464         your C++ class a wrapped type when you register it with lua. See the <a href="#class_lua_derive">deriving in lua</a> section.</p>
1465
1466         <li>derived class must call super on base
1467         <li>cannot set property '<i>&lt;class-name&gt;</i>.<i>&lt;attribute_name&gt;</i>' because it's read only
1468         <p>The attribute you are trying to set is registered as read only. If you want it to be writeable you have to change your
1469         class registration and use <tt>def_readwrite()</tt> instead of <tt>def_readonly()</tt>. Alternatively (if your attribute
1470         is a property with getter and setter functions), you have to give a setter function when declaring your attribute. See
1471         the <a href="#class_property">properties</a> section.</p>
1472
1473         <li>no static '<i>&lt;enum-name&gt;</i>' in class '<i>&lt;class-name&gt;</i>'
1474         <p>You will get this error message if you are trying to access an enum that doesn't exist. Read about how to
1475         <a href="#class_enum">declare enums</a>.</p>
1476
1477         <li>expected base class
1478         <p>You have written a malformed <a href="#class_lua">class definition in lua</a>. The format is:
1479         <tt>class&nbsp;'<i>&lt;class-name&gt;</i>'&nbsp;[<i>&lt;base-class&gt;</i>]</tt>. If you don't want to derive from
1480         a base class, you have to break the line directly after the class declaration.</p>
1481
1482         <li>invalid construct, expected class name
1483         <p>You have written a malformed <a href="#class_lua">class definition in lua</a>. The <tt>class</tt> function expects
1484         a string as argument. That string is the name of the lua class to define.</p>
1485 </ul>
1486
1487 <h1><a name="faq"></a>FAQ</h1>
1488 <ul>
1489         <li><h3>What's up with __cdecl and __stdcall?</h3>
1490
1491         <p>If you're having problem with functions that cannot be converted from
1492         <tt>'void&nbsp;(__stdcall&nbsp;*)(int,int)'</tt> to <tt>'void&nbsp;(__cdecl&nbsp;*)(int,int)'</tt>.
1493         You can change the project settings to make the compiler generate functions with
1494         <tt>__cdecl</tt> calling conventions. This is a problem in developer studio.</p>
1495
1496         <li><h3>What's wrong with functions taking variable number of arguments?</h3>
1497         <p>You cannot register a function with ellipses in its signature. Since ellipses doesn't preserve
1498         typesafety, those should be avoided anyway.</p>
1499
1500         <li><h3>Internal structure overflow in VC</h3>
1501         <p>If you, in visual studio,  get <tt>fatal error C1204: compiler limit : internal
1502         structure overflow</tt>. You should try to split that compilation unit up
1503         in smaller ones.</p>
1504
1505         <li><h3>What's wrong with precompiled headers in VC?</h3>
1506         <p>Visual Studio doesn't like anonymous namespaces in its precompiled headers. If you encounter this
1507         problem you can disable precompiled headers for the compilation unit (cpp-file) that uses luabind.</p>
1508
1509         <li><h3>error C1076: compiler limit - internal heap limit reached in VC</h3>
1510         <p>In visual studio you will probably hit this error. To fix it you have to increase the internal heap
1511         with a command-line option. We managed to compile the test suit with /Zm300, but you may need a larger
1512         heap then that.</p>
1513
1514         <li><h3>error C1055: compiler limit : out of keys in VC</h3>
1515         <p>It seems that this error occurs when too many <tt>assert()</tt> are used in a program. Or more
1516         specifically, the <tt>__LINE__</tt> macro. It seems to be fixed by changing /ZI (Program database
1517         for edit and continue) to /Zi (Program database).</p>
1518
1519         <li><h3>How come my executable is huge?</h3>
1520         <p>If you're compiling in debug mode, you will probably have alot of debug-info and symbols (luabind
1521         consists of alot of functions). Also, if built in debug mode, no optimizations were applied, luabind
1522         relies on that the compiler is able to inline functions. If you built in release mode, try running
1523         <tt>strip</tt> on your executable to remove export-symbols, this will trim down the size.</p>
1524
1525 </ul>
1526
1527 <h1><a name="future"></a>Future additions</h1>
1528 <ul>
1529         <li>Smart pointer wrappers. wraps smart pointers by just
1530                 keeping one copy of it and let lua garbage collect it when there's no more
1531                 references to it.
1532         <li>Scopes and namespaces. Add the ability to register classes and
1533                 functions within lua tables.
1534         <li>A mechanism for wrapping iterators with generators.
1535 </ul>
1536
1537 <h1><a name="issues"></a>Known issues</h1>
1538 <ul>
1539         <li>If one class registers two functions with the same name and the same signature,
1540         there's currently no error. The last registered function will be the one that's used.
1541         <li>In vc7, classes can not be called <tt>test</tt>. (due to boost.mpl)
1542 </ul>
1543
1544 <h1><a name="acknowledgments"></a>Acknowledgments</h1>
1545
1546 <p>This library was written by <a href="mailto:dalwan01@student.umu.se">Daniel Wallin</a>
1547 and <a href="mailto: c99ang@cs.umu.se">Arvid Norberg</a>. © Copyright 2003. All rights reserved.</p>
1548
1549 <p>This library was inspired by Dave Abrahams'
1550 <a href="http://www.boost.org/libs/python/doc/index.html">Boost.Python</a> library which can be found in the
1551 <a href="http://www.boost.org">boost</a> library.</p>
1552 <p>
1553         <a href="http://validator.w3.org/check/referer">
1554         <img style="border:0;width:88px;height:31px"
1555         src="http://www.w3.org/Icons/valid-html401"
1556         alt="Valid HTML 4.01!"></a>
1557
1558         <a href="http://jigsaw.w3.org/css-validator/">
1559         <img style="border:0;width:88px;height:31px"
1560         src="http://jigsaw.w3.org/css-validator/images/vcss"
1561         alt="Valid CSS!"></a>
1562
1563 </p>
1564
1565 </body></html>
1566