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.0, 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         void set();
 661         lua_State* lua_state() const;
 662         void pushvalue() const;
 663         bool is_valid() const;
 664         operator bool() const;
 665
 666         template&lt;class Key&gt;
 667         <i>&lt;implementation-defined&gt;</i> operator[](const Key&amp;);
 668
 669         template&lt;class Key&gt;
 670         object at(const Key&amp;) const;
 671
 672         template&lt;class Key&gt;
 673         object raw_at(const Key&amp;) const;
 674
 675         template&lt;class T&gt;
 676         object&amp; operator=(const T&amp;);
 677         object&amp; operator=(const object&amp;);
 678
 679         void swap(object&amp;);
 680         int type() const;
 681
 682         template&lt;class T&gt;
 683         bool operator==(const T&amp;) const;
 684         bool operator==(const object&amp;) const;
 685
 686         <i>&lt;implementation-defined&gt;</i> operator()();
 687
 688         template&lt;class A0&gt;
 689         <i>&lt;implementation-defined&gt;</i> operator()(const A0&amp; a0);
 690
 691         template&lt;class A0, class A1&gt;
 692         <i>&lt;implementation-defined&gt;</i> operator()(const A0&amp; a0, const A1&amp; a1);
 693
 694         /* ... */
 695
 696 };
 697 </pre>
 698
 699 <p>When you have a lua object, you can assign it a new value with the assignment operator (=). When
 700 you do this, the <tt>default_policy</tt> will be used to make the conversion from C++ value to lua.
 701 If your <tt>luabind::object</tt> is a table you can access its members through the operator[] or
 702 the iterators. The value returned from the operator[] is a proxy object that can be used both
 703 for reading and writing values into the table (using operator=). Note that it is impossible
 704 to know if a lua value is indexable or not (lua_gettable doesn't fail, it succeeds or crashes).
 705 This means that if you're trying to index something that can be indexed, you're on your own. Lua
 706 will call its <tt>panic()</tt> function (you can define your own panic function using
 707 <tt>lua_setpanicf</tt>). The <tt>at()</tt> and <tt>raw_at()</tt> functions returns the value
 708 at the given table position (like operator[] but only for reading). The first uses <tt>lua_gettable</tt>
 709 and the latter uses <tt>lua_rawget</tt>.</p>
 710
 711 <p>The iterators are (almost) models of the <a href="http://www.sgi.com/tech/stl/ForwardIterator.html">
 712 ForwardIterator</a> concept. The exceptions are that operator-&gt; and postincrement doesn't exist on
 713 them.</p>
 714
 715 <p>The <tt>lua_state()</tt> function returns the lua state where this object is stored. If you want
 716 to manipulate the object with lua functions directly you can push it onto the lua stack by calling
 717 <tt>pushvalue()</tt>. And set the object's value by calling <tt>set()</tt>, which will pop the top
 718 value from the lua stack and assign it to the object.</p>
 719
 720 <p>The operator== will run <tt>lua_equal()</tt>
 721 on the operands and return its result.</p>
 722
 723 <p>The <tt>int type()</tt> member function will return the lua type of the object. It will return
 724 the same values as <tt>lua_type()</tt>.</p>
 725
 726 <p>The <tt>is_valid</tt> function tells you wether the object has been initialized or not. When created
 727 with its default constructor, objects are invalid. To make an object valid, you can assign it a value. If
 728 you want to invalidate an object you can simply assign it an invalid object.</p>
 729
 730 <p>The <tt>operator bool()</tt>
 731 isn't really an implicit cast to bool, but an implicit cast to a member pointer, since member pointers
 732 don't have any arithmetic operators on them (which can cause hard to find errors). The functionality of
 733 the cast-operator is equivalent to <tt>is_valid()</tt>. This means that:</p>
 734
 735 <pre>
 736 object o;
 737 // ...
 738 if (o.is_valid())
 739 {
 740         // ...
 741 }
 742 </pre>
 743
 744 <p>is equivalent to:</p>
 745
 746 <pre>
 747 object o;
 748 // ...
 749 if (o)
 750 {
 751         // ...
 752 }
 753 </pre>
 754
 755 <p>The application operator will call the value as if it was a function. You can give it any number
 756 of parameters (currently the <tt>default_policy</tt> will be used for the conversion). The returned
 757 object refers to the return value (currently only one return value is supported). This operator may
 758 throw <tt>luabind::error</tt> if the function call fails. If you want to specify
 759 <a href="#policies">policies</a> to your function call, you can use index-operator (operator[]) on
 760 the function call, and give the policies within the [ and ]. Like this:</p>
 761
 762 <pre>
 763 my_function_object(2, 8, new my_complex_structure(6)) [ adopt(_3) ];
 764 </pre>
 765
 766 <p>This tells luabind to make lua adopt the ownership and responsibility for the pointer passed in
 767 to the lua-function.</p>
 768
 769 <p>It's important that all instances of <tt>object</tt> has been destructed by the time the lua state
 770 is closed. The object will keep a pointer to the lua state and release its lua object in its
 771 destructor.</p>
 772
 773 <p>Here's an example of how a function can use a table.</p>
 774
 775 <pre>
 776 void my_function(const object&amp; table)
 777 {
 778         if (table.type() == LUA_TTABLE)
 779         {
 780                 table["time"] = std::clock();
 781                 table["name"] = std::rand() &lt; 500 ? "unusual" : "usual";
 782
 783                 std::cout &lt;&lt; object_cast&lt;std::string&gt;(table[5]) &lt;&lt; "\n";
 784         }
 785 }
 786 </pre>
 787
 788 <p>If you take a <tt>luabind::object</tt> as a parameter to a function, any lua value will match that parameter.
 789 That's why we have to make sure it's a table before we index into it.</p>
 790
 791 <h2><a name="wrap_fun"></a>related functions</h2>
 792
 793 <p>
 794 There are a couple of functions related to objects and tables.
 795 </p>
 796
 797 <h3><tt>T object_cast&lt;<i>Type</i>&gt;(const&nbsp;object&amp;);</tt><br>
 798 <tt>T object_cast&lt;<i>Type</i>&gt;(const&nbsp;object&amp;, const&nbsp;Policies&amp;);</tt><br>
 799 <tt>boost::optional&lt;T&gt; object_cast_nothrow&lt;<i>Type</i>&gt;(const&nbsp;object&amp;);</tt><br>
 800 <tt>boost::optional&lt;T&gt; object_cast_nothrow&lt;<i>Type</i>&gt;(const&nbsp;object&amp;, const&nbsp;Policies&amp;);</tt></h3>
 801 <p>The <tt>object_cast</tt> function casts the value of an <tt>object</tt> to a C++ value. You
 802 can supply a policy to handle the conversion from lua to C++. If the cast cannot be made a
 803 <tt>cast_failed</tt> exception will be thrown. If you have defined <tt>LUABIND_NO_ERROR_CHECKING</tt>
 804 (see <a href="#config">configuration</a>) no checking will occur, and if the cast is invalid the
 805 application may very well crash. The nothrow versions will return an uninitialized <tt>boost::optional&lt;T&gt;</tt>
 806 object, to indicate that the cast could not be performed.</p>
 807
 808 <h3><tt>object get_globals(lua_State*);</tt><br>
 809 <tt>object get_registry(lua_State*);</tt></h3>
 810 <p>These functions returns the global environment table and the registry table respectively.</p>
 811
 812 <h3><tt>object newtable(lua_State*);</tt></h3>
 813 <p>This function creates a new table and return an object to it.</p>
 814
 815 <h2><a name="functor"></a>functor</h2>
 816
 817 <p>The <tt>functor</tt> class is similar to <tt>object</tt>, with the exception that it can
 818 only be used to store functions. If you take it as a parameter, it will only match functions.</p>
 819
 820 <p>To use it you need to include its header:</p>
 821
 822 <pre>
 823 #include &lt;luabind/functor.hpp&gt;
 824 </pre>
 825
 826 <p>It takes one template parameter, the return value of the lua function it represents.
 827 Currently the functor can have at most one return value (unlike lua funcions). It has the
 828 following synopsis:</p>
 829
 830 <pre>
 831 template&lt;class Ret&gt;
 832 class functor
 833 {
 834 public:
 835
 836         functor(lua_State*, const char* name);
 837         functor(const functor&amp;);
 838
 839         ~functor();
 840
 841         bool is_valid() const;
 842         operator bool() const;
 843
 844         <i>&lt;implementation-defined&gt;</i> operator()() const;
 845
 846         template&lt;class A0&gt;
 847         <i>&lt;implementation-defined&gt;</i> operator()(const A0&amp;) const;
 848
 849         template&lt;class A0, class A1&gt;
 850         <i>&lt;implementation-defined&gt;</i> operator()(const A0&amp;, const A1&amp;) const;
 851
 852         /* ... */
 853 };
 854 </pre>
 855
 856 <p>The application operator takes any parameters. The parameters are converted into lua and the
 857 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
 858 return value to give policies to the call. You do this the same way as you do with <a href="#object">objects</a>,
 859 using the operator[], and giving the policies inside the brackets.</p>
 860
 861 <p>The <tt>is_valid()</tt> function works just like the one on <a href="#object"><tt>object</tt></a>, it tells you if
 862 the functor has been assigned with a valid lua function. The <tt>operator bool()</tt> is an alias for this member function
 863 and also works just as the one found in <a href="#object"><tt>object</tt></a>.</p>
 864
 865 <p>For example, if you have the following lua function:</p>
 866
 867 <pre>
 868 function f(a, b)
 869         return a + b
 870 end
 871 </pre>
 872
 873 <p>You can expose it to C++ like this:</p>
 874
 875 <pre>
 876 functor&lt;int&gt; f(L, "f");
 877
 878 std::cout &lt;&lt; f(3, 5) &lt;&lt; "\n";
 879 </pre>
 880
 881 <p>Which will print out the sum of 3 and 5. Note that you can pass any parameters to the
 882 application operator of <tt>luabind::functor</tt>, this is because lua doesn't have
 883 signatures for its functions. All lua functions take any number of parameters
 884 of any type.</p>
 885
 886 <p>If we have a C++ function that takes a <tt>luabind::functor</tt> and registers it, it will accept lua
 887 functions passed to it. This enables us to expose APIs that requires you to
 888 register callbacks. For example, if your C++ API looks like this:</p>
 889
 890 <pre>
 891 void set_callback(void(*)(int, int));
 892 </pre>
 893
 894 <pre>
 895 object o;
 896 // ...
 897 if (o.is_valid())
 898 {
 899         // ...
 900 }
 901 </pre>
 902
 903
 904 <p>And you want to expose it to lua, you have to wrap the
 905 call to the lua function inside a real C++ function, like this:</p>
 906
 907 <pre>
 908 functor&lt;void&gt; lua_callback;
 909
 910 void callback_wrapper(int a, int b)
 911 {
 912         lua_callback(a, b);
 913 }
 914
 915 void set_callback_wrapper(const functor&lt;void&gt;&amp; f)
 916 {
 917         lua_callback = f;
 918         set_callback(&amp;callback_wrapper);
 919 }
 920 </pre>
 921
 922 <p>And then register <tt>set_callback_wrapper</tt> instead of registering <tt>set_callback</tt>.
 923 This will have the effect that when one tries to register the callback from lua, your
 924 <tt>set_callback_wrapper</tt> will be called instead and first set the lua fuctor to the given function.
 925 It will the call the real <tt>set_callback</tt> with the <tt>callback_wrapper</tt>. The
 926 <tt>callback_wrapper</tt> will be called whenever the callback should be called, and it will simply
 927 call the lua function that we registered.</p>
 928
 929 <p>You can also use <a href="#wrap_fun"><tt>object_cast</tt></a> to cast an object to a <tt>functor</tt>.</p>
 930
 931 <h1><a name="class_lua"></a>Defining classes in lua</h1>
 932
 933 <p>In addition to binding C++ functions and classes with
 934 lua, luabind also provide an oo-system in lua.</p>
 935
 936 <pre>
 937 class 'lua_testclass'
 938
 939 function lua_testclass:__init(name)
 940         self.name = name
 941 end
 942
 943 function lua_testclass:print()
 944         print(self.name)
 945 end
 946
 947 a = lua_testclass('example')
 948 a:print()
 949 </pre>
 950
 951 <p>Inheritance can be used between lua-classes:</p>
 952
 953 <pre>
 954 class 'derived' (lua_testclass)
 955
 956 function derived:__init() super('derived name')
 957 end
 958
 959 function derived:print()
 960         print('Derived:print() -&gt; ')
 961         lua_testclass.print(self)
 962 end
 963 </pre>
 964
 965 <p>Here the <tt>super</tt> keyword is
 966 used in the constructor to initialize the baseclass. The user is required to
 967 call <tt>super</tt> first in the constructor.</p>
 968
 969 <p>As you can see in this example, you can call the
 970 baseclass' member functions. You can find all member functions in the baseclass,
 971 but you will have to give the this-pointer as first argument (<tt>self</tt> that is).</p>
 972
 973 <h2><a name="class_lua_derive"></a>deriving in lua</h2>
 974
 975 <p>It is also possible to derive lua classes from C++
 976 classes, and override virtual functions with lua functions. To do this we have
 977 to create a wrapper class for our C++ baseclass. This is the class that will
 978 hold the lua object when we instantiate a lua class.</p>
 979
 980 <p>The wrapper class has to provide the same constructors
 981 as the baseclass, with the addition of one extra parameter: <tt>luabind::object</tt>.
 982 This is the reference to the lua object that should be held by the wrapper, and should
 983 be stored in a member variable as done in the sample below.</p>
 984
 985 <pre>
 986 class baseclass
 987 {
 988 public:
 989         baseclass(const char* s)        { std::cout &lt;&lt; s &lt;&lt; "\n"; }
 990         virtual void f(int a) { std::cout &lt;&lt; "f(" &lt;&lt; a &lt;&lt; ")\n"; }
 991 };
 992
 993 struct baseclass_wrapper: baseclass
 994 {
 995         luabind::object m_l;
 996         baseclass_wrapper(luabind::object l, const char* s): baseclass(s), m_l(l) {}
 997
 998         virtual void f(int a) { call_member&lt;void&gt;(m_l, "f", a); }
 999         static void f_static(baseclass* ptr, int a)
1000         {
1001                 return ptr-&gt;baseclass::f(a);
1002         }
1003 };
1004 </pre>
1005 <pre>
1006 class_&lt;baseclass, baseclass_wrapper&gt;(L, "baseclass")
1007         .def(constructor&lt;const char*&gt;())
1008         .def("f", &amp;baseclass_wrapper::f_static)
1009         ;
1010 </pre>
1011
1012 <p>Note that if you have both baseclasses and a baseclass
1013 wrapper, you must give both <tt>bases</tt> and the
1014 baseclass wrapper type as template parameter to <tt>class_</tt>. The order
1015 in which you specify them is not important.</p>
1016
1017 <p>If we didn't have a class wrapper, it would not be possible to pass a lua class
1018 back to C++. Since the entrypoints of the virtual functions would still point to
1019 the C++ baseclass, and not to the functions defined in lua. That's why we need
1020 one function that calls the baseclass' real functon (used if the lua class
1021 doesn't redefine it) and one virtual function that dispatches the call into lubind,
1022 to allow it to select if a lua function should be called, or if the original
1023 function should be called. If you don't intend to derive from a C++ class, or if
1024 it doesn't have any virtual member functions, you can register it without a
1025 class wrapper.</p>
1026
1027 <p>You don't need to have a class wrapper in order to derive from a class,
1028 but if it has virtual functions you may have silent errors. The rule of thumb is:
1029 If your class has virtual functions, create a wrapper type, if it doesn't don't create
1030 a wrapper type.</p>
1031
1032 <h1><a name="policies"></a>Parameter policies</h1>
1033
1034 <p>Sometimes it is necessary to control how luabind passes
1035 arguments and return value, to do this we have policies. These are the
1036 policies that can be used:</p>
1037
1038 <h2><a name="policies_copy"></a>copy</h2>
1039
1040 <p>This will make a copy of the parameter. This is the
1041 default behavior when passing parameters by-value. Note that this can only be
1042 used when passing from C++ to lua. This policy requires that the parameter
1043 type has a copy constructor.</p>
1044
1045 <p>To use this policy you need to include <tt>&lt;luabind/copy_policy.hpp&gt;</tt>.</p>
1046
1047 <h2><a name="policies_adopt"></a>adopt</h2>
1048
1049 <p>This will transfer ownership of the parameter.</p>
1050 <p>Consider making a factory function in C++ and exposing
1051 it to lua:</p><pre>base* create_base()
1052 {
1053         return new base();
1054 }
1055 </pre>
1056
1057 <pre>
1058 function(L, "create_base", create_base);
1059 </pre>
1060
1061 <p>Here we need to make sure lua understands that it should
1062 adopt the pointer returned by the factory-function. This can be done using the
1063 adopt-policy.</p>
1064
1065 <pre>
1066 function(L, "create_base", adopt(return_value));
1067 </pre>
1068
1069 <p>To specify multiple policies we just separate them with '+'.</p>
1070
1071 <pre>
1072 base* set_and_get_new(base* ptr)
1073 {
1074         base_ptrs.push_back(ptr);
1075         return new base();
1076 }
1077 </pre>
1078
1079 <pre>
1080 function(L, "set_and_get_new", &amp;set_and_get_new, adopt(return_value) + adopt(_1));
1081 </pre>
1082
1083 <p>To use this policy you need to include <tt>&lt;luabind/adopt_policy.hpp&gt;</tt>.</p>
1084
1085 <h2><a name="policies_dependency"></a>depedency</h2>
1086
1087 <p>The dependency policy is used to create life-time dependencies between values. Consider the following example:</p>
1088
1089 <pre>
1090 struct A
1091 {
1092         B m_member;
1093
1094         const B&amp; get_member()
1095         {
1096                 return m_member;
1097         }
1098 };
1099 </pre>
1100
1101 <p>When wrapping this class, we would do something like:</p>
1102
1103 <pre>
1104 class_&lt;A&gt;(L, "A")
1105         .def(constructor&lt;&gt;())
1106         .def("get_member", &amp;A::get_member)
1107         ;
1108 </pre>
1109
1110 <p>However, since the return value of get_member is a reference to a member of A, this will create
1111 some life-time issues. For example:</p>
1112
1113 <pre>
1114 a = A()
1115 b = a:get_member() -- b points to a member of a
1116 a = nil
1117 collectgarbage(0)  -- since there are no references left to a, it is removed
1118                    -- at this point, b is pointing into a removed object
1119 </pre>
1120
1121 <p>When using the dependency-policy, it is possible to tell luabind to tie the lifetime of one
1122 object to another, like this:</p>
1123
1124 <pre>
1125 class_&lt;A&gt;(L, "A")
1126         .def(constructor&lt;&gt;())
1127         .def("get_member", &amp;A::get_member, dependency(result, self))
1128         ;
1129 </pre>
1130
1131 <p>This will create a dependency between the return-value of the function, and the self-object. This means
1132 that the self-object will be kept alive as long as the result is still alive.</p>
1133
1134 <pre>
1135 a = A()
1136 b = a:get_member() -- b points to a member of a
1137 a = nil
1138 collectgarbage(0)  -- a is dependent on b, so it isn't removed
1139 b = nil
1140 collectgarbage(0)  -- all dependencies to a gone, a is removed
1141 </pre>
1142
1143 <p>To use this policy you need to include <tt>&lt;luabind/dependency_policy.hpp&gt;</tt>.</p>
1144
1145 <h2><a name="policies_return_ref"></a>return_reference_to</h2>
1146
1147 <p>It is very common to return references to arguments or the this-pointer to allow for chaining in C++.</p>
1148 <pre>
1149 struct A
1150 {
1151         float m_val;
1152
1153         A&amp; set(float v)
1154         {
1155                 m_val = v;
1156                 return *this;
1157         }
1158 };
1159 </pre>
1160
1161 <p>When luabind generates code for this, it will create a new object for the return-value, pointing to the self-object. This
1162 isn't a problem, but could be a bit inefficient. When using the return_reference_to-policy we have the ability to tell
1163 luabind that the return-value is already on the lua stack.</p>
1164
1165 <pre>
1166 class_&lt;A&gt;(L, "A")
1167         .def(constructor&lt;&gt;())
1168         .def("set", &amp;A::set, return_reference_to(self))
1169         ;
1170 </pre>
1171
1172 <p>Instead of creating a new object, luabind will just copy the object that is already on the stack.</p>
1173 <p>NOTE! This policy ignores all type information and should be used only it situations where the parameter type
1174 is a perfect match to the return-type (such as in the example).</p>
1175
1176 <p>To use this policy you need to include <tt>&lt;luabind/return_reference_to_policy.hpp&gt;</tt>.</p>
1177
1178 <h2><a name="policies_out"></a>out_value</h2>
1179
1180 <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>
1181
1182 <pre>
1183 void f(float&amp; val) { val = val + 10.f; }
1184 or
1185 void f(float* val) { *val = *val + 10.f; }
1186 </pre>
1187
1188 <p>Can be wrapped by doing:</p>
1189
1190 <pre>
1191 function(L, "f", &amp;f, out_value(_1))
1192 </pre>
1193
1194 <p>When invoking this function from lua it will return the value assigned to its parameter.</p>
1195
1196 <pre>
1197 a = f(10) -- a is now 20
1198 </pre>
1199
1200 <p>When this policy is used in conjunction with user define types we often need to do ownership transfers.</p>
1201
1202 <pre>
1203 struct A
1204 {
1205 };
1206
1207 void f(A*&amp; obj) { obj = new A(); }
1208 or
1209 void f(A** obj) { *obj = new A(); }
1210 </pre>
1211
1212 <p>Here we need to make sure luabind takes control over object returned, for this we use the <tt>adopt</tt> policy</p>
1213
1214 <pre>
1215 class_&lt;A&gt;(L, "A");
1216
1217 function(L, "f", &amp;f, out_value(_1, adopt(_2)));
1218 </pre>
1219
1220 <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>
1221
1222 <p>To use this policy you need to include <tt>&lt;luabind/out_value_policy.hpp&gt;</tt>.</p>
1223
1224 <h2><a name="policies_pure_out"></a>pure_out_value</h2>
1225
1226 <p>This policy works in exactly the same way as <tt>out_value</tt>, except that it replaces the parameters with default-constructed
1227 objects.</p>
1228
1229 <pre>
1230 void get(float&amp; x, float&amp; y)
1231 {
1232         x = 3.f;
1233         y = 4.f;
1234 }
1235
1236 function(L, "get", &amp;get, pure_out_value(_1) + pure_out_value(_2));
1237 </pre>
1238 <pre>
1239 x,y = get()
1240 print(x,y)  -- prints '3   4'
1241 </pre>
1242
1243 <p>Like out_value, it is possible to specify an internal policy used then converting the values back to lua.</p>
1244
1245 <pre>
1246 void get(test_class*&amp; obj)
1247 {
1248         obj = new test_class();
1249 }
1250
1251 function(L, "get", &amp;get, pure_out_value(_1, adopt(_1)));
1252 </pre>
1253
1254 <h2><a name="policies_discard_result"></a>discard_result</h2>
1255
1256 <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>
1257
1258 <pre>
1259 struct simple
1260 {
1261         simple&amp; set_name(const std::string&amp; n)
1262         {
1263                 name = n;
1264                 return *this;
1265         }
1266
1267         std::string name;
1268 };
1269
1270 class_&lt;simple&gt;(L, "simple")
1271         .def("set_name", &amp;simple::set_name, discard_result)
1272         ;
1273 </pre>
1274
1275 <p>To use this policy you need to include <tt>&lt;luabind/discard_result.hpp&gt;</tt>.</p>
1276
1277 <h2><a name="policies_custom"></a>custom</h2>
1278
1279 <p>The policies don't have a stable API yet.</p>
1280
1281 <h2><a name="policies_user_converter"></a>user defined converter</h2>
1282
1283 <p>The policies don't have a stable API yet.</p>
1284
1285 <h1><a name="config"></a>Configuration</h1>
1286
1287 <p>You can configure luabind by defining macros before you include any of luabind's headers.
1288 It is important that you have the same settings in all your compilation units.
1289 The available configuration options follows:</p>
1290
1291 <table border="1" cellspacing="0" cellpadding="10">
1292         <tr>
1293                 <td valign="top"><tt>LUABIND_MAX_ARITY</tt></td>
1294                 <td>
1295                         <p>Controls the maximum arity of functions that are registered
1296                         with luabind. You can't register functions that takes more
1297                         parameters than the number this macro is set to. It defaults
1298                         to 4, so, if your functions have greater arity you have to
1299                         redefine it. A high limit will increase compilation times.</p>
1300                 </td>
1301         </tr>
1302         <tr>
1303                 <td valign="top"><tt>LUABIND_MAX_BASES</tt></td>
1304                 <td>
1305                         <p>Controls the maximum number of classes one class can derive from
1306                         in luabind (the number of classes specified within
1307                         <tt>bases&lt;&gt;</tt>). <tt>LUABIND_MAX_BASES</tt> defaults to 4.
1308                         A high limit will increase compilation times.</p>
1309                 </td>
1310         </tr>
1311         <tr>
1312                 <td valign="top"><tt>LUABIND_NO_ERROR_CHECKING</tt></td>
1313                 <td>
1314                         <p>If this macro is defined, all the lua code is expected only to make
1315                         legal calls. If illegal function calls are made (eg. giving parameters
1316                         that doesn't match the function signature) they will not be detected
1317                         by luabind and the application will probably crash. Error checking
1318                         could be disabled when shipping a release build (given that no end-user
1319                         has access to write custom lua code). Note that function parameter
1320                         matching will be done if a function is overloaded, since otherwise it's
1321                         impossible to know which one was called. Functions will still be able
1322                         to throw exceptions when error checking is disabled.</p>
1323
1324                         <p>Functions will still be able to throw exceptions, they will be
1325                         caught by luabind and propagated with <tt>lua_error()</tt>.</p>
1326                 </td>
1327         </tr>
1328         <tr>
1329                 <td valign="top"><tt>LUABIND_DONT_COPY_STRINGS</tt></td>
1330                 <td>
1331                         <p>If this macro is defined, luabind will expect that all strings given
1332                         to the def() methods are static constant strings (given as string
1333                         constants for example). luabind will not copy the strings if you
1334                         enable this setting, but just keep the char pointers. This may be
1335                         especially useful for embedded systems or consoles where heap
1336                         allocations should be minimized.</p>
1337                 </td>
1338         </tr>
1339         <tr>
1340                 <td valign="top"><tt>LUABIND_NO_EXCEPTIONS</tt></td>
1341                 <td>
1342                         <p>This define will disable all usage of try, catch and throw in
1343                         luabind. This will in many cases disable run-time errors, when
1344                         performing invalid casts or calling lua-functions that fails or
1345                         returns values that cannot be converted by the given policy.
1346                         luabind requires that no function called directly or indirectly
1347                         by luabind throws an exception (throwing exceptions through
1348                         lua has undefined behavior).</p>
1349
1350                         <p>Where exceptions are the onlyway to get an error report from
1351                         luabind, they will be replaced with an assert.</p>
1352                 </td>
1353         </tr>
1354         <tr>
1355                 <td valign="top">
1356                         <p><tt>LUABIND_TYPE_INFO</tt><br>
1357                         <tt>LUABIND_TYPE_INFO_EQUAL(i1,i2)</tt><br>
1358                         <tt>LUABIND_TYPEID(t)</tt><br>
1359                         <tt>LUABIND_INVALID_TYPE_INFO</tt></p>
1360                 </td>
1361                 <td>
1362                         <p>If you don't want to use the rtti supplied by C++
1363                         you can supply your own type-info structure with the
1364                         LUABIND_TYPE_INFO define. Your type-info structure must
1365                         be copyable and must be able to compare itself against
1366                         other type-info structures. You supply the compare
1367                         function through the LUABIND_TYPE_INFO_EQUAL()
1368                         define. It should compare the two type-info structures
1369                         it is given and return true if they represent the same type
1370                         and false otherwise. You also have to supply a function
1371                         to generate your type-info structure. You do this through
1372                         the LUABIND_TYPEID() define. It should return your type-info
1373                         structure and it takes a type as its parameter. That is,
1374                         a compile time parameter. LUABIND_INVALID_TYPE_INFO macro
1375                         should be defined to an invalid type. No other type should
1376                         be able tp produce this type info. To use it you probably
1377                         have to make a traits class with specializations for all
1378                         classes that you have type-info for. Like this:</p>
1379
1380                         <pre>
1381 class A;
1382 class B;
1383 class C;
1384
1385 template&lt;class T&gt; struct typeinfo_trait;
1386
1387 template&lt;&gt; struct typeinfo_trait&lt;A&gt; { enum { type_id = 0 }; };
1388 template&lt;&gt; struct typeinfo_trait&lt;B&gt; { enum { type_id = 1 }; };
1389 template&lt;&gt; struct typeinfo_trait&lt;C&gt; { enum { type_id = 2 }; };
1390                         </pre>
1391
1392                         <p>If you have set up your own rtti system like this (by using integers to identify types)
1393                         you can have luabind use it with the following defines</p>
1394
1395                         <pre>
1396 #define LUABIND_TYPE_INFO int
1397 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) i1 == i2
1398 #define LUABIND_TYPEID(t) typeinfo_trait&lt;t&gt;::type_id
1399 #define LUABIND_INVALID_TYPE_INFO -1
1400                         </pre>
1401
1402                         <p>The default behaviour, if you don't define any of these three, is to use the builtin
1403                         rtti support in C++.</p>
1404
1405                         <pre>
1406 #define LUABIND_TYPE_INFO const std::type_info*
1407 #define LUABIND_TYPEID(t) &amp;typeid(t)
1408 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
1409 #define LUABIND_INVALID_TYPE_INFO &amp;typeid(detail::null_type)
1410                         </pre>
1411
1412                         <p>currently the type given through LUABIND_TYPE_INFO must be less-than comparable!</p>
1413                 </td>
1414         </tr>
1415         <tr>
1416                 <td valign="top"><tt>NDEBUG</tt></td>
1417                 <td>
1418                         <p>This define will disable all asserts and should be defined in a release build.</p>
1419                 </td>
1420         </tr>
1421 </table>
1422
1423 <h1><a name="implementation_notes"></a>Implementation notes</h1>
1424
1425 <p>The classes and objects are implemented as userdata in lua. To make sure that
1426 the user data really is the internal structure it is supposed to be, we tag their
1427 metatables. A userdata who's metatable contains a boolean member named
1428 <tt>"__luabind_classrep"</tt> is expected to be a class exported by luabind.
1429 A userdata who's metatable contains a boolean member named <tt>"__luabind_class"</tt>
1430 is expected to be an instantiation of a luabind class.</p>
1431
1432 <p>This means that if you make your own userdata and tags its metatable with the
1433 exact same names, you can very easily fool luabind and crash the application.</p>
1434
1435 <p>In the lua registry, luabind keeps an entry called "<tt>__luabind_classes</tt>"
1436 and "<tt>__luabind_free_functions</tt>". These should not be removed or overwritten.</p>
1437
1438 <p>In the global table, a variable called <tt>super</tt> is used every time a constructor
1439 in a lua-class is called. This is to make it easy for that constructor to call its base
1440 class' constructor. So, if you have a global variable named <tt>super</tt> it may very
1441 well be overwritten. This is probably not the best solution, and this restriction may very
1442 well be removed in the future.</p>
1443
1444 <p>Inside the <tt>luabind</tt> namespace, there's another namespace called <tt>detail</tt>.
1445 This namespace contains non-public classes and are not supposed to be used directly.</p>
1446
1447 <h1><a name="error_messages"></a>Error messages</h1>
1448
1449 <ul>
1450         <li>cannot set attribute '<i>&lt;class-name&gt;</i>.<i>&lt;attribute-name&gt;</i>'
1451         <p>There is no data member named <i>&lt;attribute-name&gt;</i> in the class <i>&lt;class-name&gt;</i>, or
1452         there's no setter-method registered on that property name. See the <a href="#class_property">properties</a> section.</p>
1453
1454         <li><i>&lt;class-name&gt;</i>() threw an exception
1455         <li><i>&lt;class-name&gt;</i>:<i>&lt;function-name&gt;</i>() threw an exception
1456         <p>The class' constructor or member function threw an unknown exception. Known exceptions are <tt>const&nbsp;char*</tt>,
1457         <tt>std::exception</tt>. See the <a href="#fun_exception">exceptions</a> section.</p>
1458
1459         <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>
1460         <li>no match for function call '<i>&lt;function-name&gt;</i>' with the parameters (<i>&lt;parameter-types&gt;</i>)
1461         <li>no constructor of <i>&lt;class-name&gt;</i> matched the arguments (<i>&lt;parameter-types&gt;</i>)
1462         <li>no operator <i>&lt;operator-name&gt;</i> matched the arguments (<i>&lt;parameter-types&gt;</i>)
1463         <p>No function/operator with the given name takes the parameters you gave it. You have either misspelled the function name,
1464         or given it incorrect parameters. This error is followed by a list of possible candidate functions to help you figure out what
1465         parameter has the wrong type. If the candidate list is empty there's no function at all with that name. See the
1466         <a href="#fun_sigmatch">signature matching</a> section.</p>
1467
1468         <li>call of overloaded '<i>&lt;class-name&gt;</i>:<i>&lt;function-name&gt;</i>(&lt;<i>parameter-types&gt;</i>)' is ambiguous
1469         <li>ambiguous match for function call '<i>&lt;function-name&gt;</i>' with the parameters (<i>&lt;parameter-types&gt;</i>)
1470         <li>call of overloaded constructor '<i>&lt;class-name&gt;</i>(<i>&lt;parameter-types&gt;</i>)' is ambiguous
1471         <li>call of overloaded operator <i>&lt;operator-name&gt;</i> (<i>&lt;parameter-types&gt;</i>) is ambiguous
1472         <p>This means that the function/operator you are trying to call has at least one other overload that matches the arguments
1473         just as good as the first overload.</p>
1474
1475         <li>cannot derive from C++ class '<i>&lt;class-name&gt;</i>'. It does not have a wrapped type.
1476         <p>You are trying to derive a lua class from a C++ class that doesn't have a wrapped type. You have to give
1477         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>
1478
1479         <li>derived class must call super on base
1480         <li>cannot set property '<i>&lt;class-name&gt;</i>.<i>&lt;attribute_name&gt;</i>' because it's read only
1481         <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
1482         class registration and use <tt>def_readwrite()</tt> instead of <tt>def_readonly()</tt>. Alternatively (if your attribute
1483         is a property with getter and setter functions), you have to give a setter function when declaring your attribute. See
1484         the <a href="#class_property">properties</a> section.</p>
1485
1486         <li>no static '<i>&lt;enum-name&gt;</i>' in class '<i>&lt;class-name&gt;</i>'
1487         <p>You will get this error message if you are trying to access an enum that doesn't exist. Read about how to
1488         <a href="#class_enum">declare enums</a>.</p>
1489
1490         <li>expected base class
1491         <p>You have written a malformed <a href="#class_lua">class definition in lua</a>. The format is:
1492         <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
1493         a base class, you have to break the line directly after the class declaration.</p>
1494
1495         <li>invalid construct, expected class name
1496         <p>You have written a malformed <a href="#class_lua">class definition in lua</a>. The <tt>class</tt> function expects
1497         a string as argument. That string is the name of the lua class to define.</p>
1498 </ul>
1499
1500 <h1><a name="faq"></a>FAQ</h1>
1501 <ul>
1502         <li><h3>What's up with __cdecl and __stdcall?</h3>
1503
1504         <p>If you're having problem with functions that cannot be converted from
1505         <tt>'void&nbsp;(__stdcall&nbsp;*)(int,int)'</tt> to <tt>'void&nbsp;(__cdecl&nbsp;*)(int,int)'</tt>.
1506         You can change the project settings to make the compiler generate functions with
1507         <tt>__cdecl</tt> calling conventions. This is a problem in developer studio.</p>
1508
1509         <li><h3>What's wrong with functions taking variable number of arguments?</h3>
1510         <p>You cannot register a function with ellipses in its signature. Since ellipses doesn't preserve
1511         typesafety, those should be avoided anyway.</p>
1512
1513         <li><h3>Internal structure overflow in VC</h3>
1514         <p>If you, in visual studio,  get <tt>fatal error C1204: compiler limit : internal
1515         structure overflow</tt>. You should try to split that compilation unit up
1516         in smaller ones.</p>
1517
1518         <li><h3>What's wrong with precompiled headers in VC?</h3>
1519         <p>Visual Studio doesn't like anonymous namespaces in its precompiled headers. If you encounter this
1520         problem you can disable precompiled headers for the compilation unit (cpp-file) that uses luabind.</p>
1521
1522         <li><h3>error C1076: compiler limit - internal heap limit reached in VC</h3>
1523         <p>In visual studio you will probably hit this error. To fix it you have to increase the internal heap
1524         with a command-line option. We managed to compile the test suit with /Zm300, but you may need a larger
1525         heap then that.</p>
1526
1527         <li><h3>error C1055: compiler limit : out of keys in VC</h3>
1528         <p>It seems that this error occurs when too many <tt>assert()</tt> are used in a program. Or more
1529         specifically, the <tt>__LINE__</tt> macro. It seems to be fixed by changing /ZI (Program database
1530         for edit and continue) to /Zi (Program database).</p>
1531
1532         <li><h3>How come my executable is huge?</h3>
1533         <p>If you're compiling in debug mode, you will probably have alot of debug-info and symbols (luabind
1534         consists of alot of functions). Also, if built in debug mode, no optimizations were applied, luabind
1535         relies on that the compiler is able to inline functions. If you built in release mode, try running
1536         <tt>strip</tt> on your executable to remove export-symbols, this will trim down the size.</p>
1537
1538 </ul>
1539
1540 <h1><a name="future"></a>Future additions</h1>
1541 <ul>
1542         <li>Smart pointer wrappers. wraps smart pointers by just
1543                 keeping one copy of it and let lua garbage collect it when there's no more
1544                 references to it.
1545         <li>Scopes and namespaces. Add the ability to register classes and
1546                 functions within lua tables.
1547         <li>A mechanism for wrapping iterators with generators.
1548 </ul>
1549
1550 <h1><a name="issues"></a>Known issues</h1>
1551 <ul>
1552         <li>If one class registers two functions with the same name and the same signature,
1553         there's currently no error. The last registered function will be the one that's used.
1554         <li>In vc7, classes can not be called <tt>test</tt>. (due to boost.mpl)
1555 </ul>
1556
1557 <h1><a name="acknowledgments"></a>Acknowledgments</h1>
1558
1559 <p>This library was written by <a href="mailto:dalwan01@student.umu.se">Daniel Wallin</a>
1560 and <a href="mailto: c99ang@cs.umu.se">Arvid Norberg</a>. © Copyright 2003. All rights reserved.</p>
1561
1562 <p>This library was inspired by Dave Abrahams'
1563 <a href="http://www.boost.org/libs/python/doc/index.html">Boost.Python</a> library which can be found in the
1564 <a href="http://www.boost.org">boost</a> library.</p>
1565 <p>
1566         <a href="http://validator.w3.org/check/referer">
1567         <img style="border:0;width:88px;height:31px"
1568         src="http://www.w3.org/Icons/valid-html401"
1569         alt="Valid HTML 4.01!"></a>
1570
1571         <a href="http://jigsaw.w3.org/css-validator/">
1572         <img style="border:0;width:88px;height:31px"
1573         src="http://jigsaw.w3.org/css-validator/images/vcss"
1574         alt="Valid CSS!"></a>
1575
1576 </p>
1577
1578 </body></html>
1579