doc/docs.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
   7 <title>luabind</title>
   8 <meta name="author" content="Daniel Wallin, Arvid Norberg" />
   9 <meta name="copyright" content="Copyright Daniel Wallin, Arvid Norberg 2003." />
  10 <meta name="date" content="2006-03-26" />
  11 <style type="text/css">
  12
  13 /*
  14 :Author: David Goodger
  15 :Contact: goodger@users.sourceforge.net
  16 :date: $Date$
  17 :version: $Revision$
  18 :copyright: This stylesheet has been placed in the public domain.
  19
  20 Default cascading style sheet for the HTML output of Docutils.
  21 */
  22
  23 p {
  24   text-align: justify;
  25 }
  26
  27 .first {
  28   margin-top: 0 }
  29
  30 .last {
  31   margin-bottom: 0 }
  32
  33 a.toc-backref {
  34   text-decoration: none ;
  35   color: black }
  36
  37 dt { /* used in FAQ */
  38   font-weight: bold ;
  39   margin-bottom: 0.2em
  40 }
  41
  42 dl {
  43   margin-left: 0.5em ;
  44   margin-right: 10em
  45 }
  46
  47 h3 {
  48   font-size: 90%
  49 }
  50
  51 dd {
  52   margin-bottom: 0.5em }
  53
  54 div.abstract {
  55   margin: 2em 5em }
  56
  57 div.abstract p.topic-title {
  58   font-weight: bold ;
  59   text-align: center }
  60
  61 div.attention, div.caution, div.danger, div.error, div.hint,
  62 div.important, div.note, div.tip, div.warning, div.admonition {
  63   margin: 2em ;
  64   border: medium outset ;
  65   padding: 1em }
  66
  67 div.attention p.admonition-title, div.caution p.admonition-title,
  68 div.danger p.admonition-title, div.error p.admonition-title,
  69 div.warning p.admonition-title {
  70   color: red ;
  71   font-weight: bold ;
  72   font-family: sans-serif }
  73
  74 div.hint p.admonition-title, div.important p.admonition-title,
  75 div.note p.admonition-title, div.tip p.admonition-title,
  76 div.admonition p.admonition-title {
  77   font-weight: bold ;
  78   font-family: sans-serif }
  79
  80 div.dedication {
  81   margin: 2em 5em ;
  82   text-align: center ;
  83   font-style: italic }
  84
  85 div.dedication p.topic-title {
  86   font-weight: bold ;
  87   font-style: normal }
  88
  89 div.figure {
  90   margin-left: 2em }
  91
  92 div.footer, div.header {
  93   font-size: smaller }
  94
  95 div.sidebar {
  96   margin-left: 1em ;
  97   border: medium outset ;
  98   padding: 0em 1em ;
  99   background-color: #ffffee ;
 100   width: 40% ;
 101   float: right ;
 102   clear: right }
 103
 104 div.sidebar p.rubric {
 105   font-family: sans-serif ;
 106   font-size: medium }
 107
 108 div.system-messages {
 109   margin: 5em }
 110
 111 div.system-messages h1 {
 112   color: red }
 113
 114 div.system-message {
 115   border: medium outset ;
 116   padding: 1em }
 117
 118 div.system-message p.system-message-title {
 119   color: red ;
 120   font-weight: bold }
 121
 122 div.topic {
 123   margin: 2em }
 124
 125 h1.title {
 126   text-align: center }
 127
 128 h2.subtitle {
 129   text-align: center }
 130
 131 hr {
 132   width: 75% }
 133
 134 ol.simple, ul.simple {
 135   margin-bottom: 1em }
 136
 137 ol.arabic {
 138   list-style: decimal }
 139
 140 ol.loweralpha {
 141   list-style: lower-alpha }
 142
 143 ol.upperalpha {
 144   list-style: upper-alpha }
 145
 146 ol.lowerroman {
 147   list-style: lower-roman }
 148
 149 ol.upperroman {
 150   list-style: upper-roman }
 151
 152 p.attribution {
 153   text-align: right ;
 154   margin-left: 50% }
 155
 156 p.caption {
 157   font-style: italic }
 158
 159 p.credits {
 160   font-style: italic ;
 161   font-size: smaller }
 162
 163 p.label {
 164   white-space: nowrap }
 165
 166 p.rubric {
 167   font-weight: bold ;
 168   font-size: larger ;
 169   color: maroon ;
 170   text-align: center }
 171
 172 p.sidebar-title {
 173   font-family: sans-serif ;
 174   font-weight: bold ;
 175   font-size: larger }
 176
 177 p.sidebar-subtitle {
 178   font-family: sans-serif ;
 179   font-weight: bold }
 180
 181 p.topic-title {
 182   font-weight: bold }
 183
 184 pre.address {
 185   margin-bottom: 0 ;
 186   margin-top: 0 ;
 187   font-family: serif ;
 188   font-size: 100% }
 189
 190 pre.line-block {
 191   font-family: serif ;
 192   font-size: 100% }
 193
 194 pre.literal-block, pre.doctest-block {
 195   margin-left: 2em ;
 196   margin-right: 2em ;
 197 /*  padding-left: 1em ;*/
 198   background-color: #eeeeee ;
 199 /*  border-left: solid 3px #c0c0c0*/ }
 200
 201 span.classifier {
 202   font-family: sans-serif ;
 203   font-style: oblique }
 204
 205 span.classifier-delimiter {
 206   font-family: sans-serif ;
 207   font-weight: bold }
 208
 209 span.interpreted {
 210   font-family: sans-serif }
 211
 212 span.option {
 213   white-space: nowrap }
 214
 215 span.option-argument {
 216   font-style: italic }
 217
 218 span.pre {
 219   white-space: pre }
 220
 221 span.problematic {
 222   color: red }
 223
 224 table {
 225   margin-top: 0.5em ;
 226   margin-bottom: 0.5em }
 227
 228 table.citation {
 229   border-left: solid thin gray ;
 230   padding-left: 0.5ex }
 231
 232 table.docinfo {
 233   margin: 2em 4em ;
 234   border: none }
 235
 236 table.footnote {
 237   border-left: solid thin black ;
 238   padding-left: 0.5ex }
 239
 240 td, th {
 241   padding-left: 0.5em ;
 242   padding-right: 0.5em ;
 243   vertical-align: top }
 244
 245 th.docinfo-name, th.field-name {
 246   font-weight: bold ;
 247   text-align: left ;
 248   white-space: nowrap ;
 249   border: none ;
 250   background-color: #f0f0f0
 251  }
 252
 253 h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
 254   font-size: 100% ;
 255   font-family: serif }
 256
 257 /*h1 { font-family: Arial, Helvetica, sans-serif; font-weight: bold; text-align: left; font-size: 140%; }
 258 h2 { font-family: Arial, Helvetica, sans-serif; font-weight: bold; text-align: left; font-size: 110%; }
 259 h3 { font-family: "courier new", courier, monospace; font-weight: bold; text-align: left; font-size: 100%; }
 260 */
 261 tt {
 262   /*background-color: #eeeeee*/
 263   color: #102eb0
 264 }
 265
 266 ul.auto-toc {
 267   list-style-type: none }
 268
 269 /* --- */
 270
 271 table {
 272   border-collapse: collapse;
 273   border: none;
 274 /*  border-bottom: 1px solid black;*/
 275   margin-left: 1em;
 276 }
 277
 278 td, th {
 279   border: none;
 280 }
 281
 282 th {
 283 /* border-top: 1px solid black;*/
 284   border-bottom: 1px solid black;
 285   text-align: left;
 286 }
 287
 288 a:link
 289 {
 290         font-weight: bold;
 291         color: #003366;
 292         text-decoration: none;
 293 }
 294
 295 a:visited
 296 {
 297         font-weight: bold;
 298         color: #003366;
 299         text-decoration: none;
 300 }
 301
 302 h3 {
 303   text-transform: uppercase
 304 }
 305
 306 </style>
 307 </head>
 308 <body>
 309 <div class="document" id="luabind">
 310 <h1 class="title">luabind</h1>
 311 <table class="docinfo" frame="void" rules="none">
 312 <col class="docinfo-name" />
 313 <col class="docinfo-content" />
 314 <tbody valign="top">
 315 <tr><th class="docinfo-name">Author:</th>
 316 <td>Daniel Wallin, Arvid Norberg</td></tr>
 317 <tr><th class="docinfo-name">Copyright:</th>
 318 <td>Copyright Daniel Wallin, Arvid Norberg 2003.</td></tr>
 319 <tr><th class="docinfo-name">Date:</th>
 320 <td>2006-03-26</td></tr>
 321 <tr><th class="docinfo-name">Revision:</th>
 322 <td>1.28</td></tr>
 323 <tr class="field"><th class="docinfo-name">License:</th><td class="field-body"><p class="first">Permission is hereby granted, free of charge, to any person obtaining a
 324 copy of this software and associated documentation files (the &quot;Software&quot;),
 325 to deal in the Software without restriction, including without limitation
 326 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 327 and/or sell copies of the Software, and to permit persons to whom the
 328 Software is furnished to do so, subject to the following conditions:</p>
 329 <p>The above copyright notice and this permission notice shall be included
 330 in all copies or substantial portions of the Software.</p>
 331 <p class="last">THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF
 332 ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
 333 TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 334 PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
 335 SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
 336 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 337 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 338 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
 339 OR OTHER DEALINGS IN THE SOFTWARE.</p>
 340 </td>
 341 </tr>
 342 </tbody>
 343 </table>
 344 <p>Note: This library is currently in public beta phase. This documentation
 345 should be considered beta as well. Please report any grammatical
 346 corrections/spelling corrections.</p>
 347 <div class="contents topic">
 348 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
 349 <ul class="auto-toc simple">
 350 <li><a class="reference" href="#introduction" id="id44" name="id44">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
 351 <li><a class="reference" href="#features" id="id45" name="id45">2&nbsp;&nbsp;&nbsp;Features</a></li>
 352 <li><a class="reference" href="#portability" id="id46" name="id46">3&nbsp;&nbsp;&nbsp;Portability</a></li>
 353 <li><a class="reference" href="#building-luabind" id="id47" name="id47">4&nbsp;&nbsp;&nbsp;Building luabind</a></li>
 354 <li><a class="reference" href="#basic-usage" id="id48" name="id48">5&nbsp;&nbsp;&nbsp;Basic usage</a><ul class="auto-toc">
 355 <li><a class="reference" href="#hello-world" id="id49" name="id49">5.1&nbsp;&nbsp;&nbsp;Hello world</a></li>
 356 </ul>
 357 </li>
 358 <li><a class="reference" href="#scopes" id="id50" name="id50">6&nbsp;&nbsp;&nbsp;Scopes</a></li>
 359 <li><a class="reference" href="#binding-functions-to-lua" id="id51" name="id51">7&nbsp;&nbsp;&nbsp;Binding functions to Lua</a><ul class="auto-toc">
 360 <li><a class="reference" href="#overloaded-functions" id="id52" name="id52">7.1&nbsp;&nbsp;&nbsp;Overloaded functions</a></li>
 361 <li><a class="reference" href="#signature-matching" id="id53" name="id53">7.2&nbsp;&nbsp;&nbsp;Signature matching</a></li>
 362 <li><a class="reference" href="#calling-lua-functions" id="id54" name="id54">7.3&nbsp;&nbsp;&nbsp;Calling Lua functions</a></li>
 363 <li><a class="reference" href="#using-lua-threads" id="id55" name="id55">7.4&nbsp;&nbsp;&nbsp;Using Lua threads</a></li>
 364 </ul>
 365 </li>
 366 <li><a class="reference" href="#binding-classes-to-lua" id="id56" name="id56">8&nbsp;&nbsp;&nbsp;Binding classes to Lua</a><ul class="auto-toc">
 367 <li><a class="reference" href="#overloaded-member-functions" id="id57" name="id57">8.1&nbsp;&nbsp;&nbsp;Overloaded member functions</a></li>
 368 <li><a class="reference" href="#properties" id="id58" name="id58">8.2&nbsp;&nbsp;&nbsp;Properties</a></li>
 369 <li><a class="reference" href="#enums" id="id59" name="id59">8.3&nbsp;&nbsp;&nbsp;Enums</a></li>
 370 <li><a class="reference" href="#operators" id="id60" name="id60">8.4&nbsp;&nbsp;&nbsp;Operators</a></li>
 371 <li><a class="reference" href="#nested-scopes-and-static-functions" id="id61" name="id61">8.5&nbsp;&nbsp;&nbsp;Nested scopes and static functions</a></li>
 372 <li><a class="reference" href="#derived-classes" id="id62" name="id62">8.6&nbsp;&nbsp;&nbsp;Derived classes</a></li>
 373 <li><a class="reference" href="#smart-pointers" id="id63" name="id63">8.7&nbsp;&nbsp;&nbsp;Smart pointers</a></li>
 374 <li><a class="reference" href="#splitting-class-registrations" id="id64" name="id64">8.8&nbsp;&nbsp;&nbsp;Splitting class registrations</a></li>
 375 </ul>
 376 </li>
 377 <li><a class="reference" href="#object" id="id65" name="id65">9&nbsp;&nbsp;&nbsp;Object</a><ul class="auto-toc">
 378 <li><a class="reference" href="#iterators" id="id66" name="id66">9.1&nbsp;&nbsp;&nbsp;Iterators</a></li>
 379 <li><a class="reference" href="#related-functions" id="id67" name="id67">9.2&nbsp;&nbsp;&nbsp;Related functions</a></li>
 380 <li><a class="reference" href="#assigning-nil" id="id68" name="id68">9.3&nbsp;&nbsp;&nbsp;Assigning nil</a></li>
 381 </ul>
 382 </li>
 383 <li><a class="reference" href="#defining-classes-in-lua" id="id69" name="id69">10&nbsp;&nbsp;&nbsp;Defining classes in Lua</a><ul class="auto-toc">
 384 <li><a class="reference" href="#deriving-in-lua" id="id70" name="id70">10.1&nbsp;&nbsp;&nbsp;Deriving in lua</a></li>
 385 <li><a class="reference" href="#overloading-operators" id="id71" name="id71">10.2&nbsp;&nbsp;&nbsp;Overloading operators</a></li>
 386 <li><a class="reference" href="#finalizers" id="id72" name="id72">10.3&nbsp;&nbsp;&nbsp;Finalizers</a></li>
 387 <li><a class="reference" href="#slicing" id="id73" name="id73">10.4&nbsp;&nbsp;&nbsp;Slicing</a></li>
 388 </ul>
 389 </li>
 390 <li><a class="reference" href="#exceptions" id="id74" name="id74">11&nbsp;&nbsp;&nbsp;Exceptions</a></li>
 391 <li><a class="reference" href="#policies" id="id75" name="id75">12&nbsp;&nbsp;&nbsp;Policies</a><ul class="auto-toc">
 392 <li><a class="reference" href="#adopt" id="id76" name="id76">12.1&nbsp;&nbsp;&nbsp;adopt</a></li>
 393 <li><a class="reference" href="#dependency" id="id77" name="id77">12.2&nbsp;&nbsp;&nbsp;dependency</a></li>
 394 <li><a class="reference" href="#out-value" id="id78" name="id78">12.3&nbsp;&nbsp;&nbsp;out_value</a></li>
 395 <li><a class="reference" href="#pure-out-value" id="id79" name="id79">12.4&nbsp;&nbsp;&nbsp;pure_out_value</a></li>
 396 <li><a class="reference" href="#return-reference-to" id="id80" name="id80">12.5&nbsp;&nbsp;&nbsp;return_reference_to</a></li>
 397 <li><a class="reference" href="#copy" id="id81" name="id81">12.6&nbsp;&nbsp;&nbsp;copy</a></li>
 398 <li><a class="reference" href="#discard-result" id="id82" name="id82">12.7&nbsp;&nbsp;&nbsp;discard_result</a></li>
 399 <li><a class="reference" href="#return-stl-iterator" id="id83" name="id83">12.8&nbsp;&nbsp;&nbsp;return_stl_iterator</a></li>
 400 <li><a class="reference" href="#raw" id="id84" name="id84">12.9&nbsp;&nbsp;&nbsp;raw</a></li>
 401 <li><a class="reference" href="#yield" id="id85" name="id85">12.10&nbsp;&nbsp;&nbsp;yield</a></li>
 402 </ul>
 403 </li>
 404 <li><a class="reference" href="#splitting-up-the-registration" id="id86" name="id86">13&nbsp;&nbsp;&nbsp;Splitting up the registration</a></li>
 405 <li><a class="reference" href="#error-handling" id="id87" name="id87">14&nbsp;&nbsp;&nbsp;Error Handling</a><ul class="auto-toc">
 406 <li><a class="reference" href="#pcall-errorfunc" id="id88" name="id88">14.1&nbsp;&nbsp;&nbsp;pcall errorfunc</a></li>
 407 <li><a class="reference" href="#file-and-line-numbers" id="id89" name="id89">14.2&nbsp;&nbsp;&nbsp;file and line numbers</a></li>
 408 <li><a class="reference" href="#lua-panic" id="id90" name="id90">14.3&nbsp;&nbsp;&nbsp;lua panic</a></li>
 409 <li><a class="reference" href="#structured-exceptions-msvc" id="id91" name="id91">14.4&nbsp;&nbsp;&nbsp;structured exceptions (MSVC)</a></li>
 410 <li><a class="reference" href="#error-messages" id="id92" name="id92">14.5&nbsp;&nbsp;&nbsp;Error messages</a></li>
 411 </ul>
 412 </li>
 413 <li><a class="reference" href="#build-options" id="id93" name="id93">15&nbsp;&nbsp;&nbsp;Build options</a></li>
 414 <li><a class="reference" href="#implementation-notes" id="id94" name="id94">16&nbsp;&nbsp;&nbsp;Implementation notes</a></li>
 415 <li><a class="reference" href="#faq" id="id95" name="id95">17&nbsp;&nbsp;&nbsp;FAQ</a></li>
 416 <li><a class="reference" href="#known-issues" id="id96" name="id96">18&nbsp;&nbsp;&nbsp;Known issues</a></li>
 417 <li><a class="reference" href="#acknowledgments" id="id97" name="id97">19&nbsp;&nbsp;&nbsp;Acknowledgments</a></li>
 418 </ul>
 419 </div>
 420 <div class="section">
 421 <h1><a id="introduction" name="introduction">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
 422 <p>Luabind is a library that helps you create bindings between C++ and Lua. It has
 423 the ability to expose functions and classes, written in C++, to Lua. It will
 424 also supply the functionality to define classes in Lua and let them derive from
 425 other Lua classes or C++ classes. Lua classes can override virtual functions
 426 from their C++ base classes. It is written towards Lua 5.0, and does not work
 427 with Lua 4.</p>
 428 <p>It is implemented utilizing template meta programming. That means that you
 429 don't need an extra preprocess pass to compile your project (it is done by the
 430 compiler). It also means you don't (usually) have to know the exact signature
 431 of each function you register, since the library will generate code depending
 432 on the compile-time type of the function (which includes the signature). The
 433 main drawback of this approach is that the compilation time will increase for
 434 the file that does the registration, it is therefore recommended that you
 435 register everything in the same cpp-file.</p>
 436 <p>Luabind is released under the terms of the <a class="reference" href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</p>
 437 <p>We are very interested in hearing about projects that use luabind, please let
 438 us know about your project.</p>
 439 <p>The main channel for help and feedback is the <a class="reference" href="https://lists.sourceforge.net/lists/listinfo/luabind-user">luabind mailing list</a>.
 440 There's also an IRC channel <tt class="docutils literal"><span class="pre">#luabind</span></tt> on irc.freenode.net.</p>
 441 </div>
 442 <div class="section">
 443 <h1><a id="features" name="features">2&nbsp;&nbsp;&nbsp;Features</a></h1>
 444 <p>Luabind supports:</p>
 445 <blockquote>
 446 <ul class="simple">
 447 <li>Overloaded free functions</li>
 448 <li>C++ classes in Lua</li>
 449 <li>Overloaded member functions</li>
 450 <li>Operators</li>
 451 <li>Properties</li>
 452 <li>Enums</li>
 453 <li>Lua functions in C++</li>
 454 <li>Lua classes in C++</li>
 455 <li>Lua classes (single inheritance)</li>
 456 <li>Derives from Lua or C++ classes</li>
 457 <li>Override virtual functions from C++ classes</li>
 458 <li>Implicit casts between registered types</li>
 459 <li>Best match signature matching</li>
 460 <li>Return value policies and parameter policies</li>
 461 </ul>
 462 </blockquote>
 463 </div>
 464 <div class="section">
 465 <h1><a id="portability" name="portability">3&nbsp;&nbsp;&nbsp;Portability</a></h1>
 466 <p>Luabind has been tested to work on the following compilers:</p>
 467 <blockquote>
 468 <ul class="simple">
 469 <li>Visual Studio 7.1</li>
 470 <li>Visual Studio 7.0</li>
 471 <li>Visual Studio 6.0 (sp 5)</li>
 472 <li>Intel C++ 6.0 (Windows)</li>
 473 <li>GCC 2.95.3 (cygwin)</li>
 474 <li>GCC 3.0.4 (Debian/Linux)</li>
 475 <li>GCC 3.1 (SunOS 5.8)</li>
 476 <li>GCC 3.2 (cygwin)</li>
 477 <li>GCC 3.3.1 (cygwin)</li>
 478 <li>GCC 3.3 (Apple, MacOS X)</li>
 479 <li>GCC 4.0 (Apple, MacOS X)</li>
 480 </ul>
 481 </blockquote>
 482 <p>It has been confirmed not to work with:</p>
 483 <blockquote>
 484 <ul class="simple">
 485 <li>GCC 2.95.2 (SunOS 5.8)</li>
 486 </ul>
 487 </blockquote>
 488 <p>Metrowerks 8.3 (Windows) compiles but fails the const-test. This
 489 means that const member functions are treated as non-const member
 490 functions.</p>
 491 <p>If you have tried luabind with a compiler not listed here, let us know
 492 your result with it.</p>
 493 </div>
 494 <div class="section">
 495 <h1><a id="building-luabind" name="building-luabind">4&nbsp;&nbsp;&nbsp;Building luabind</a></h1>
 496 <p>To keep down the compilation-time luabind is built as a library. This means you
 497 have to either build it and link against it, or include its source files in
 498 your project. You also have to make sure the luabind directory is somewhere in
 499 your compiler's include path. It requires <a class="reference" href="http://www.boost.org">Boost</a> 1.32.0 or 1.33.0 to be
 500 installed (only boost headers). It also requires that Lua is installed.</p>
 501 <p>The official way of building luabind is with <a class="reference" href="http://www.boost.org/tools/build/v2/index_v2.html">Boost.Build V2</a>. To properly build
 502 luabind with Boost.Build you need to set two environment variables:</p>
 503 <dl class="docutils">
 504 <dt>BOOST_ROOT</dt>
 505 <dd>Point this to your Boost installation.</dd>
 506 <dt>LUA_PATH</dt>
 507 <dd>Point this to your Lua directory. The build system will assume that the
 508 include and library files are located in <tt class="docutils literal"><span class="pre">$(LUA_PATH)/include/</span></tt> and
 509 <tt class="docutils literal"><span class="pre">$(LUA_PATH)/lib/.</span></tt>. If this environment variable is not defined, the
 510 Jamfile will try to invoke <tt class="docutils literal"><span class="pre">pkg-config</span></tt> in order to find lua. It will
 511 look for lua 5.1 (<tt class="docutils literal"><span class="pre">lua5.1</span></tt> as the package is called on debian systems).</dd>
 512 </dl>
 513 <p>For backward compatibility, there is also a makefile in the root-directory that
 514 will build the library and the test programs. If you are using a UNIX-system (or
 515 cygwin) they will make it easy to build luabind as a static library. If you are
 516 using Visual Studio it may be easier to include the files in the src directory
 517 in your project.</p>
 518 <p>When building luabind you have several options that may streamline the library
 519 to better suit your needs. It is extremely important that your application has
 520 the same settings as the library was built with. The available options are
 521 found in the <a class="reference" href="#build-options">Build options</a> section.</p>
 522 <p>If you want to change the settings to differ from the default, it's recommended
 523 that you define the settings on the command line of all your files (in the
 524 project settings in visual studio).</p>
 525 </div>
 526 <div class="section">
 527 <h1><a id="basic-usage" name="basic-usage">5&nbsp;&nbsp;&nbsp;Basic usage</a></h1>
 528 <p>To use luabind, you must include <tt class="docutils literal"><span class="pre">lua.h</span></tt> and luabind's main header file:</p>
 529 <pre class="literal-block">
 530 extern &quot;C&quot;
 531 {
 532     #include &quot;lua.h&quot;
 533 }
 534
 535 #include &lt;luabind/luabind.hpp&gt;
 536 </pre>
 537 <p>This includes support for both registering classes and functions. If you just
 538 want to have support for functions or classes you can include
 539 <tt class="docutils literal"><span class="pre">luabind/function.hpp</span></tt> and <tt class="docutils literal"><span class="pre">luabind/class.hpp</span></tt> separately:</p>
 540 <pre class="literal-block">
 541 #include &lt;luabind/function.hpp&gt;
 542 #include &lt;luabind/class.hpp&gt;
 543 </pre>
 544 <p>The first thing you need to do is to call <tt class="docutils literal"><span class="pre">luabind::open(lua_State*)</span></tt> which
 545 will register the functions to create classes from Lua, and initialize some
 546 state-global structures used by luabind. If you don't call this function you
 547 will hit asserts later in the library. There is no corresponding close function
 548 because once a class has been registered in Lua, there really isn't any good
 549 way to remove it. Partly because any remaining instances of that class relies
 550 on the class being there. Everything will be cleaned up when the state is
 551 closed though.</p>
 552 <!-- Isn't this wrong? Don't we include lua.h using lua_include.hpp ? -->
 553 <p>Luabind's headers will never include <tt class="docutils literal"><span class="pre">lua.h</span></tt> directly, but through
 554 <tt class="docutils literal"><span class="pre">&lt;luabind/lua_include.hpp&gt;</span></tt>. If you for some reason need to include another
 555 Lua header, you can modify this file.</p>
 556 <div class="section">
 557 <h2><a id="hello-world" name="hello-world">5.1&nbsp;&nbsp;&nbsp;Hello world</a></h2>
 558 <pre class="literal-block">
 559 #include &lt;iostream&gt;
 560 #include &lt;luabind/luabind.hpp&gt;
 561
 562 void greet()
 563 {
 564     std::cout &lt;&lt; &quot;hello world!\n&quot;;
 565 }
 566
 567 extern &quot;C&quot; int init(lua_State* L)
 568 {
 569     using namespace luabind;
 570
 571     open(L);
 572
 573     module(L)
 574     [
 575         def(&quot;greet&quot;, &amp;greet)
 576     ];
 577
 578     return 0;
 579 }
 580 </pre>
 581 <pre class="literal-block">
 582 Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
 583 &gt; loadlib('hello_world.dll', 'init')()
 584 &gt; greet()
 585 Hello world!
 586 &gt;
 587 </pre>
 588 </div>
 589 </div>
 590 <div class="section">
 591 <h1><a id="scopes" name="scopes">6&nbsp;&nbsp;&nbsp;Scopes</a></h1>
 592 <p>Everything that gets registered in Lua is registered in a namespace (Lua
 593 tables) or in the global scope (called module). All registrations must be
 594 surrounded by its scope. To define a module, the <tt class="docutils literal"><span class="pre">luabind::module</span></tt> class is
 595 used. It is used like this:</p>
 596 <pre class="literal-block">
 597 module(L)
 598 [
 599     // declarations
 600 ];
 601 </pre>
 602 <p>This will register all declared functions or classes in the global namespace in
 603 Lua. If you want to have a namespace for your module (like the standard
 604 libraries) you can give a name to the constructor, like this:</p>
 605 <pre class="literal-block">
 606 module(L, &quot;my_library&quot;)
 607 [
 608     // declarations
 609 ];
 610 </pre>
 611 <p>Here all declarations will be put in the my_library table.</p>
 612 <p>If you want nested namespace's you can use the <tt class="docutils literal"><span class="pre">luabind::namespace_</span></tt> class. It
 613 works exactly as <tt class="docutils literal"><span class="pre">luabind::module</span></tt> except that it doesn't take a lua_State*
 614 in it's constructor. An example of its usage could look like this:</p>
 615 <pre class="literal-block">
 616 module(L, &quot;my_library&quot;)
 617 [
 618     // declarations
 619
 620     namespace_(&quot;detail&quot;)
 621     [
 622         // library-private declarations
 623     ]
 624 ];
 625 </pre>
 626 <p>As you might have figured out, the following declarations are equivalent:</p>
 627 <pre class="literal-block">
 628 module(L)
 629 [
 630     namespace_(&quot;my_library&quot;)
 631     [
 632         // declarations
 633     ]
 634
 635 ];
 636 </pre>
 637 <pre class="literal-block">
 638 module(L, &quot;my_library&quot;)
 639 [
 640     // declarations
 641 ];
 642 </pre>
 643 <p>Each declaration must be separated by a comma, like this:</p>
 644 <pre class="literal-block">
 645 module(L)
 646 [
 647     def(&quot;f&quot;, &amp;f),
 648     def(&quot;g&quot;, &amp;g),
 649     class_&lt;A&gt;(&quot;A&quot;)
 650         .def(constructor&lt;int, int&gt;),
 651     def(&quot;h&quot;, &amp;h)
 652 ];
 653 </pre>
 654 <p>More about the actual declarations in the <a class="reference" href="#binding-functions-to-lua">Binding functions to Lua</a> and
 655 <a class="reference" href="#binding-classes-to-lua">Binding classes to Lua</a> sections.</p>
 656 <p>A word of caution, if you are in really bad need for performance, putting your
 657 functions in tables will increase the lookup time.</p>
 658 </div>
 659 <div class="section">
 660 <h1><a id="binding-functions-to-lua" name="binding-functions-to-lua">7&nbsp;&nbsp;&nbsp;Binding functions to Lua</a></h1>
 661 <p>To bind functions to Lua you use the function <tt class="docutils literal"><span class="pre">luabind::def()</span></tt>. It has the
 662 following synopsis:</p>
 663 <pre class="literal-block">
 664 template&lt;class F, class policies&gt;
 665 void def(const char* name, F f, const Policies&amp;);
 666 </pre>
 667 <ul class="simple">
 668 <li>name is the name the function will have within Lua.</li>
 669 <li>F is the function pointer you want to register.</li>
 670 <li>The Policies parameter is used to describe how parameters and return values
 671 are treated by the function, this is an optional parameter. More on this in
 672 the <a class="reference" href="#policies">policies</a> section.</li>
 673 </ul>
 674 <p>An example usage could be if you want to register the function <tt class="docutils literal"><span class="pre">float</span>
 675 <span class="pre">std::sin(float)</span></tt>:</p>
 676 <pre class="literal-block">
 677 module(L)
 678 [
 679     def(&quot;sin&quot;, &amp;std::sin)
 680 ];
 681 </pre>
 682 <div class="section">
 683 <h2><a id="overloaded-functions" name="overloaded-functions">7.1&nbsp;&nbsp;&nbsp;Overloaded functions</a></h2>
 684 <p>If you have more than one function with the same name, and want to register
 685 them in Lua, you have to explicitly give the signature. This is to let C++ know
 686 which function you refer to. For example, if you have two functions, <tt class="docutils literal"><span class="pre">int</span>
 687 <span class="pre">f(const</span> <span class="pre">char*)</span></tt> and <tt class="docutils literal"><span class="pre">void</span> <span class="pre">f(int)</span></tt>.</p>
 688 <pre class="literal-block">
 689 module(L)
 690 [
 691     def(&quot;f&quot;, (int(*)(const char*)) &amp;f),
 692     def(&quot;f&quot;, (void(*)(int)) &amp;f)
 693 ];
 694 </pre>
 695 </div>
 696 <div class="section">
 697 <h2><a id="signature-matching" name="signature-matching">7.2&nbsp;&nbsp;&nbsp;Signature matching</a></h2>
 698 <p>luabind will generate code that checks the Lua stack to see if the values there
 699 can match your functions' signatures. It will handle implicit typecasts between
 700 derived classes, and it will prefer matches with the least number of implicit
 701 casts. In a function call, if the function is overloaded and there's no
 702 overload that match the parameters better than the other, you have an
 703 ambiguity. This will spawn a run-time error, stating that the function call is
 704 ambiguous. A simple example of this is to register one function that takes an
 705 int and one that takes a float. Since Lua doesn't distinguish between floats and
 706 integers, both will always match.</p>
 707 <p>Since all overloads are tested, it will always find the best match (not the
 708 first match). This also means that it can handle situations where the only
 709 difference in the signature is that one member function is const and the other
 710 isn't.</p>
 711 <div class="sidebar">
 712 <p class="first sidebar-title">Ownership transfer</p>
 713 <p class="last">To correctly handle ownership transfer, create_a() would need an adopt
 714 return value policy. More on this in the <a class="reference" href="#policies">Policies</a> section.</p>
 715 </div>
 716 <p>For example, if the following function and class is registered:</p>
 717 <pre class="literal-block">
 718 struct A
 719 {
 720     void f();
 721     void f() const;
 722 };
 723
 724 const A* create_a();
 725
 726 struct B: A {};
 727 struct C: B {};
 728
 729 void g(A*);
 730 void g(B*);
 731 </pre>
 732 <p>And the following Lua code is executed:</p>
 733 <pre class="literal-block">
 734 a1 = create_a()
 735 a1:f() -- the const version is called
 736
 737 a2 = A()
 738 a2:f() -- the non-const version is called
 739
 740 a = A()
 741 b = B()
 742 c = C()
 743
 744 g(a) -- calls g(A*)
 745 g(b) -- calls g(B*)
 746 g(c) -- calls g(B*)
 747 </pre>
 748 </div>
 749 <div class="section">
 750 <h2><a id="calling-lua-functions" name="calling-lua-functions">7.3&nbsp;&nbsp;&nbsp;Calling Lua functions</a></h2>
 751 <p>To call a Lua function, you can either use <tt class="docutils literal"><span class="pre">call_function()</span></tt> or
 752 an <tt class="docutils literal"><span class="pre">object</span></tt>.</p>
 753 <pre class="literal-block">
 754 template&lt;class Ret&gt;
 755 Ret call_function(lua_State* L, const char* name, ...)
 756 template&lt;class Ret&gt;
 757 Ret call_function(object const&amp; obj, ...)
 758 </pre>
 759 <p>There are two overloads of the <tt class="docutils literal"><span class="pre">call_function</span></tt> function, one that calls
 760 a function given its name, and one that takes an object that should be a Lua
 761 value that can be called as a function.</p>
 762 <p>The overload that takes a name can only call global Lua functions. The ...
 763 represents a variable number of parameters that are sent to the Lua
 764 function. This function call may throw <tt class="docutils literal"><span class="pre">luabind::error</span></tt> if the function
 765 call fails.</p>
 766 <p>The return value isn't actually Ret (the template parameter), but a proxy
 767 object that will do the function call. This enables you to give policies to the
 768 call. You do this with the operator[]. You give the policies within the
 769 brackets, like this:</p>
 770 <pre class="literal-block">
 771 int ret = call_function&lt;int&gt;(
 772     L
 773   , &quot;a_lua_function&quot;
 774   , new complex_class()
 775 )[ adopt(_1) ];
 776 </pre>
 777 <p>If you want to pass a parameter as a reference, you have to wrap it with the
 778 <a class="reference" href="http://www.boost.org/doc/html/ref.html">Boost.Ref</a>.</p>
 779 <p>Like this:</p>
 780 <pre class="literal-block">
 781 int ret = call_function(L, &quot;fun&quot;, boost::ref(val));
 782 </pre>
 783 <p>If you want to use a custom error handler for the function call, see
 784 <tt class="docutils literal"><span class="pre">set_pcall_callback</span></tt> under <a class="reference" href="#pcall-errorfunc">pcall errorfunc</a>.</p>
 785 </div>
 786 <div class="section">
 787 <h2><a id="using-lua-threads" name="using-lua-threads">7.4&nbsp;&nbsp;&nbsp;Using Lua threads</a></h2>
 788 <p>To start a Lua thread, you have to call <tt class="docutils literal"><span class="pre">lua_resume()</span></tt>, this means that you
 789 cannot use the previous function <tt class="docutils literal"><span class="pre">call_function()</span></tt> to start a thread. You have
 790 to use</p>
 791 <pre class="literal-block">
 792 template&lt;class Ret&gt;
 793 Ret resume_function(lua_State* L, const char* name, ...)
 794 template&lt;class Ret&gt;
 795 Ret resume_function(object const&amp; obj, ...)
 796 </pre>
 797 <p>and</p>
 798 <pre class="literal-block">
 799 template&lt;class Ret&gt;
 800 Ret resume(lua_State* L, ...)
 801 </pre>
 802 <p>The first time you start the thread, you have to give it a function to execute. i.e. you
 803 have to use <tt class="docutils literal"><span class="pre">resume_function</span></tt>, when the Lua function yields, it will return the first
 804 value passed in to <tt class="docutils literal"><span class="pre">lua_yield()</span></tt>. When you want to continue the execution, you just call
 805 <tt class="docutils literal"><span class="pre">resume()</span></tt> on your <tt class="docutils literal"><span class="pre">lua_State</span></tt>, since it's already executing a function, you don't pass
 806 it one. The parameters to <tt class="docutils literal"><span class="pre">resume()</span></tt> will be returned by <tt class="docutils literal"><span class="pre">yield()</span></tt> on the Lua side.</p>
 807 <p>For yielding C++-functions (without the support of passing data back and forth between the
 808 Lua side and the c++ side), you can use the <a class="reference" href="#yield">yield</a> policy.</p>
 809 <p>With the overload of <tt class="docutils literal"><span class="pre">resume_function</span></tt> that takes an <a class="reference" href="#object">object</a>, it is important that the
 810 object was constructed with the thread as its <tt class="docutils literal"><span class="pre">lua_State*</span></tt>. Like this:</p>
 811 <pre class="literal-block">
 812 lua_State* thread = lua_newthread(L);
 813 object fun = get_global(<strong>thread</strong>)[&quot;my_thread_fun&quot;];
 814 resume_function(fun);
 815 </pre>
 816 </div>
 817 </div>
 818 <div class="section">
 819 <h1><a id="binding-classes-to-lua" name="binding-classes-to-lua">8&nbsp;&nbsp;&nbsp;Binding classes to Lua</a></h1>
 820 <p>To register classes you use a class called <tt class="docutils literal"><span class="pre">class_</span></tt>. Its name is supposed to
 821 resemble the C++ keyword, to make it look more intuitive. It has an overloaded
 822 member function <tt class="docutils literal"><span class="pre">def()</span></tt> that is used to register member functions, operators,
 823 constructors, enums and properties on the class. It will return its
 824 this-pointer, to let you register more members directly.</p>
 825 <p>Let's start with a simple example. Consider the following C++ class:</p>
 826 <pre class="literal-block">
 827 class testclass
 828 {
 829 public:
 830     testclass(const std::string&amp; s): m_string(s) {}
 831     void print_string() { std::cout &lt;&lt; m_string &lt;&lt; &quot;\n&quot;; }
 832
 833 private:
 834     std::string m_string;
 835 };
 836 </pre>
 837 <p>To register it with a Lua environment, write as follows (assuming you are using
 838 namespace luabind):</p>
 839 <pre class="literal-block">
 840 module(L)
 841 [
 842     class_&lt;testclass&gt;(&quot;testclass&quot;)
 843         .def(constructor&lt;const std::string&amp;&gt;())
 844         .def(&quot;print_string&quot;, &amp;testclass::print_string)
 845 ];
 846 </pre>
 847 <p>This will register the class with the name testclass and constructor that takes
 848 a string as argument and one member function with the name <tt class="docutils literal"><span class="pre">print_string</span></tt>.</p>
 849 <pre class="literal-block">
 850 Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
 851 &gt; a = testclass('a string')
 852 &gt; a:print_string()
 853 a string
 854 </pre>
 855 <p>It is also possible to register free functions as member functions. The
 856 requirement on the function is that it takes a pointer, const pointer,
 857 reference or const reference to the class type as the first parameter. The rest
 858 of the parameters are the ones that are visible in Lua, while the object
 859 pointer is given as the first parameter. If we have the following C++ code:</p>
 860 <pre class="literal-block">
 861 struct A
 862 {
 863     int a;
 864 };
 865
 866 int plus(A* o, int v) { return o-&gt;a + v; }
 867 </pre>
 868 <p>You can register <tt class="docutils literal"><span class="pre">plus()</span></tt> as if it was a member function of A like this:</p>
 869 <pre class="literal-block">
 870 class_&lt;A&gt;(&quot;A&quot;)
 871     .def(&quot;plus&quot;, &amp;plus)
 872 </pre>
 873 <p><tt class="docutils literal"><span class="pre">plus()</span></tt> can now be called as a member function on A with one parameter, int.
 874 If the object pointer parameter is const, the function will act as if it was a
 875 const member function (it can be called on const objects).</p>
 876 <div class="section">
 877 <h2><a id="overloaded-member-functions" name="overloaded-member-functions">8.1&nbsp;&nbsp;&nbsp;Overloaded member functions</a></h2>
 878 <p>When binding more than one overloads of a member function, or just binding
 879 one overload of an overloaded member function, you have to disambiguate
 880 the member function pointer you pass to <tt class="docutils literal"><span class="pre">def</span></tt>. To do this, you can use an
 881 ordinary C-style cast, to cast it to the right overload. To do this, you have
 882 to know how to express member function types in C++, here's a short tutorial
 883 (for more info, refer to your favourite book on C++).</p>
 884 <p>The syntax for member function pointer follows:</p>
 885 <pre class="literal-block">
 886 <em>return-value</em> (<em>class-name</em>::*)(<em>arg1-type</em>, <em>arg2-type</em>, <em>...</em>)
 887 </pre>
 888 <p>Here's an example illlustrating this:</p>
 889 <pre class="literal-block">
 890 struct A
 891 {
 892     void f(int);
 893     void f(int, int);
 894 };
 895 </pre>
 896 <pre class="literal-block">
 897 class_&lt;A&gt;()
 898     .def(&quot;f&quot;, (void(A::*)(int))&amp;A::f)
 899 </pre>
 900 <p>This selects the first overload of the function <tt class="docutils literal"><span class="pre">f</span></tt> to bind. The second
 901 overload is not bound.</p>
 902 </div>
 903 <div class="section">
 904 <h2><a id="properties" name="properties">8.2&nbsp;&nbsp;&nbsp;Properties</a></h2>
 905 <p>To register a global data member with a class is easily done. Consider the
 906 following class:</p>
 907 <pre class="literal-block">
 908 struct A
 909 {
 910     int a;
 911 };
 912 </pre>
 913 <p>This class is registered like this:</p>
 914 <pre class="literal-block">
 915 module(L)
 916 [
 917     class_&lt;A&gt;(&quot;A&quot;)
 918         .def_readwrite(&quot;a&quot;, &amp;A::a)
 919 ];
 920 </pre>
 921 <p>This gives read and write access to the member variable <tt class="docutils literal"><span class="pre">A::a</span></tt>. It is also
 922 possible to register attributes with read-only access:</p>
 923 <pre class="literal-block">
 924 module(L)
 925 [
 926     class_&lt;A&gt;(&quot;A&quot;)
 927         .def_readonly(&quot;a&quot;, &amp;A::a)
 928 ];
 929 </pre>
 930 <p>When binding members that are a non-primitive type, the auto generated getter
 931 function will return a reference to it. This is to allow chained .-operators.
 932 For example, when having a struct containing another struct. Like this:</p>
 933 <pre class="literal-block">
 934 struct A { int m; };
 935 struct B { A a; };
 936 </pre>
 937 <p>When binding <tt class="docutils literal"><span class="pre">B</span></tt> to lua, the following expression code should work:</p>
 938 <pre class="literal-block">
 939 b = B()
 940 b.a.m = 1
 941 assert(b.a.m == 1)
 942 </pre>
 943 <p>This requires the first lookup (on <tt class="docutils literal"><span class="pre">a</span></tt>) to return a reference to <tt class="docutils literal"><span class="pre">A</span></tt>, and
 944 not a copy. In that case, luabind will automatically use the dependency policy
 945 to make the return value dependent on the object in which it is stored. So, if
 946 the returned reference lives longer than all references to the object (b in
 947 this case) it will keep the object alive, to avoid being a dangling pointer.</p>
 948 <p>You can also register getter and setter functions and make them look as if they
 949 were a public data member. Consider the following class:</p>
 950 <pre class="literal-block">
 951 class A
 952 {
 953 public:
 954     void set_a(int x) { a = x; }
 955     int get_a() const { return a; }
 956
 957 private:
 958     int a;
 959 };
 960 </pre>
 961 <p>It can be registered as if it had a public data member a like this:</p>
 962 <pre class="literal-block">
 963 class_&lt;A&gt;(&quot;A&quot;)
 964     .property(&quot;a&quot;, &amp;A::get_a, &amp;A::set_a)
 965 </pre>
 966 <p>This way the <tt class="docutils literal"><span class="pre">get_a()</span></tt> and <tt class="docutils literal"><span class="pre">set_a()</span></tt> functions will be called instead of
 967 just writing  to the data member. If you want to make it read only you can just
 968 omit the last parameter. Please note that the get function <strong>has to be
 969 const</strong>, otherwise it won't compile. This seems to be a common source of errors.</p>
 970 </div>
 971 <div class="section">
 972 <h2><a id="enums" name="enums">8.3&nbsp;&nbsp;&nbsp;Enums</a></h2>
 973 <p>If your class contains enumerated constants (enums), you can register them as
 974 well to make them available in Lua. Note that they will not be type safe, all
 975 enums are integers in Lua, and all functions that takes an enum, will accept
 976 any integer. You register them like this:</p>
 977 <pre class="literal-block">
 978 module(L)
 979 [
 980     class_&lt;A&gt;(&quot;A&quot;)
 981         .enum_(&quot;constants&quot;)
 982         [
 983             value(&quot;my_enum&quot;, 4),
 984             value(&quot;my_2nd_enum&quot;, 7),
 985             value(&quot;another_enum&quot;, 6)
 986         ]
 987 ];
 988 </pre>
 989 <p>In Lua they are accessed like any data member, except that they are read-only
 990 and reached on the class itself rather than on an instance of the class.</p>
 991 <pre class="literal-block">
 992 Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
 993 &gt; print(A.my_enum)
 994 4
 995 &gt; print(A.another_enum)
 996 6
 997 </pre>
 998 </div>
 999 <div class="section">
1000 <h2><a id="operators" name="operators">8.4&nbsp;&nbsp;&nbsp;Operators</a></h2>
1001 <p>To bind operators you have to include <tt class="docutils literal"><span class="pre">&lt;luabind/operator.hpp&gt;</span></tt>.</p>
1002 <p>The mechanism for registering operators on your class is pretty simple. You use
1003 a global name <tt class="docutils literal"><span class="pre">luabind::self</span></tt> to refer to the class itself and then you just
1004 write the operator expression inside the <tt class="docutils literal"><span class="pre">def()</span></tt> call. This class:</p>
1005 <pre class="literal-block">
1006 struct vec
1007 {
1008     vec operator+(int s);
1009 };
1010 </pre>
1011 <p>Is registered like this:</p>
1012 <pre class="literal-block">
1013 module(L)
1014 [
1015     class_&lt;vec&gt;(&quot;vec&quot;)
1016         .def(<strong>self + int()</strong>)
1017 ];
1018 </pre>
1019 <p>This will work regardless if your plus operator is defined inside your class or
1020 as a free function.</p>
1021 <p>If your operator is const (or, when defined as a free function, takes a const
1022 reference to the class itself) you have to use <tt class="docutils literal"><span class="pre">const_self</span></tt> instead of
1023 <tt class="docutils literal"><span class="pre">self</span></tt>. Like this:</p>
1024 <pre class="literal-block">
1025 module(L)
1026 [
1027     class_&lt;vec&gt;(&quot;vec&quot;)
1028         .def(<strong>const_self</strong> + int())
1029 ];
1030 </pre>
1031 <p>The operators supported are those available in Lua:</p>
1032 <pre class="literal-block">
1033 +    -    *    /    ==    &lt;    &lt;=
1034 </pre>
1035 <p>This means, no in-place operators. The equality operator (<tt class="docutils literal"><span class="pre">==</span></tt>) has a little
1036 hitch; it will not be called if the references are equal. This means that the
1037 <tt class="docutils literal"><span class="pre">==</span></tt> operator has to do pretty much what's it's expected to do.</p>
1038 <p>Lua does not support operators such as <tt class="docutils literal"><span class="pre">!=</span></tt>, <tt class="docutils literal"><span class="pre">&gt;</span></tt> or <tt class="docutils literal"><span class="pre">&gt;=</span></tt>. That's why you
1039 can only register the operators listed above. When you invoke one of the
1040 mentioned operators, lua will define it in terms of one of the avaliable
1041 operators.</p>
1042 <p>In the above example the other operand type is instantiated by writing
1043 <tt class="docutils literal"><span class="pre">int()</span></tt>. If the operand type is a complex type that cannot easily be
1044 instantiated you can wrap the type in a class called <tt class="docutils literal"><span class="pre">other&lt;&gt;</span></tt>. For example:</p>
1045 <p>To register this class, we don't want to instantiate a string just to register
1046 the operator.</p>
1047 <pre class="literal-block">
1048 struct vec
1049 {
1050     vec operator+(std::string);
1051 };
1052 </pre>
1053 <p>Instead we use the <tt class="docutils literal"><span class="pre">other&lt;&gt;</span></tt> wrapper like this:</p>
1054 <pre class="literal-block">
1055 module(L)
1056 [
1057     class_&lt;vec&gt;(&quot;vec&quot;)
1058         .def(self + <strong>other&lt;std::string&gt;()</strong>)
1059 ];
1060 </pre>
1061 <p>To register an application (function call-) operator:</p>
1062 <pre class="literal-block">
1063 module(L)
1064 [
1065     class_&lt;vec&gt;(&quot;vec&quot;)
1066         .def( <strong>self(int())</strong> )
1067 ];
1068 </pre>
1069 <p>There's one special operator. In Lua it's called <tt class="docutils literal"><span class="pre">__tostring</span></tt>, it's not
1070 really an operator. It is used for converting objects to strings in a standard
1071 way in Lua. If you register this functionality, you will be able to use the lua
1072 standard function <tt class="docutils literal"><span class="pre">tostring()</span></tt> for converting your object to a string.</p>
1073 <p>To implement this operator in C++ you should supply an <tt class="docutils literal"><span class="pre">operator&lt;&lt;</span></tt> for
1074 std::ostream. Like this example:</p>
1075 <pre class="literal-block">
1076 class number {};
1077 std::ostream&amp; operator&lt;&lt;(std::ostream&amp;, number&amp;);
1078
1079 ...
1080
1081 module(L)
1082 [
1083     class_&lt;number&gt;(&quot;number&quot;)
1084         .def(<strong>tostring(self)</strong>)
1085 ];
1086 </pre>
1087 </div>
1088 <div class="section">
1089 <h2><a id="nested-scopes-and-static-functions" name="nested-scopes-and-static-functions">8.5&nbsp;&nbsp;&nbsp;Nested scopes and static functions</a></h2>
1090 <p>It is possible to add nested scopes to a class. This is useful when you need
1091 to wrap a nested class, or a static function.</p>
1092 <pre class="literal-block">
1093 class_&lt;foo&gt;(&quot;foo&quot;)
1094     .def(constructor&lt;&gt;())
1095     <strong>.scope
1096     [
1097         class_&lt;inner&gt;(&quot;nested&quot;),
1098         def(&quot;f&quot;, &amp;f)
1099     ]</strong>;
1100 </pre>
1101 <p>In this example, <tt class="docutils literal"><span class="pre">f</span></tt> will behave like a static member function of the class
1102 <tt class="docutils literal"><span class="pre">foo</span></tt>, and the class <tt class="docutils literal"><span class="pre">nested</span></tt> will behave like a nested class of <tt class="docutils literal"><span class="pre">foo</span></tt>.</p>
1103 <p>It's also possible to add namespace's to classes using the same syntax.</p>
1104 </div>
1105 <div class="section">
1106 <h2><a id="derived-classes" name="derived-classes">8.6&nbsp;&nbsp;&nbsp;Derived classes</a></h2>
1107 <p>If you want to register classes that derives from other classes, you can
1108 specify a template parameter <tt class="docutils literal"><span class="pre">bases&lt;&gt;</span></tt> to the <tt class="docutils literal"><span class="pre">class_</span></tt> instantiation. The
1109 following hierarchy:</p>
1110 <pre class="literal-block">
1111 struct A {};
1112 struct B : A {};
1113 </pre>
1114 <p>Would be registered like this:</p>
1115 <pre class="literal-block">
1116 module(L)
1117 [
1118     class_&lt;A&gt;(&quot;A&quot;),
1119     class_&lt;B, A&gt;(&quot;B&quot;)
1120 ];
1121 </pre>
1122 <p>If you have multiple inheritance you can specify more than one base. If B would
1123 also derive from a class C, it would be registered like this:</p>
1124 <pre class="literal-block">
1125 module(L)
1126 [
1127     class_&lt;B, bases&lt;A, C&gt; &gt;(&quot;B&quot;)
1128 ];
1129 </pre>
1130 <p>Note that you can omit <tt class="docutils literal"><span class="pre">bases&lt;&gt;</span></tt> when using single inheritance.</p>
1131 <div class="note">
1132 <p class="first admonition-title">Note</p>
1133 <p class="last">If you don't specify that classes derive from each other, luabind will not
1134 be able to implicitly cast pointers between the types.</p>
1135 </div>
1136 </div>
1137 <div class="section">
1138 <h2><a id="smart-pointers" name="smart-pointers">8.7&nbsp;&nbsp;&nbsp;Smart pointers</a></h2>
1139 <p>When you register a class you can tell luabind that all instances of that class
1140 should be held by some kind of smart pointer (boost::shared_ptr for instance).
1141 You do this by giving the holder type as an extra template parameter to
1142 the <tt class="docutils literal"><span class="pre">class_</span></tt> you are constructing, like this:</p>
1143 <pre class="literal-block">
1144 module(L)
1145 [
1146     class_&lt;A, boost::shared_ptr&lt;A&gt; &gt;(&quot;A&quot;)
1147 ];
1148 </pre>
1149 <p>You also have to supply two functions for your smart pointer. One that returns
1150 the type of const version of the smart pointer type (boost::shared_ptr&lt;const A&gt;
1151 in this case). And one function that extracts the raw pointer from the smart
1152 pointer. The first function is needed because luabind has to allow the
1153 non-const -&gt; conversion when passing values from Lua to C++. The second
1154 function is needed when Lua calls member functions on held types, the this
1155 pointer must be a raw pointer, it is also needed to allow the smart_pointer -&gt;
1156 raw_pointer conversion from Lua to C++. They look like this:</p>
1157 <pre class="literal-block">
1158 namespace luabind {
1159
1160     template&lt;class T&gt;
1161     T* get_pointer(boost::shared_ptr&lt;T&gt;&amp; p)
1162     {
1163         return p.get();
1164     }
1165
1166     template&lt;class A&gt;
1167     boost::shared_ptr&lt;const A&gt;*
1168     get_const_holder(boost::shared_ptr&lt;A&gt;*)
1169     {
1170         return 0;
1171     }
1172 }
1173 </pre>
1174 <p>The second function will only be used to get a compile time mapping
1175 of <tt class="docutils literal"><span class="pre">boost::shared_ptr&lt;A&gt;</span></tt> to its const version,
1176 <tt class="docutils literal"><span class="pre">boost::shared_ptr&lt;const</span> <span class="pre">A&gt;</span></tt>. It will never be called, so the
1177 return value doesn't matter (only the return type).</p>
1178 <p>The conversion that works are (given that B is a base class of A):</p>
1179 <div class="topic">
1180 <p class="topic-title first">From Lua to C++</p>
1181 <table border="1" class="docutils">
1182 <colgroup>
1183 <col width="51%" />
1184 <col width="49%" />
1185 </colgroup>
1186 <thead valign="bottom">
1187 <tr><th class="head">Source</th>
1188 <th class="head">Target</th>
1189 </tr>
1190 </thead>
1191 <tbody valign="top">
1192 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1193 <td><tt class="docutils literal"><span class="pre">A*</span></tt></td>
1194 </tr>
1195 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1196 <td><tt class="docutils literal"><span class="pre">B*</span></tt></td>
1197 </tr>
1198 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1199 <td><tt class="docutils literal"><span class="pre">A</span> <span class="pre">const*</span></tt></td>
1200 </tr>
1201 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1202 <td><tt class="docutils literal"><span class="pre">B</span> <span class="pre">const*</span></tt></td>
1203 </tr>
1204 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1205 <td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1206 </tr>
1207 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1208 <td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
1209 </tr>
1210 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
1211 <td><tt class="docutils literal"><span class="pre">A</span> <span class="pre">const*</span></tt></td>
1212 </tr>
1213 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
1214 <td><tt class="docutils literal"><span class="pre">B</span> <span class="pre">const*</span></tt></td>
1215 </tr>
1216 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
1217 <td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
1218 </tr>
1219 </tbody>
1220 </table>
1221 </div>
1222 <div class="topic">
1223 <p class="topic-title first">From C++ to Lua</p>
1224 <table border="1" class="docutils">
1225 <colgroup>
1226 <col width="56%" />
1227 <col width="44%" />
1228 </colgroup>
1229 <thead valign="bottom">
1230 <tr><th class="head">Source</th>
1231 <th class="head">Target</th>
1232 </tr>
1233 </thead>
1234 <tbody valign="top">
1235 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1236 <td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1237 </tr>
1238 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
1239 <td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
1240 </tr>
1241 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span> <span class="pre">const&amp;</span></tt></td>
1242 <td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
1243 </tr>
1244 <tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span> <span class="pre">const&amp;</span></tt></td>
1245 <td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
1246 </tr>
1247 </tbody>
1248 </table>
1249 </div>
1250 <p>When using a holder type, it can be useful to know if the pointer is valid
1251 (i.e. not null). For example when using std::auto_ptr, the holder will be
1252 invalidated when passed as a parameter to a function. For this purpose there
1253 is a member of all object instances in luabind: <tt class="docutils literal"><span class="pre">__ok</span></tt>.</p>
1254 <pre class="literal-block">
1255 struct X {};
1256 void f(std::auto_ptr&lt;X&gt;);
1257
1258 module(L)
1259 [
1260     class_&lt;X, std::auto_ptr&lt;X&gt; &gt;(&quot;X&quot;)
1261         .def(constructor&lt;&gt;()),
1262
1263     def(&quot;f&quot;, &amp;f)
1264 ];
1265 </pre>
1266 <pre class="literal-block">
1267 Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
1268 &gt; a = X()
1269 &gt; f(a)
1270 &gt; print a.__ok
1271 false
1272 </pre>
1273 <p>When registering a hierarchy of classes, where all instances are to be held
1274 by a smart pointer, all the classes should have the baseclass' holder type.
1275 Like this:</p>
1276 <pre class="literal-block">
1277 module(L)
1278 [
1279     class_&lt;base, boost::shared_ptr&lt;base&gt; &gt;(&quot;base&quot;)
1280         .def(constructor&lt;&gt;()),
1281     class_&lt;derived, base, <strong>boost::shared_ptr&lt;base&gt;</strong> &gt;(&quot;base&quot;)
1282         .def(constructor&lt;&gt;())
1283 ];
1284 </pre>
1285 <p>Internally, luabind will do the necessary conversions on the raw pointers, which
1286 are first extracted from the holder type.</p>
1287 </div>
1288 <div class="section">
1289 <h2><a id="splitting-class-registrations" name="splitting-class-registrations">8.8&nbsp;&nbsp;&nbsp;Splitting class registrations</a></h2>
1290 <p>In some situations it may be desirable to split a registration of a class
1291 across different compilation units. Partly to save rebuild time when changing
1292 in one part of the binding, and in some cases compiler limits may force you
1293 to split it. To do this is very simple. Consider the following sample code:</p>
1294 <pre class="literal-block">
1295 void register_part1(class_&lt;X&gt;&amp; x)
1296 {
1297     x.def(/*...*/);
1298 }
1299
1300 void register_part2(class_&lt;X&gt;&amp; x)
1301 {
1302     x.def(/*...*/);
1303 }
1304
1305 void register_(lua_State* L)
1306 {
1307     class_&lt;X&gt; x(&quot;x&quot;);
1308
1309     register_part1(x);
1310     register_part2(x);
1311
1312     module(L) [ x ];
1313 }
1314 </pre>
1315 <p>Here, the class <tt class="docutils literal"><span class="pre">X</span></tt> is registered in two steps. The two functions
1316 <tt class="docutils literal"><span class="pre">register_part1</span></tt> and <tt class="docutils literal"><span class="pre">register_part2</span></tt> may be put in separate compilation
1317 units.</p>
1318 <p>To separate the module registration and the classes to be registered, see
1319 <a class="reference" href="#splitting-up-the-registration">Splitting up the registration</a>.</p>
1320 </div>
1321 </div>
1322 <div class="section">
1323 <h1><a id="object" name="object">9&nbsp;&nbsp;&nbsp;Object</a></h1>
1324 <p>Since functions have to be able to take Lua values (of variable type) we need a
1325 wrapper around them. This wrapper is called <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. If the
1326 function you register takes an object, it will match any Lua value. To use it,
1327 you need to include <tt class="docutils literal"><span class="pre">&lt;luabind/object.hpp&gt;</span></tt>.</p>
1328 <div class="topic">
1329 <p class="topic-title first">Synopsis</p>
1330 <pre class="literal-block">
1331 class object
1332 {
1333 public:
1334     template&lt;class T&gt;
1335     object(lua_State*, T const&amp; value);
1336     object(from_stack const&amp;);
1337     object(object const&amp;);
1338     object();
1339
1340     ~object();
1341
1342     lua_State* interpreter() const;
1343     void push() const;
1344     bool is_valid() const;
1345     operator <em>safe_bool_type</em> () const;
1346
1347     template&lt;class Key&gt;
1348     <em>implementation-defined</em> operator[](Key const&amp;);
1349
1350     template&lt;class T&gt;
1351     object&amp; operator=(T const&amp;);
1352     object&amp; operator=(object const&amp;);
1353
1354     bool operator==(object const&amp;) const;
1355     bool operator&lt;(object const&amp;) const;
1356     bool operator&lt;=(object const&amp;) const;
1357     bool operator&gt;(object const&amp;) const;
1358     bool operator&gt;=(object const&amp;) const;
1359     bool operator!=(object const&amp;) const;
1360
1361     template &lt;class T&gt;
1362     <em>implementation-defined</em> operator[](T const&amp; key) const
1363
1364     void swap(object&amp;);
1365
1366     <em>implementation-defined</em> operator()();
1367
1368     template&lt;class A0&gt;
1369     <em>implementation-defined</em> operator()(A0 const&amp; a0);
1370
1371     template&lt;class A0, class A1&gt;
1372     <em>implementation-defined</em> operator()(A0 const&amp; a0, A1 const&amp; a1);
1373
1374     /* ... */
1375 };
1376 </pre>
1377 </div>
1378 <p>When you have a Lua object, you can assign it a new value with the assignment
1379 operator (=). When you do this, the <tt class="docutils literal"><span class="pre">default_policy</span></tt> will be used to make the
1380 conversion from C++ value to Lua. If your <tt class="docutils literal"><span class="pre">luabind::object</span></tt> is a table you
1381 can access its members through the operator[] or the <a class="reference" href="#iterators">Iterators</a>. The value
1382 returned from the operator[] is a proxy object that can be used both for
1383 reading and writing values into the table (using operator=).</p>
1384 <p>Note that it is impossible to know if a Lua value is indexable or not
1385 (<tt class="docutils literal"><span class="pre">lua_gettable</span></tt> doesn't fail, it succeeds or crashes). This means that if
1386 you're trying to index something that cannot be indexed, you're on your own.
1387 Lua will call its <tt class="docutils literal"><span class="pre">panic()</span></tt> function. See <a class="reference" href="#lua-panic">lua panic</a>.</p>
1388 <p>There are also free functions that can be used for indexing the table, see
1389 <a class="reference" href="#related-functions">Related functions</a>.</p>
1390 <p>The constructor that takes a <tt class="docutils literal"><span class="pre">from_stack</span></tt> object is used when you want to
1391 initialize the object with a value from the lua stack. The <tt class="docutils literal"><span class="pre">from_stack</span></tt>
1392 type has the following constructor:</p>
1393 <pre class="literal-block">
1394 from_stack(lua_State* L, int index);
1395 </pre>
1396 <p>The index is an ordinary lua stack index, negative values are indexed from the
1397 top of the stack. You use it like this:</p>
1398 <pre class="literal-block">
1399 object o(from_stack(L, -1));
1400 </pre>
1401 <p>This will create the object <tt class="docutils literal"><span class="pre">o</span></tt> and copy the value from the top of the lua stack.</p>
1402 <p>The <tt class="docutils literal"><span class="pre">interpreter()</span></tt> function returns the Lua state where this object is stored.
1403 If you want to manipulate the object with Lua functions directly you can push
1404 it onto the Lua stack by calling <tt class="docutils literal"><span class="pre">push()</span></tt>.</p>
1405 <p>The operator== will call lua_equal() on the operands and return its result.</p>
1406 <p>The <tt class="docutils literal"><span class="pre">is_valid()</span></tt> function tells you whether the object has been initialized
1407 or not. When created with its default constructor, objects are invalid. To make
1408 an object valid, you can assign it a value. If you want to invalidate an object
1409 you can simply assign it an invalid object.</p>
1410 <p>The <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">safe_bool_type()</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">is_valid()</span></tt>. This means
1411 that these snippets are equivalent:</p>
1412 <pre class="literal-block">
1413 object o;
1414 // ...
1415 if (o)
1416 {
1417     // ...
1418 }
1419
1420 ...
1421
1422 object o;
1423 // ...
1424 if (o.is_valid())
1425 {
1426     // ...
1427 }
1428 </pre>
1429 <p>The application operator will call the value as if it was a function. You can
1430 give it any number of parameters (currently the <tt class="docutils literal"><span class="pre">default_policy</span></tt> will be used
1431 for the conversion). The returned object refers to the return value (currently
1432 only one return value is supported). This operator may throw <tt class="docutils literal"><span class="pre">luabind::error</span></tt>
1433 if the function call fails. If you want to specify policies to your function
1434 call, you can use index-operator (operator[]) on the function call, and give
1435 the policies within the [ and ]. Like this:</p>
1436 <pre class="literal-block">
1437 my_function_object(
1438     2
1439   , 8
1440   , new my_complex_structure(6)
1441 ) [ adopt(_3) ];
1442 </pre>
1443 <p>This tells luabind to make Lua adopt the ownership and responsibility for the
1444 pointer passed in to the lua-function.</p>
1445 <p>It's important that all instances of object have been destructed by the time
1446 the Lua state is closed. The object will keep a pointer to the lua state and
1447 release its Lua object in its destructor.</p>
1448 <p>Here's an example of how a function can use a table:</p>
1449 <pre class="literal-block">
1450 void my_function(object const&amp; table)
1451 {
1452     if (type(table) == LUA_TTABLE)
1453     {
1454         table[&quot;time&quot;] = std::clock();
1455         table[&quot;name&quot;] = std::rand() &lt; 500 ? &quot;unusual&quot; : &quot;usual&quot;;
1456
1457         std::cout &lt;&lt; object_cast&lt;std::string&gt;(table[5]) &lt;&lt; &quot;\n&quot;;
1458     }
1459 }
1460 </pre>
1461 <p>If you take a <tt class="docutils literal"><span class="pre">luabind::object</span></tt> as a parameter to a function, any Lua value
1462 will match that parameter. That's why we have to make sure it's a table before
1463 we index into it.</p>
1464 <pre class="literal-block">
1465 std::ostream&amp; operator&lt;&lt;(std::ostream&amp;, object const&amp;);
1466 </pre>
1467 <p>There's a stream operator that makes it possible to print objects or use
1468 <tt class="docutils literal"><span class="pre">boost::lexical_cast</span></tt> to convert it to a string. This will use lua's string
1469 conversion function. So if you convert a C++ object with a <tt class="docutils literal"><span class="pre">tostring</span></tt>
1470 operator, the stream operator for that type will be used.</p>
1471 <div class="section">
1472 <h2><a id="iterators" name="iterators">9.1&nbsp;&nbsp;&nbsp;Iterators</a></h2>
1473 <p>There are two kinds of iterators. The normal iterator that will use the metamethod
1474 of the object (if there is any) when the value is retrieved. This iterator is simply
1475 called <tt class="docutils literal"><span class="pre">luabind::iterator</span></tt>. The other iterator is called <tt class="docutils literal"><span class="pre">luabind::raw_iterator</span></tt>
1476 and will bypass the metamethod and give the true contents of the table. They have
1477 identical interfaces, which implements the <a class="reference" href="http://www.sgi.com/tech/stl/ForwardIterator.html">ForwardIterator</a> concept. Apart from
1478 the members of standard iterators, they have the following members and constructors:</p>
1479 <pre class="literal-block">
1480 class iterator
1481 {
1482     iterator();
1483     iterator(object const&amp;);
1484
1485     object key() const;
1486
1487     <em>standard iterator members</em>
1488 };
1489 </pre>
1490 <p>The constructor that takes a <tt class="docutils literal"><span class="pre">luabind::object</span></tt> is actually a template that can be
1491 used with object. Passing an object as the parameter to the iterator will
1492 construct the iterator to refer to the first element in the object.</p>
1493 <p>The default constructor will initialize the iterator to the one-past-end
1494 iterator. This is used to test for the end of the sequence.</p>
1495 <p>The value type of the iterator is an implementation defined proxy type which
1496 supports the same operations as <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. Which means that in most
1497 cases you can just treat it as an ordinary object. The difference is that any
1498 assignments to this proxy will result in the value being inserted at the
1499 iterators position, in the table.</p>
1500 <p>The <tt class="docutils literal"><span class="pre">key()</span></tt> member returns the key used by the iterator when indexing the
1501 associated Lua table.</p>
1502 <p>An example using iterators:</p>
1503 <pre class="literal-block">
1504 for (iterator i(globals(L)[&quot;a&quot;]), end; i != end; ++i)
1505 {
1506   *i = 1;
1507 }
1508 </pre>
1509 <p>The iterator named <tt class="docutils literal"><span class="pre">end</span></tt> will be constructed using the default constructor
1510 and hence refer to the end of the sequence. This example will simply iterate
1511 over the entries in the global table <tt class="docutils literal"><span class="pre">a</span></tt> and set all its values to 1.</p>
1512 </div>
1513 <div class="section">
1514 <h2><a id="related-functions" name="related-functions">9.2&nbsp;&nbsp;&nbsp;Related functions</a></h2>
1515 <p>There are a couple of functions related to objects and tables.</p>
1516 <pre class="literal-block">
1517 int type(object const&amp;);
1518 </pre>
1519 <p>This function will return the lua type index of the given object.
1520 i.e. <tt class="docutils literal"><span class="pre">LUA_TNIL</span></tt>, <tt class="docutils literal"><span class="pre">LUA_TNUMBER</span></tt> etc.</p>
1521 <pre class="literal-block">
1522 template&lt;class T, class K&gt;
1523 void settable(object const&amp; o, K const&amp; key, T const&amp; value);
1524 template&lt;class K&gt;
1525 object gettable(object const&amp; o, K const&amp; key);
1526 template&lt;class T, class K&gt;
1527 void rawset(object const&amp; o, K const&amp; key, T const&amp; value);
1528 template&lt;class K&gt;
1529 object rawget(object const&amp; o, K const&amp; key);
1530 </pre>
1531 <p>These functions are used for indexing into tables. <tt class="docutils literal"><span class="pre">settable</span></tt> and <tt class="docutils literal"><span class="pre">gettable</span></tt>
1532 translates into calls to <tt class="docutils literal"><span class="pre">lua_settable</span></tt> and <tt class="docutils literal"><span class="pre">lua_gettable</span></tt> respectively. Which
1533 means that you could just as well use the index operator of the object.</p>
1534 <p><tt class="docutils literal"><span class="pre">rawset</span></tt> and <tt class="docutils literal"><span class="pre">rawget</span></tt> will translate into calls to <tt class="docutils literal"><span class="pre">lua_rawset</span></tt> and
1535 <tt class="docutils literal"><span class="pre">lua_rawget</span></tt> respectively. So they will bypass any metamethod and give you the
1536 true value of the table entry.</p>
1537 <pre class="literal-block">
1538 template&lt;class T&gt;
1539 T object_cast&lt;T&gt;(object const&amp;);
1540 template&lt;class T, class Policies&gt;
1541 T object_cast&lt;T&gt;(object const&amp;, Policies);
1542
1543 template&lt;class T&gt;
1544 boost::optional&lt;T&gt; object_cast_nothrow&lt;T&gt;(object const&amp;);
1545 template&lt;class T, class Policies&gt;
1546 boost::optional&lt;T&gt; object_cast_nothrow&lt;T&gt;(object const&amp;, Policies);
1547 </pre>
1548 <p>The <tt class="docutils literal"><span class="pre">object_cast</span></tt> function casts the value of an object to a C++ value.
1549 You can supply a policy to handle the conversion from lua to C++. If the cast
1550 cannot be made a <tt class="docutils literal"><span class="pre">cast_failed</span></tt> exception will be thrown. If you have
1551 defined LUABIND_NO_ERROR_CHECKING (see <a class="reference" href="#build-options">Build options</a>) no checking will occur,
1552 and if the cast is invalid the application may very well crash. The nothrow
1553 versions will return an uninitialized <tt class="docutils literal"><span class="pre">boost::optional&lt;T&gt;</span></tt> object, to
1554 indicate that the cast could not be performed.</p>
1555 <p>The function signatures of all of the above functions are really templates
1556 for the object parameter, but the intention is that you should only pass
1557 objects in there, that's why it's left out of the documentation.</p>
1558 <pre class="literal-block">
1559 object globals(lua_State*);
1560 object registry(lua_State*);
1561 </pre>
1562 <p>These functions return the global environment table and the registry table respectively.</p>
1563 <pre class="literal-block">
1564 object newtable(lua_State*);
1565 </pre>
1566 <p>This function creates a new table and returns it as an object.</p>
1567 </div>
1568 <div class="section">
1569 <h2><a id="assigning-nil" name="assigning-nil">9.3&nbsp;&nbsp;&nbsp;Assigning nil</a></h2>
1570 <p>To set a table entry to <tt class="docutils literal"><span class="pre">nil</span></tt>, you can use <tt class="docutils literal"><span class="pre">luabind::nil</span></tt>. It will avoid
1571 having to take the detour by first assigning <tt class="docutils literal"><span class="pre">nil</span></tt> to an object and then
1572 assign that to the table entry. It will simply result in a <tt class="docutils literal"><span class="pre">lua_pushnil()</span></tt>
1573 call, instead of copying an object.</p>
1574 <p>Example:</p>
1575 <pre class="literal-block">
1576 using luabind;
1577 object table = newtable(L);
1578 table[&quot;foo&quot;] = &quot;bar&quot;;
1579
1580 // now, clear the &quot;foo&quot;-field
1581 table[&quot;foo&quot;] = nil;
1582 </pre>
1583 </div>
1584 </div>
1585 <div class="section">
1586 <h1><a id="defining-classes-in-lua" name="defining-classes-in-lua">10&nbsp;&nbsp;&nbsp;Defining classes in Lua</a></h1>
1587 <p>In addition to binding C++ functions and classes with Lua, luabind also provide
1588 an OO-system in Lua.</p>
1589 <pre class="literal-block">
1590 class 'lua_testclass'
1591
1592 function lua_testclass:__init(name)
1593     self.name = name
1594 end
1595
1596 function lua_testclass:print()
1597     print(self.name)
1598 end
1599
1600 a = lua_testclass('example')
1601 a:print()
1602 </pre>
1603 <p>Inheritance can be used between lua-classes:</p>
1604 <pre class="literal-block">
1605 class 'derived' (lua_testclass)
1606
1607 function derived:__init() super('derived name')
1608 end
1609
1610 function derived:print()
1611     print('Derived:print() -&gt; ')
1612     lua_testclass.print(self)
1613 end
1614 </pre>
1615 <p>Here the <tt class="docutils literal"><span class="pre">super</span></tt> keyword is used in the constructor to initialize the base
1616 class. The user is required to call <tt class="docutils literal"><span class="pre">super</span></tt> first in the constructor.</p>
1617 <p>As you can see in this example, you can call the base class member functions.
1618 You can find all member functions in the base class, but you will have to give
1619 the this-pointer (<tt class="docutils literal"><span class="pre">self</span></tt>) as first argument.</p>
1620 <div class="section">
1621 <h2><a id="deriving-in-lua" name="deriving-in-lua">10.1&nbsp;&nbsp;&nbsp;Deriving in lua</a></h2>
1622 <p>It is also possible to derive Lua classes from C++ classes, and override
1623 virtual functions with Lua functions. To do this we have to create a wrapper
1624 class for our C++ base class. This is the class that will hold the Lua object
1625 when we instantiate a Lua class.</p>
1626 <pre class="literal-block">
1627 class base
1628 {
1629 public:
1630     base(const char* s)
1631     { std::cout &lt;&lt; s &lt;&lt; &quot;\n&quot;; }
1632
1633     virtual void f(int a)
1634     { std::cout &lt;&lt; &quot;f(&quot; &lt;&lt; a &lt;&lt; &quot;)\n&quot;; }
1635 };
1636
1637 struct base_wrapper : base, luabind::wrap_base
1638 {
1639     base_wrapper(const char* s)
1640         : base(s)
1641     {}
1642
1643     virtual void f(int a)
1644     {
1645         call&lt;void&gt;(&quot;f&quot;, a);
1646     }
1647
1648     static void default_f(base* ptr, int a)
1649     {
1650         return ptr-&gt;base::f(a);
1651     }
1652 };
1653
1654 ...
1655
1656 module(L)
1657 [
1658     class_&lt;base, base_wrapper&gt;(&quot;base&quot;)
1659         .def(constructor&lt;const char*&gt;())
1660         .def(&quot;f&quot;, &amp;base::f, &amp;base_wrapper::default_f)
1661 ];
1662 </pre>
1663 <div class="important">
1664 <p class="first admonition-title">Important</p>
1665 <p class="last">Since MSVC6.5 doesn't support explicit template parameters
1666 to member functions, instead of using the member function <tt class="docutils literal"><span class="pre">call()</span></tt>
1667 you call a free function <tt class="docutils literal"><span class="pre">call_member()</span></tt> and pass the this-pointer
1668 as first parameter.</p>
1669 </div>
1670 <p>Note that if you have both base classes and a base class wrapper, you must give
1671 both bases and the base class wrapper type as template parameter to
1672 <tt class="docutils literal"><span class="pre">class_</span></tt> (as done in the example above). The order in which you specify
1673 them is not important. You must also register both the static version and the
1674 virtual version of the function from the wrapper, this is necessary in order
1675 to allow luabind to use both dynamic and static dispatch when calling the function.</p>
1676 <div class="important">
1677 <p class="first admonition-title">Important</p>
1678 <p class="last">It is extremely important that the signatures of the static (default) function
1679 is identical to the virtual function. The fact that one of them is a free
1680 function and the other a member function doesn't matter, but the parameters
1681 as seen from lua must match. It would not have worked if the static function
1682 took a <tt class="docutils literal"><span class="pre">base_wrapper*</span></tt> as its first argument, since the virtual function
1683 takes a <tt class="docutils literal"><span class="pre">base*</span></tt> as its first argument (its this pointer). There's currently
1684 no check in luabind to make sure the signatures match.</p>
1685 </div>
1686 <p>If we didn't have a class wrapper, it would not be possible to pass a Lua class
1687 back to C++. Since the entry points of the virtual functions would still point
1688 to the C++ base class, and not to the functions defined in Lua. That's why we
1689 need one function that calls the base class' real function (used if the lua
1690 class doesn't redefine it) and one virtual function that dispatches the call
1691 into luabind, to allow it to select if a Lua function should be called, or if
1692 the original function should be called. If you don't intend to derive from a
1693 C++ class, or if it doesn't have any virtual member functions, you can register
1694 it without a class wrapper.</p>
1695 <p>You don't need to have a class wrapper in order to derive from a class, but if
1696 it has virtual functions you may have silent errors.</p>
1697 <!-- Unnecessary? The rule of thumb is:
1698 If your class has virtual functions, create a wrapper type, if it doesn't
1699 don't create a wrapper type. -->
1700 <p>The wrappers must derive from <tt class="docutils literal"><span class="pre">luabind::wrap_base</span></tt>, it contains a Lua reference
1701 that will hold the Lua instance of the object to make it possible to dispatch
1702 virtual function calls into Lua. This is done through an overloaded member function:</p>
1703 <pre class="literal-block">
1704 template&lt;class Ret&gt;
1705 Ret call(char const* name, ...)
1706 </pre>
1707 <p>Its used in a similar way as <tt class="docutils literal"><span class="pre">call_function</span></tt>, with the exception that it doesn't
1708 take a <tt class="docutils literal"><span class="pre">lua_State</span></tt> pointer, and the name is a member function in the Lua class.</p>
1709 <div class="warning">
1710 <p class="first admonition-title">Warning</p>
1711 <p class="last">The current implementation of <tt class="docutils literal"><span class="pre">call_member</span></tt> is not able to distinguish const
1712 member functions from non-const. If you have a situation where you have an overloaded
1713 virtual function where the only difference in their signatures is their constness, the
1714 wrong overload will be called by <tt class="docutils literal"><span class="pre">call_member</span></tt>. This is rarely the case though.</p>
1715 </div>
1716 <div class="section">
1717 <h3><a id="object-identity" name="object-identity">10.1.1&nbsp;&nbsp;&nbsp;Object identity</a></h3>
1718 <p>When a pointer or reference to a registered class with a wrapper is passed
1719 to Lua, luabind will query for it's dynamic type. If the dynamic type
1720 inherits from <tt class="docutils literal"><span class="pre">wrap_base</span></tt>, object identity is preserved.</p>
1721 <pre class="literal-block">
1722 struct A { .. };
1723 struct A_wrap : A, wrap_base { .. };
1724
1725 A* f(A* ptr) { return ptr; }
1726
1727 module(L)
1728 [
1729     class_&lt;A, A_wrap&gt;(&quot;A&quot;),
1730     def(&quot;f&quot;, &amp;f)
1731 ];
1732 </pre>
1733 <pre class="literal-block">
1734 &gt; class 'B' (A)
1735 &gt; x = B()
1736 &gt; assert(x == f(x)) -- object identity is preserved when object is
1737                     -- passed through C++
1738 </pre>
1739 <p>This functionality relies on RTTI being enabled (that <tt class="docutils literal"><span class="pre">LUABIND_NO_RTTI</span></tt> is
1740 not defined).</p>
1741 </div>
1742 </div>
1743 <div class="section">
1744 <h2><a id="overloading-operators" name="overloading-operators">10.2&nbsp;&nbsp;&nbsp;Overloading operators</a></h2>
1745 <p>You can overload most operators in Lua for your classes. You do this by simply
1746 declaring a member function with the same name as an operator (the name of the
1747 metamethods in Lua). The operators you can overload are:</p>
1748 <blockquote>
1749 <ul class="simple">
1750 <li><tt class="docutils literal"><span class="pre">__add</span></tt></li>
1751 <li><tt class="docutils literal"><span class="pre">__sub</span></tt></li>
1752 <li><tt class="docutils literal"><span class="pre">__mul</span></tt></li>
1753 <li><tt class="docutils literal"><span class="pre">__div</span></tt></li>
1754 <li><tt class="docutils literal"><span class="pre">__pow</span></tt></li>
1755 <li><tt class="docutils literal"><span class="pre">__lt</span></tt></li>
1756 <li><tt class="docutils literal"><span class="pre">__le</span></tt></li>
1757 <li><tt class="docutils literal"><span class="pre">__eq</span></tt></li>
1758 <li><tt class="docutils literal"><span class="pre">__call</span></tt></li>
1759 <li><tt class="docutils literal"><span class="pre">__unm</span></tt></li>
1760 <li><tt class="docutils literal"><span class="pre">__tostring</span></tt></li>
1761 </ul>
1762 </blockquote>
1763 <p><tt class="docutils literal"><span class="pre">__tostring</span></tt> isn't really an operator, but it's the metamethod that is called
1764 by the standard library's <tt class="docutils literal"><span class="pre">tostring()</span></tt> function. There's one strange behavior
1765 regarding binary operators. You are not guaranteed that the self pointer you
1766 get actually refers to an instance of your class. This is because Lua doesn't
1767 distinguish the two cases where you get the other operand as left hand value or
1768 right hand value. Consider the following examples:</p>
1769 <pre class="literal-block">
1770 class 'my_class'
1771
1772   function my_class:__init(v)
1773       self.val = v
1774   end
1775
1776   function my_class:__sub(v)
1777       return my_class(self.val - v.val)
1778   end
1779
1780   function my_class:__tostring()
1781       return self.val
1782   end
1783 </pre>
1784 <p>This will work well as long as you only subtracts instances of my_class with
1785 each other. But If you want to be able to subtract ordinary numbers from your
1786 class too, you have to manually check the type of both operands, including the
1787 self object.</p>
1788 <pre class="literal-block">
1789 function my_class:__sub(v)
1790     if (type(self) == 'number') then
1791         return my_class(self - v.val)
1792
1793     elseif (type(v) == 'number') then
1794         return my_class(self.val - v)
1795
1796     else
1797         -- assume both operands are instances of my_class
1798         return my_class(self.val - v.val)
1799
1800     end
1801 end
1802 </pre>
1803 <p>The reason why <tt class="docutils literal"><span class="pre">__sub</span></tt> is used as an example is because subtraction is not
1804 commutative (the order of the operands matter). That's why luabind cannot
1805 change order of the operands to make the self reference always refer to the
1806 actual class instance.</p>
1807 <p>If you have two different Lua classes with an overloaded operator, the operator
1808 of the right hand side type will be called. If the other operand is a C++ class
1809 with the same operator overloaded, it will be prioritized over the Lua class'
1810 operator. If none of the C++ overloads matches, the Lua class operator will be
1811 called.</p>
1812 </div>
1813 <div class="section">
1814 <h2><a id="finalizers" name="finalizers">10.3&nbsp;&nbsp;&nbsp;Finalizers</a></h2>
1815 <p>If an object needs to perform actions when it's collected we provide a
1816 <tt class="docutils literal"><span class="pre">__finalize</span></tt> function that can be overridden in lua-classes. The
1817 <tt class="docutils literal"><span class="pre">__finalize</span></tt> functions will be called on all classes in the inheritance
1818 chain, starting with the most derived type.</p>
1819 <pre class="literal-block">
1820 ...
1821
1822 function lua_testclass:__finalize()
1823     -- called when the an object is collected
1824 end
1825 </pre>
1826 </div>
1827 <div class="section">
1828 <h2><a id="slicing" name="slicing">10.4&nbsp;&nbsp;&nbsp;Slicing</a></h2>
1829 <p>If your lua C++ classes don't have wrappers (see <a class="reference" href="#deriving-in-lua">Deriving in lua</a>) and
1830 you derive from them in lua, they may be sliced. Meaning, if an object
1831 is passed into C++ as a pointer to its base class, the lua part will be
1832 separated from the C++ base part. This means that if you call virtual
1833 functions on that C++ object, they will not be dispatched to the lua
1834 class. It also means that if you adopt the object, the lua part will be
1835 garbage collected.</p>
1836 <pre class="literal-block">
1837 +--------------------+
1838 | C++ object         |    &lt;- ownership of this part is transferred
1839 |                    |       to c++ when adopted
1840 +--------------------+
1841 | lua class instance |    &lt;- this part is garbage collected when
1842 | and lua members    |       instance is adopted, since it cannot
1843 +--------------------+       be held by c++.
1844 </pre>
1845 <p>The problem can be illustrated by this example:</p>
1846 <pre class="literal-block">
1847 struct A {};
1848
1849 A* filter_a(A* a) { return a; }
1850 void adopt_a(A* a) { delete a; }
1851 </pre>
1852 <pre class="literal-block">
1853 using namespace luabind;
1854
1855 module(L)
1856 [
1857     class_&lt;A&gt;(&quot;A&quot;),
1858     def(&quot;filter_a&quot;, &amp;filter_a),
1859     def(&quot;adopt_a&quot;, &amp;adopt_a, adopt(_1))
1860 ]
1861 </pre>
1862 <p>In lua:</p>
1863 <pre class="literal-block">
1864 a = A()
1865 b = filter_a(a)
1866 adopt_a(b)
1867 </pre>
1868 <p>In this example, lua cannot know that <tt class="docutils literal"><span class="pre">b</span></tt> actually is the same object as
1869 <tt class="docutils literal"><span class="pre">a</span></tt>, and it will therefore consider the object to be owned by the C++ side.
1870 When the <tt class="docutils literal"><span class="pre">b</span></tt> pointer then is adopted, a runtime error will be raised because
1871 an object not owned by lua is being adopted to C++.</p>
1872 <p>If you have a wrapper for your class, none of this will happen, see
1873 <a class="reference" href="#object-identity">Object identity</a>.</p>
1874 </div>
1875 </div>
1876 <div class="section">
1877 <h1><a id="exceptions" name="exceptions">11&nbsp;&nbsp;&nbsp;Exceptions</a></h1>
1878 <p>If any of the functions you register throws an exception when called, that
1879 exception will be caught by luabind and converted to an error string and
1880 <tt class="docutils literal"><span class="pre">lua_error()</span></tt> will be invoked. If the exception is a <tt class="docutils literal"><span class="pre">std::exception</span></tt> or a
1881 <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt> the string that is pushed on the Lua stack, as error message,
1882 will be the string returned by <tt class="docutils literal"><span class="pre">std::exception::what()</span></tt> or the string itself
1883 respectively. If the exception is unknown, a generic string saying that the
1884 function threw an exception will be pushed.</p>
1885 <p>Exceptions thrown from user defined functions have to be caught by luabind. If
1886 they weren't they would be thrown through Lua itself, which is usually compiled
1887 as C code and doesn't support the stack-unwinding that exceptions imply.</p>
1888 <p>Any function that invokes Lua code may throw <tt class="docutils literal"><span class="pre">luabind::error</span></tt>. This exception
1889 means that a Lua run-time error occurred. The error message is found on top of
1890 the Lua stack. The reason why the exception doesn't contain the error string
1891 itself is because it would then require heap allocation which may fail. If an
1892 exception class throws an exception while it is being thrown itself, the
1893 application will be terminated.</p>
1894 <p>Error's synopsis is:</p>
1895 <pre class="literal-block">
1896 class error : public std::exception
1897 {
1898 public:
1899     error(lua_State*);
1900     lua_State* state() const throw();
1901     virtual const char* what() const throw();
1902 };
1903 </pre>
1904 <p>The state function returns a pointer to the Lua state in which the error was
1905 thrown. This pointer may be invalid if you catch this exception after the lua
1906 state is destructed. If the Lua state is valid you can use it to retrieve the
1907 error message from the top of the Lua stack.</p>
1908 <p>An example of where the Lua state pointer may point to an invalid state
1909 follows:</p>
1910 <pre class="literal-block">
1911 struct lua_state
1912 {
1913     lua_state(lua_State* L): m_L(L) {}
1914     ~lua_state() { lua_close(m_L); }
1915     operator lua_State*() { return m_L; }
1916     lua_State* m_L;
1917 };
1918
1919 int main()
1920 {
1921     try
1922     {
1923         lua_state L = lua_open();
1924         /* ... */
1925     }
1926     catch(luabind::error&amp; e)
1927     {
1928         lua_State* L = e.state();
1929         // L will now point to the destructed
1930         // Lua state and be invalid
1931         /* ... */
1932     }
1933 }
1934 </pre>
1935 <p>There's another exception that luabind may throw: <tt class="docutils literal"><span class="pre">luabind::cast_failed</span></tt>,
1936 this exception is thrown from <tt class="docutils literal"><span class="pre">call_function&lt;&gt;</span></tt> or <tt class="docutils literal"><span class="pre">call_member&lt;&gt;</span></tt>. It
1937 means that the return value from the Lua function couldn't be converted to
1938 a C++ value. It is also thrown from <tt class="docutils literal"><span class="pre">object_cast&lt;&gt;</span></tt> if the cast cannot
1939 be made.</p>
1940 <p>The synopsis for <tt class="docutils literal"><span class="pre">luabind::cast_failed</span></tt> is:</p>
1941 <pre class="literal-block">
1942 class cast_failed : public std::exception
1943 {
1944 public:
1945     cast_failed(lua_State*);
1946     lua_State* state() const throw();
1947     LUABIND_TYPE_INFO info() const throw();
1948     virtual const char* what() const throw();
1949 };
1950 </pre>
1951 <p>Again, the state member function returns a pointer to the Lua state where the
1952 error occurred. See the example above to see where this pointer may be invalid.</p>
1953 <p>The info member function returns the user defined <tt class="docutils literal"><span class="pre">LUABIND_TYPE_INFO</span></tt>, which
1954 defaults to a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">std::type_info*</span></tt>. This type info describes the type that
1955 we tried to cast a Lua value to.</p>
1956 <p>If you have defined <tt class="docutils literal"><span class="pre">LUABIND_NO_EXCEPTIONS</span></tt> none of these exceptions will be
1957 thrown, instead you can set two callback functions that are called instead.
1958 These two functions are only defined if <tt class="docutils literal"><span class="pre">LUABIND_NO_EXCEPTIONS</span></tt> are defined.</p>
1959 <pre class="literal-block">
1960 luabind::set_error_callback(void(*)(lua_State*))
1961 </pre>
1962 <p>The function you set will be called when a runtime-error occur in Lua code. You
1963 can find an error message on top of the Lua stack. This function is not
1964 expected to return, if it does luabind will call <tt class="docutils literal"><span class="pre">std::terminate()</span></tt>.</p>
1965 <pre class="literal-block">
1966 luabind::set_cast_failed_callback(void(*)(lua_State*, LUABIND_TYPE_INFO))
1967 </pre>
1968 <p>The function you set is called instead of throwing <tt class="docutils literal"><span class="pre">cast_failed</span></tt>. This function
1969 is not expected to return, if it does luabind will call <tt class="docutils literal"><span class="pre">std::terminate()</span></tt>.</p>
1970 </div>
1971 <div class="section">
1972 <h1><a id="policies" name="policies">12&nbsp;&nbsp;&nbsp;Policies</a></h1>
1973 <p>Sometimes it is necessary to control how luabind passes arguments and return
1974 value, to do this we have policies. All policies use an index to associate
1975 them with an argument in the function signature. These indices are <tt class="docutils literal"><span class="pre">result</span></tt>
1976 and <tt class="docutils literal"><span class="pre">_N</span></tt> (where <tt class="docutils literal"><span class="pre">N</span> <span class="pre">&gt;=</span> <span class="pre">1</span></tt>). When dealing with member functions <tt class="docutils literal"><span class="pre">_1</span></tt> refers
1977 to the <tt class="docutils literal"><span class="pre">this</span></tt> pointer.</p>
1978 <div class="contents local topic">
1979 <p class="topic-title first"><a id="policies-currently-implemented" name="policies-currently-implemented">Policies currently implemented</a></p>
1980 <ul class="auto-toc simple">
1981 <li><a class="reference" href="#adopt" id="id98" name="id98">12.1&nbsp;&nbsp;&nbsp;adopt</a></li>
1982 <li><a class="reference" href="#dependency" id="id99" name="id99">12.2&nbsp;&nbsp;&nbsp;dependency</a></li>
1983 <li><a class="reference" href="#out-value" id="id100" name="id100">12.3&nbsp;&nbsp;&nbsp;out_value</a></li>
1984 <li><a class="reference" href="#pure-out-value" id="id101" name="id101">12.4&nbsp;&nbsp;&nbsp;pure_out_value</a></li>
1985 <li><a class="reference" href="#return-reference-to" id="id102" name="id102">12.5&nbsp;&nbsp;&nbsp;return_reference_to</a></li>
1986 <li><a class="reference" href="#copy" id="id103" name="id103">12.6&nbsp;&nbsp;&nbsp;copy</a></li>
1987 <li><a class="reference" href="#discard-result" id="id104" name="id104">12.7&nbsp;&nbsp;&nbsp;discard_result</a></li>
1988 <li><a class="reference" href="#return-stl-iterator" id="id105" name="id105">12.8&nbsp;&nbsp;&nbsp;return_stl_iterator</a></li>
1989 <li><a class="reference" href="#raw" id="id106" name="id106">12.9&nbsp;&nbsp;&nbsp;raw</a></li>
1990 <li><a class="reference" href="#yield" id="id107" name="id107">12.10&nbsp;&nbsp;&nbsp;yield</a></li>
1991 </ul>
1992 </div>
1993 <div class="section">
1994 <h2><a id="adopt" name="adopt">12.1&nbsp;&nbsp;&nbsp;adopt</a></h2>
1995 <div class="section">
1996 <h3><a id="motivation" name="motivation">12.1.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
1997 <p>Used to transfer ownership across language boundaries.</p>
1998 </div>
1999 <div class="section">
2000 <h3><a id="defined-in" name="defined-in">12.1.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2001 <pre class="literal-block">
2002 #include &lt;luabind/adopt_policy.hpp&gt;
2003 </pre>
2004 </div>
2005 <div class="section">
2006 <h3><a id="synopsis" name="synopsis">12.1.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2007 <pre class="literal-block">
2008 adopt(index)
2009 </pre>
2010 </div>
2011 <div class="section">
2012 <h3><a id="parameters" name="parameters">12.1.4&nbsp;&nbsp;&nbsp;Parameters</a></h3>
2013 <table border="1" class="docutils">
2014 <colgroup>
2015 <col width="17%" />
2016 <col width="83%" />
2017 </colgroup>
2018 <thead valign="bottom">
2019 <tr><th class="head">Parameter</th>
2020 <th class="head">Purpose</th>
2021 </tr>
2022 </thead>
2023 <tbody valign="top">
2024 <tr><td><tt class="docutils literal"><span class="pre">index</span></tt></td>
2025 <td>The index which should transfer ownership, <tt class="docutils literal"><span class="pre">_N</span></tt> or <tt class="docutils literal"><span class="pre">result</span></tt></td>
2026 </tr>
2027 </tbody>
2028 </table>
2029 </div>
2030 <div class="section">
2031 <h3><a id="example" name="example">12.1.5&nbsp;&nbsp;&nbsp;Example</a></h3>
2032 <pre class="literal-block">
2033 X* create()
2034 {
2035     return new X;
2036 }
2037
2038 ...
2039
2040 module(L)
2041 [
2042     def(&quot;create&quot;, &amp;create, <strong>adopt(result)</strong>)
2043 ];
2044 </pre>
2045 </div>
2046 </div>
2047 <div class="section">
2048 <h2><a id="dependency" name="dependency">12.2&nbsp;&nbsp;&nbsp;dependency</a></h2>
2049 <div class="section">
2050 <h3><a id="id2" name="id2">12.2.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2051 <p>The dependency policy is used to create life-time dependencies between values.
2052 This is needed for example when returning internal references to some class.</p>
2053 </div>
2054 <div class="section">
2055 <h3><a id="id3" name="id3">12.2.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2056 <pre class="literal-block">
2057 #include &lt;luabind/dependency_policy.hpp&gt;
2058 </pre>
2059 </div>
2060 <div class="section">
2061 <h3><a id="id4" name="id4">12.2.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2062 <pre class="literal-block">
2063 dependency(nurse_index, patient_index)
2064 </pre>
2065 </div>
2066 <div class="section">
2067 <h3><a id="id5" name="id5">12.2.4&nbsp;&nbsp;&nbsp;Parameters</a></h3>
2068 <table border="1" class="docutils">
2069 <colgroup>
2070 <col width="23%" />
2071 <col width="77%" />
2072 </colgroup>
2073 <thead valign="bottom">
2074 <tr><th class="head">Parameter</th>
2075 <th class="head">Purpose</th>
2076 </tr>
2077 </thead>
2078 <tbody valign="top">
2079 <tr><td><tt class="docutils literal"><span class="pre">nurse_index</span></tt></td>
2080 <td>The index which will keep the patient alive.</td>
2081 </tr>
2082 <tr><td><tt class="docutils literal"><span class="pre">patient_index</span></tt></td>
2083 <td>The index which will be kept alive.</td>
2084 </tr>
2085 </tbody>
2086 </table>
2087 </div>
2088 <div class="section">
2089 <h3><a id="id6" name="id6">12.2.5&nbsp;&nbsp;&nbsp;Example</a></h3>
2090 <pre class="literal-block">
2091 struct X
2092 {
2093     B member;
2094     B&amp; get() { return member; }
2095 };
2096
2097 module(L)
2098 [
2099     class_&lt;X&gt;(&quot;X&quot;)
2100         .def(&quot;get&quot;, &amp;X::get, <strong>dependency(result, _1)</strong>)
2101 ];
2102 </pre>
2103 </div>
2104 </div>
2105 <div class="section">
2106 <h2><a id="out-value" name="out-value">12.3&nbsp;&nbsp;&nbsp;out_value</a></h2>
2107 <div class="section">
2108 <h3><a id="id7" name="id7">12.3.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2109 <p>This policy makes it possible to wrap functions that take non-const references
2110 or pointer to non-const as it's parameters with the intention to write return
2111 values to them. Since it's impossible to pass references to primitive types
2112 in lua, this policy will add another return value with the value after the
2113 call. If the function already has one return value, one instance of this
2114 policy will add another return value (read about multiple return values in
2115 the lua manual).</p>
2116 </div>
2117 <div class="section">
2118 <h3><a id="id8" name="id8">12.3.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2119 <pre class="literal-block">
2120 #include &lt;luabind/out_value_policy.hpp&gt;
2121 </pre>
2122 </div>
2123 <div class="section">
2124 <h3><a id="id9" name="id9">12.3.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2125 <pre class="literal-block">
2126 out_value(index, policies = none)
2127 </pre>
2128 </div>
2129 <div class="section">
2130 <h3><a id="id10" name="id10">12.3.4&nbsp;&nbsp;&nbsp;Parameters</a></h3>
2131 <table border="1" class="docutils">
2132 <colgroup>
2133 <col width="20%" />
2134 <col width="80%" />
2135 </colgroup>
2136 <thead valign="bottom">
2137 <tr><th class="head">Parameter</th>
2138 <th class="head">Purpose</th>
2139 </tr>
2140 </thead>
2141 <tbody valign="top">
2142 <tr><td><tt class="docutils literal"><span class="pre">index</span></tt></td>
2143 <td>The index of the parameter to be used as an out parameter.</td>
2144 </tr>
2145 <tr><td><tt class="docutils literal"><span class="pre">policies</span></tt></td>
2146 <td>The policies used internally to convert the out parameter
2147 to/from Lua. <tt class="docutils literal"><span class="pre">_1</span></tt> means <strong>to</strong> C++, <tt class="docutils literal"><span class="pre">_2</span></tt> means <strong>from</strong>
2148 C++.</td>
2149 </tr>
2150 </tbody>
2151 </table>
2152 </div>
2153 <div class="section">
2154 <h3><a id="id11" name="id11">12.3.5&nbsp;&nbsp;&nbsp;Example</a></h3>
2155 <pre class="literal-block">
2156 void f1(float&amp; val) { val = val + 10.f; }
2157 void f2(float* val) { *val = *val + 10.f; }
2158
2159 module(L)
2160 [
2161     def(&quot;f&quot;, &amp;f, <strong>out_value(_1)</strong>)
2162 ];
2163
2164 Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2165 &gt; print(f1(10))
2166 20
2167 &gt; print(f2(10))
2168 20
2169 </pre>
2170 </div>
2171 </div>
2172 <div class="section">
2173 <h2><a id="pure-out-value" name="pure-out-value">12.4&nbsp;&nbsp;&nbsp;pure_out_value</a></h2>
2174 <div class="section">
2175 <h3><a id="id12" name="id12">12.4.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2176 <p>This works exactly like <tt class="docutils literal"><span class="pre">out_value</span></tt>, except that it will pass a
2177 default constructed object instead of converting an argument from
2178 Lua. This means that the parameter will be removed from the lua
2179 signature.</p>
2180 </div>
2181 <div class="section">
2182 <h3><a id="id13" name="id13">12.4.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2183 <pre class="literal-block">
2184 #include &lt;luabind/out_value_policy.hpp&gt;
2185 </pre>
2186 </div>
2187 <div class="section">
2188 <h3><a id="id14" name="id14">12.4.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2189 <pre class="literal-block">
2190 pure_out_value(index, policies = none)
2191 </pre>
2192 </div>
2193 <div class="section">
2194 <h3><a id="id15" name="id15">12.4.4&nbsp;&nbsp;&nbsp;Parameters</a></h3>
2195 <table border="1" class="docutils">
2196 <colgroup>
2197 <col width="20%" />
2198 <col width="80%" />
2199 </colgroup>
2200 <thead valign="bottom">
2201 <tr><th class="head">Parameter</th>
2202 <th class="head">Purpose</th>
2203 </tr>
2204 </thead>
2205 <tbody valign="top">
2206 <tr><td><tt class="docutils literal"><span class="pre">index</span></tt></td>
2207 <td>The index of the parameter to be used as an out parameter.</td>
2208 </tr>
2209 <tr><td><tt class="docutils literal"><span class="pre">policies</span></tt></td>
2210 <td>The policies used internally to convert the out parameter
2211 to Lua. <tt class="docutils literal"><span class="pre">_1</span></tt> is used as the internal index.</td>
2212 </tr>
2213 </tbody>
2214 </table>
2215 </div>
2216 <div class="section">
2217 <h3><a id="id16" name="id16">12.4.5&nbsp;&nbsp;&nbsp;Example</a></h3>
2218 <p>Note that no values are passed to the calls to <tt class="docutils literal"><span class="pre">f1</span></tt> and <tt class="docutils literal"><span class="pre">f2</span></tt>.</p>
2219 <pre class="literal-block">
2220 void f1(float&amp; val) { val = 10.f; }
2221 void f2(float* val) { *val = 10.f; }
2222
2223 module(L)
2224 [
2225     def(&quot;f&quot;, &amp;f, <strong>pure_out_value(_1)</strong>)
2226 ];
2227
2228 Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2229 &gt; print(f1())
2230 10
2231 &gt; print(f2())
2232 10
2233 </pre>
2234 </div>
2235 </div>
2236 <div class="section">
2237 <h2><a id="return-reference-to" name="return-reference-to">12.5&nbsp;&nbsp;&nbsp;return_reference_to</a></h2>
2238 <div class="section">
2239 <h3><a id="id17" name="id17">12.5.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2240 <p>It is very common to return references to arguments or the this-pointer to
2241 allow for chaining in C++.</p>
2242 <pre class="literal-block">
2243 struct A
2244 {
2245     float val;
2246
2247     A&amp; set(float v)
2248     {
2249         val = v;
2250         return *this;
2251     }
2252 };
2253 </pre>
2254 <p>When luabind generates code for this, it will create a new object for the
2255 return-value, pointing to the self-object. This isn't a problem, but could be a
2256 bit inefficient. When using the return_reference_to-policy we have the ability
2257 to tell luabind that the return-value is already on the lua stack.</p>
2258 </div>
2259 <div class="section">
2260 <h3><a id="id18" name="id18">12.5.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2261 <pre class="literal-block">
2262 #include &lt;luabind/return_reference_to_policy.hpp&gt;
2263 </pre>
2264 </div>
2265 <div class="section">
2266 <h3><a id="id19" name="id19">12.5.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2267 <pre class="literal-block">
2268 return_reference_to(index)
2269 </pre>
2270 </div>
2271 <div class="section">
2272 <h3><a id="id20" name="id20">12.5.4&nbsp;&nbsp;&nbsp;Parameters</a></h3>
2273 <table border="1" class="docutils">
2274 <colgroup>
2275 <col width="13%" />
2276 <col width="87%" />
2277 </colgroup>
2278 <thead valign="bottom">
2279 <tr><th class="head">Parameter</th>
2280 <th class="head">Purpose</th>
2281 </tr>
2282 </thead>
2283 <tbody valign="top">
2284 <tr><td><tt class="docutils literal"><span class="pre">index</span></tt></td>
2285 <td>The argument index to return a reference to, any argument but
2286 not <tt class="docutils literal"><span class="pre">result</span></tt>.</td>
2287 </tr>
2288 </tbody>
2289 </table>
2290 </div>
2291 <div class="section">
2292 <h3><a id="id21" name="id21">12.5.5&nbsp;&nbsp;&nbsp;Example</a></h3>
2293 <pre class="literal-block">
2294 struct A
2295 {
2296     float val;
2297
2298     A&amp; set(float v)
2299     {
2300         val = v;
2301         return *this;
2302     }
2303 };
2304
2305 module(L)
2306 [
2307     class_&lt;A&gt;(&quot;A&quot;)
2308         .def(constructor&lt;&gt;())
2309         .def(&quot;set&quot;, &amp;A::set, <strong>return_reference_to(_1)</strong>)
2310 ];
2311 </pre>
2312 <div class="warning">
2313 <p class="first admonition-title">Warning</p>
2314 <p class="last">This policy ignores all type information and should be used only it
2315 situations where the parameter type is a perfect match to the
2316 return-type (such as in the example).</p>
2317 </div>
2318 </div>
2319 </div>
2320 <div class="section">
2321 <h2><a id="copy" name="copy">12.6&nbsp;&nbsp;&nbsp;copy</a></h2>
2322 <div class="section">
2323 <h3><a id="id22" name="id22">12.6.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2324 <p>This will make a copy of the parameter. This is the default behavior when
2325 passing parameters by-value. Note that this can only be used when passing from
2326 C++ to Lua. This policy requires that the parameter type has an accessible copy
2327 constructor.</p>
2328 </div>
2329 <div class="section">
2330 <h3><a id="id23" name="id23">12.6.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2331 <pre class="literal-block">
2332 #include &lt;luabind/copy_policy.hpp&gt;
2333 </pre>
2334 </div>
2335 <div class="section">
2336 <h3><a id="id24" name="id24">12.6.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2337 <pre class="literal-block">
2338 copy(index)
2339 </pre>
2340 </div>
2341 <div class="section">
2342 <h3><a id="id25" name="id25">12.6.4&nbsp;&nbsp;&nbsp;Parameters</a></h3>
2343 <table border="1" class="docutils">
2344 <colgroup>
2345 <col width="17%" />
2346 <col width="83%" />
2347 </colgroup>
2348 <thead valign="bottom">
2349 <tr><th class="head">Parameter</th>
2350 <th class="head">Purpose</th>
2351 </tr>
2352 </thead>
2353 <tbody valign="top">
2354 <tr><td><tt class="docutils literal"><span class="pre">index</span></tt></td>
2355 <td>The index to copy. <tt class="docutils literal"><span class="pre">result</span></tt> when used while wrapping C++
2356 functions. <tt class="docutils literal"><span class="pre">_N</span></tt> when passing arguments to Lua.</td>
2357 </tr>
2358 </tbody>
2359 </table>
2360 </div>
2361 <div class="section">
2362 <h3><a id="id26" name="id26">12.6.5&nbsp;&nbsp;&nbsp;Example</a></h3>
2363 <pre class="literal-block">
2364 X* get()
2365 {
2366     static X instance;
2367     return &amp;instance;
2368 }
2369
2370 ...
2371
2372 module(L)
2373 [
2374     def(&quot;create&quot;, &amp;create, <strong>copy(result)</strong>)
2375 ];
2376 </pre>
2377 </div>
2378 </div>
2379 <div class="section">
2380 <h2><a id="discard-result" name="discard-result">12.7&nbsp;&nbsp;&nbsp;discard_result</a></h2>
2381 <div class="section">
2382 <h3><a id="id27" name="id27">12.7.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2383 <p>This is a very simple policy which makes it possible to throw away
2384 the value returned by a C++ function, instead of converting it to
2385 Lua.</p>
2386 </div>
2387 <div class="section">
2388 <h3><a id="id28" name="id28">12.7.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2389 <pre class="literal-block">
2390 #include &lt;luabind/discard_result_policy.hpp&gt;
2391 </pre>
2392 </div>
2393 <div class="section">
2394 <h3><a id="id29" name="id29">12.7.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2395 <pre class="literal-block">
2396 discard_result
2397 </pre>
2398 </div>
2399 <div class="section">
2400 <h3><a id="id30" name="id30">12.7.4&nbsp;&nbsp;&nbsp;Example</a></h3>
2401 <pre class="literal-block">
2402 struct X
2403 {
2404     X&amp; set(T n)
2405     {
2406         ...
2407         return *this;
2408     }
2409 };
2410
2411 ...
2412
2413 module(L)
2414 [
2415     class_&lt;X&gt;(&quot;X&quot;)
2416         .def(&quot;set&quot;, &amp;simple::set, <strong>discard_result</strong>)
2417 ];
2418 </pre>
2419 </div>
2420 </div>
2421 <div class="section">
2422 <h2><a id="return-stl-iterator" name="return-stl-iterator">12.8&nbsp;&nbsp;&nbsp;return_stl_iterator</a></h2>
2423 <div class="section">
2424 <h3><a id="id31" name="id31">12.8.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2425 <p>This policy converts an STL container to a generator function that can be used
2426 in lua to iterate over the container. It works on any container that defines
2427 <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> member functions (they have to return iterators).</p>
2428 </div>
2429 <div class="section">
2430 <h3><a id="id32" name="id32">12.8.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2431 <pre class="literal-block">
2432 #include &lt;luabind/iterator_policy.hpp&gt;
2433 </pre>
2434 </div>
2435 <div class="section">
2436 <h3><a id="id33" name="id33">12.8.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2437 <pre class="literal-block">
2438 return_stl_iterator
2439 </pre>
2440 </div>
2441 <div class="section">
2442 <h3><a id="id34" name="id34">12.8.4&nbsp;&nbsp;&nbsp;Example</a></h3>
2443 <pre class="literal-block">
2444 struct X
2445 {
2446     std::vector&lt;std::string&gt; names;
2447 };
2448
2449 ...
2450
2451 module(L)
2452 [
2453     class_&lt;A&gt;(&quot;A&quot;)
2454         .def_readwrite(&quot;names&quot;, &amp;X::names, <strong>return_stl_iterator</strong>)
2455 ];
2456
2457 ...
2458
2459 &gt; a = A()
2460 &gt; for name in a.names do
2461 &gt;  print(name)
2462 &gt; end
2463 </pre>
2464 </div>
2465 </div>
2466 <div class="section">
2467 <h2><a id="raw" name="raw">12.9&nbsp;&nbsp;&nbsp;raw</a></h2>
2468 <div class="section">
2469 <h3><a id="id35" name="id35">12.9.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2470 <p>This converter policy will pass through the <tt class="docutils literal"><span class="pre">lua_State*</span></tt> unmodified.
2471 This can be useful for example when binding functions that need to
2472 return a <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. The parameter will be removed from the
2473 function signature, decreasing the function arity by one.</p>
2474 </div>
2475 <div class="section">
2476 <h3><a id="id36" name="id36">12.9.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2477 <pre class="literal-block">
2478 #include &lt;luabind/raw_policy.hpp&gt;
2479 </pre>
2480 </div>
2481 <div class="section">
2482 <h3><a id="id37" name="id37">12.9.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2483 <pre class="literal-block">
2484 raw(index)
2485 </pre>
2486 </div>
2487 <div class="section">
2488 <h3><a id="id38" name="id38">12.9.4&nbsp;&nbsp;&nbsp;Parameters</a></h3>
2489 <table border="1" class="docutils">
2490 <colgroup>
2491 <col width="17%" />
2492 <col width="83%" />
2493 </colgroup>
2494 <thead valign="bottom">
2495 <tr><th class="head">Parameter</th>
2496 <th class="head">Purpose</th>
2497 </tr>
2498 </thead>
2499 <tbody valign="top">
2500 <tr><td><tt class="docutils literal"><span class="pre">index</span></tt></td>
2501 <td>The index of the lua_State* parameter.</td>
2502 </tr>
2503 </tbody>
2504 </table>
2505 </div>
2506 <div class="section">
2507 <h3><a id="id39" name="id39">12.9.5&nbsp;&nbsp;&nbsp;Example</a></h3>
2508 <pre class="literal-block">
2509 void greet(lua_State* L)
2510 {
2511     lua_pushstring(L, &quot;hello&quot;);
2512 }
2513
2514 ...
2515
2516 module(L)
2517 [
2518     def(&quot;greet&quot;, &amp;greet, <strong>raw(_1)</strong>)
2519 ];
2520
2521 &gt; print(greet())
2522 hello
2523 </pre>
2524 </div>
2525 </div>
2526 <div class="section">
2527 <h2><a id="yield" name="yield">12.10&nbsp;&nbsp;&nbsp;yield</a></h2>
2528 <div class="section">
2529 <h3><a id="id40" name="id40">12.10.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
2530 <p>Makes a C++ function yield when returning.</p>
2531 </div>
2532 <div class="section">
2533 <h3><a id="id41" name="id41">12.10.2&nbsp;&nbsp;&nbsp;Defined in</a></h3>
2534 <pre class="literal-block">
2535 #include &lt;luabind/yield_policy.hpp&gt;
2536 </pre>
2537 </div>
2538 <div class="section">
2539 <h3><a id="id42" name="id42">12.10.3&nbsp;&nbsp;&nbsp;Synopsis</a></h3>
2540 <pre class="literal-block">
2541 yield
2542 </pre>
2543 </div>
2544 <div class="section">
2545 <h3><a id="id43" name="id43">12.10.4&nbsp;&nbsp;&nbsp;Example</a></h3>
2546 <pre class="literal-block">
2547 void do_thing_that_takes_time()
2548 {
2549     ...
2550 }
2551
2552 ...
2553
2554 module(L)
2555 [
2556     def(&quot;do_thing_that_takes_time&quot;, &amp;do_thing_that_takes_time, <strong>yield</strong>)
2557 ];
2558 </pre>
2559 <!-- old policies section
2560 ===================================================
2561
2562 Copy
2563 - - - -
2564
2565 This will make a copy of the parameter. This is the default behavior when
2566 passing parameters by-value. Note that this can only be used when passing from
2567 C++ to Lua. This policy requires that the parameter type has a copy
2568 constructor.
2569
2570 To use this policy you need to include ``luabind/copy_policy.hpp``.
2571
2572
2573 Adopt
2574 - - - - -
2575
2576 This will transfer ownership of the parameter.
2577
2578 Consider making a factory function in C++ and exposing it to lua::
2579
2580     base* create_base()
2581     {
2582         return new base();
2583     }
2584
2585     ...
2586
2587     module(L)
2588     [
2589         def("create_base", create_base)
2590     ];
2591
2592 Here we need to make sure Lua understands that it should adopt the pointer
2593 returned by the factory-function. This can be done using the adopt-policy.
2594
2595 ::
2596
2597     module(L)
2598     [
2599         def(L, "create_base", adopt(return_value))
2600     ];
2601
2602 To specify multiple policies we just separate them with '+'.
2603
2604 ::
2605
2606     base* set_and_get_new(base* ptr)
2607     {
2608         base_ptrs.push_back(ptr);
2609         return new base();
2610     }
2611
2612     module(L)
2613     [
2614         def("set_and_get_new", &set_and_get_new,
2615             adopt(return_value) + adopt(_1))
2616     ];
2617
2618 When Lua adopts a pointer, it will call delete on it. This means that it cannot
2619 adopt pointers allocated with another allocator than new (no malloc for
2620 example).
2621
2622 To use this policy you need to include ``luabind/adopt_policy.hpp``.
2623
2624
2625 Dependency
2626 - - - - - - - - - -
2627
2628 The dependency policy is used to create life-time dependencies between values.
2629 Consider the following example::
2630
2631     struct A
2632     {
2633         B member;
2634
2635         const B& get_member()
2636         {
2637             return member;
2638         }
2639     };
2640
2641 When wrapping this class, we would do something like::
2642
2643     module(L)
2644     [
2645         class_<A>("A")
2646             .def(constructor<>())
2647             .def("get_member", &A::get_member)
2648     ];
2649
2650
2651 However, since the return value of get_member is a reference to a member of A,
2652 this will create some life-time issues. For example::
2653
2654     Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2655     a = A()
2656     b = a:get_member() - - b points to a member of a
2657     a = nil
2658     collectgarbage(0)  - - since there are no references left to a, it is
2659                        - - removed
2660                        - - at this point, b is pointing into a removed object
2661
2662 When using the dependency-policy, it is possible to tell luabind to tie the
2663 lifetime of one object to another, like this::
2664
2665     module(L)
2666     [
2667         class_<A>("A")
2668             .def(constructor<>())
2669             .def("get_member", &A::get_member, dependency(result, _1))
2670     ];
2671
2672 This will create a dependency between the return-value of the function, and the
2673 self-object. This means that the self-object will be kept alive as long as the
2674 result is still alive. ::
2675
2676     Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2677     a = A()
2678     b = a:get_member() - - b points to a member of a
2679     a = nil
2680     collectgarbage(0)  - - a is dependent on b, so it isn't removed
2681     b = nil
2682     collectgarbage(0)  - - all dependencies to a gone, a is removed
2683
2684 To use this policy you need to include ``luabind/dependency_policy.hpp``.
2685
2686
2687 Return reference to
2688 - - - - - - - - - - - - - - - - - - -
2689
2690 It is very common to return references to arguments or the this-pointer to
2691 allow for chaining in C++.
2692
2693 ::
2694
2695     struct A
2696     {
2697         float val;
2698
2699         A& set(float v)
2700         {
2701             val = v;
2702             return *this;
2703         }
2704     };
2705
2706 When luabind generates code for this, it will create a new object for the
2707 return-value, pointing to the self-object. This isn't a problem, but could be a
2708 bit inefficient. When using the return_reference_to-policy we have the ability
2709 to tell luabind that the return-value is already on the Lua stack.
2710
2711 ::
2712
2713     module(L)
2714     [
2715         class_<A>("A")
2716             .def(constructor<>())
2717             .def("set", &A::set, return_reference_to(_1))
2718     ];
2719
2720 Instead of creating a new object, luabind will just copy the object that is
2721 already on the stack.
2722
2723 .. warning::
2724    This policy ignores all type information and should be used only it
2725    situations where the parameter type is a perfect match to the
2726    return-type (such as in the example).
2727
2728 To use this policy you need to include ``luabind/return_reference_to_policy.hpp``.
2729
2730
2731 Out value
2732 - - - - - - - - -
2733
2734 This policy makes it possible to wrap functions that take non const references
2735 as its parameters with the intention to write return values to them.
2736
2737 ::
2738
2739     void f(float& val) { val = val + 10.f; }
2740
2741 or
2742
2743 ::
2744
2745     void f(float* val) { *val = *val + 10.f; }
2746
2747 Can be wrapped by doing::
2748
2749     module(L)
2750     [
2751         def("f", &f, out_value(_1))
2752     ];
2753
2754 When invoking this function from Lua it will return the value assigned to its
2755 parameter.
2756
2757 ::
2758
2759     Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2760     > a = f(10)
2761     > print(a)
2762     20
2763
2764 When this policy is used in conjunction with user define types we often need
2765 to do ownership transfers.
2766
2767 ::
2768
2769     struct A;
2770
2771     void f1(A*& obj) { obj = new A(); }
2772     void f2(A** obj) { *obj = new A(); }
2773
2774 Here we need to make sure luabind takes control over object returned, for
2775 this we use the adopt policy::
2776
2777     module(L)
2778     [
2779         class_<A>("A"),
2780         def("f1", &f1, out_value(_1, adopt(_2)))
2781         def("f2", &f2, out_value(_1, adopt(_2)))
2782     ];
2783
2784 Here we are using adopt as an internal policy to out_value. The index
2785 specified, _2, means adopt will be used to convert the value back to Lua.
2786 Using _1 means the policy will be used when converting from Lua to C++.
2787
2788 To use this policy you need to include ``luabind/out_value_policy.hpp``.
2789
2790 Pure out value
2791 - - - - - - - - - - - - - -
2792
2793 This policy works in exactly the same way as out_value, except that it
2794 replaces the parameters with default-constructed objects.
2795
2796 ::
2797
2798     void get(float& x, float& y)
2799     {
2800         x = 3.f;
2801         y = 4.f;
2802     }
2803
2804     ...
2805
2806     module(L)
2807     [
2808         def("get", &get,
2809             pure_out_value(_1) + pure_out_value(_2))
2810     ];
2811
2812 ::
2813
2814     Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
2815     > x, y = get()
2816     > print(x, y)
2817     3    5
2818
2819 Like out_value, it is possible to specify an internal policy used then
2820 converting the values back to Lua.
2821
2822 ::
2823
2824     void get(test_class*& obj)
2825     {
2826         obj = new test_class();
2827     }
2828
2829     ...
2830
2831     module(L)
2832     [
2833         def("get", &get, pure_out_value(_1, adopt(_1)))
2834     ];
2835
2836
2837 Discard result
2838 - - - - - - - - - - - - - -
2839
2840 This is a very simple policy which makes it possible to throw away
2841 the value returned by a C++ function, instead of converting it to
2842 Lua. This example makes sure the this reference never gets converted
2843 to Lua.
2844
2845 ::
2846
2847     struct simple
2848     {
2849         simple& set_name(const std::string& n)
2850         {
2851             name = n;
2852             return *this;
2853         }
2854
2855         std::string name;
2856     };
2857
2858     ...
2859
2860     module(L)
2861     [
2862         class_<simple>("simple")
2863             .def("set_name", &simple::set_name, discard_result)
2864     ];
2865
2866 To use this policy you need to include ``luabind/discard_result_policy.hpp``.
2867
2868
2869 Return STL iterator
2870 - - - - - - - - - - - - - - - - - - -
2871
2872 This policy converts an STL container to a generator function that can be used
2873 in Lua to iterate over the container. It works on any container that defines
2874 ``begin()`` and ``end()`` member functions (they have to return iterators). It
2875 can be used like this::
2876
2877     struct A
2878     {
2879         std::vector<std::string> names;
2880     };
2881
2882
2883     module(L)
2884     [
2885         class_<A>("A")
2886             .def_readwrite("names", &A::names, return_stl_iterator)
2887     ];
2888
2889 The Lua code to iterate over the container::
2890
2891     a = A()
2892
2893     for name in a.names do
2894       print(name)
2895     end
2896
2897
2898 To use this policy you need to include ``luabind/iterator_policy.hpp``.
2899
2900
2901 Yield
2902 - - - - -
2903
2904 This policy will cause the function to always yield the current thread when
2905 returning. See the Lua manual for restrictions on yield. -->
2906 </div>
2907 </div>
2908 </div>
2909 <div class="section">
2910 <h1><a id="splitting-up-the-registration" name="splitting-up-the-registration">13&nbsp;&nbsp;&nbsp;Splitting up the registration</a></h1>
2911 <p>It is possible to split up a module registration into several
2912 translation units without making each registration dependent
2913 on the module it's being registered in.</p>
2914 <p><tt class="docutils literal"><span class="pre">a.cpp</span></tt>:</p>
2915 <pre class="literal-block">
2916 luabind::scope register_a()
2917 {
2918     return
2919         class_&lt;a&gt;(&quot;a&quot;)
2920             .def(&quot;f&quot;, &amp;a::f)
2921             ;
2922 }
2923 </pre>
2924 <p><tt class="docutils literal"><span class="pre">b.cpp</span></tt>:</p>
2925 <pre class="literal-block">
2926 luabind::scope register_b()
2927 {
2928     return
2929         class_&lt;b&gt;(&quot;b&quot;)
2930             .def(&quot;g&quot;, &amp;b::g)
2931             ;
2932 }
2933 </pre>
2934 <p><tt class="docutils literal"><span class="pre">module_ab.cpp</span></tt>:</p>
2935 <pre class="literal-block">
2936 luabind::scope register_a();
2937 luabind::scope register_b();
2938
2939 void register_module(lua_State* L)
2940 {
2941     module(&quot;b&quot;, L)
2942     [
2943         register_a(),
2944         register_b()
2945     ];
2946 }
2947 </pre>
2948 </div>
2949 <div class="section">
2950 <h1><a id="error-handling" name="error-handling">14&nbsp;&nbsp;&nbsp;Error Handling</a></h1>
2951 <div class="section">
2952 <h2><a id="pcall-errorfunc" name="pcall-errorfunc">14.1&nbsp;&nbsp;&nbsp;pcall errorfunc</a></h2>
2953 <p>As mentioned in the <a class="reference" href="http://www.lua.org/manual/5.0/manual.html">Lua documentation</a>, it is possible to pass an
2954 error handler function to <tt class="docutils literal"><span class="pre">lua_pcall()</span></tt>. Luabind makes use of
2955 <tt class="docutils literal"><span class="pre">lua_pcall()</span></tt> internally when calling member functions and free functions.
2956 It is possible to set the error handler function that Luabind will use
2957 globally:</p>
2958 <pre class="literal-block">
2959 typedef int(*pcall_callback_fun)(lua_State*);
2960 void set_pcall_callback(pcall_callback_fun fn);
2961 </pre>
2962 <p>This is primarily useful for adding more information to the error message
2963 returned by a failed protected call. For more information on how to use the
2964 pcall_callback function, see <tt class="docutils literal"><span class="pre">errfunc</span></tt> under the
2965 <a class="reference" href="http://www.lua.org/manual/5.0/manual.html#3.15">pcall section of the lua manual</a>.</p>
2966 <p>For more information on how to retrieve debugging information from lua, see
2967 <a class="reference" href="http://www.lua.org/manual/5.0/manual.html#4">the debug section of the lua manual</a>.</p>
2968 <p>The message returned by the <tt class="docutils literal"><span class="pre">pcall_callback</span></tt> is accessable as the top lua
2969 value on the stack. For example, if you would like to access it as a luabind
2970 object, you could do like this:</p>
2971 <pre class="literal-block">
2972 catch(error&amp; e)
2973 {
2974     object error_msg(from_stack(e.state(), -1));
2975     std::cout &lt;&lt; error_msg &lt;&lt; std::endl;
2976 }
2977 </pre>
2978 </div>
2979 <div class="section">
2980 <h2><a id="file-and-line-numbers" name="file-and-line-numbers">14.2&nbsp;&nbsp;&nbsp;file and line numbers</a></h2>
2981 <p>If you want to add file name and line number to the error messages generated
2982 by luabind you can define your own <a class="reference" href="#pcall-errorfunc">pcall errorfunc</a>. You may want to modify
2983 this callback to better suit your needs, but the basic functionality could be
2984 implemented like this:</p>
2985 <pre class="literal-block">
2986 int add_file_and_line(lua_State* L)
2987 {
2988    lua_Debug d;
2989    lua_getstack(L, 1, &amp;d);
2990    lua_getinfo(L, &quot;Sln&quot;, &amp;d);
2991    std::string err = lua_tostring(L, -1);
2992    lua_pop(L, 1);
2993    std::stringstream msg;
2994    msg &lt;&lt; d.short_src &lt;&lt; &quot;:&quot; &lt;&lt; d.currentline;
2995
2996    if (d.name != 0)
2997    {
2998       msg &lt;&lt; &quot;(&quot; &lt;&lt; d.namewhat &lt;&lt; &quot; &quot; &lt;&lt; d.name &lt;&lt; &quot;)&quot;;
2999    }
3000    msg &lt;&lt; &quot; &quot; &lt;&lt; err;
3001    lua_pushstring(L, msg.str().c_str());
3002    return 1;
3003 }
3004 </pre>
3005 <p>For more information about what kind of information you can add to the error
3006 message, see <a class="reference" href="http://www.lua.org/manual/5.0/manual.html#4">the debug section of the lua manual</a>.</p>
3007 <p>Note that the callback set by <tt class="docutils literal"><span class="pre">set_pcall_callback()</span></tt> will only be used when
3008 luabind executes lua code. Anytime when you call <tt class="docutils literal"><span class="pre">lua_pcall</span></tt> yourself, you
3009 have to supply your function if you want error messages translated.</p>
3010 </div>
3011 <div class="section">
3012 <h2><a id="lua-panic" name="lua-panic">14.3&nbsp;&nbsp;&nbsp;lua panic</a></h2>
3013 <p>When lua encounters a fatal error caused by a bug from the C/C++ side, it will
3014 call its internal panic function. This can happen, for example,  when you call
3015 <tt class="docutils literal"><span class="pre">lua_gettable</span></tt> on a value that isn't a table. If you do the same thing from
3016 within lua, it will of course just fail with an error message.</p>
3017 <p>The default panic function will <tt class="docutils literal"><span class="pre">exit()</span></tt> the application. If you want to
3018 handle this case without terminating your application, you can define your own
3019 panic function using <tt class="docutils literal"><span class="pre">lua_atpanic</span></tt>. The best way to continue from the panic
3020 function is to make sure lua is compiled as C++ and throw an exception from
3021 the panic function. Throwing an exception instead of using <tt class="docutils literal"><span class="pre">setjmp</span></tt> and
3022 <tt class="docutils literal"><span class="pre">longjmp</span></tt> will make sure the stack is correctly unwound.</p>
3023 <p>When the panic function is called, the lua state is invalid, and the only
3024 allowed operation on it is to close it.</p>
3025 <p>For more information, see the <a class="reference" href="http://www.lua.org/manual/5.0/manual.html#3.19">lua manual section 3.19</a>.</p>
3026 </div>
3027 <div class="section">
3028 <h2><a id="structured-exceptions-msvc" name="structured-exceptions-msvc">14.4&nbsp;&nbsp;&nbsp;structured exceptions (MSVC)</a></h2>
3029 <p>Since lua is generally built as a C library, any callbacks called from lua
3030 cannot under any circumstance throw an exception. Because of that, luabind has
3031 to catch all exceptions and translate them into proper lua errors (by calling
3032 <tt class="docutils literal"><span class="pre">lua_error()</span></tt>). This means we have a <tt class="docutils literal"><span class="pre">catch(...)</span> <span class="pre">{}</span></tt> in there.</p>
3033 <p>In Visual Studio, <tt class="docutils literal"><span class="pre">catch</span> <span class="pre">(...)</span></tt> will not only catch C++ exceptions, it will
3034 also catch structured exceptions, such as segmentation fault. This means that if
3035 your function, that gets called from luabind, makes an invalid memory
3036 adressing, you won't notice it. All that will happen is that lua will return
3037 an error message saying &quot;unknown exception&quot;.</p>
3038 <p>To remedy this, you can create your own <em>exception translator</em>:</p>
3039 <pre class="literal-block">
3040 void straight_to_debugger(unsigned int, _EXCEPTION_POINTERS*)
3041 { throw; }
3042
3043 #ifdef _MSC_VER
3044    ::_set_se_translator(straight_to_debugger);
3045 #endif
3046 </pre>
3047 <p>This will make structured exceptions, like segmentation fault, to actually get
3048 caught by the debugger.</p>
3049 </div>
3050 <div class="section">
3051 <h2><a id="error-messages" name="error-messages">14.5&nbsp;&nbsp;&nbsp;Error messages</a></h2>
3052 <p>These are the error messages that can be generated by luabind, with a more
3053 in-depth explanation.</p>
3054 <ul>
3055 <li><pre class="first literal-block">
3056 the attribute '<em>class-name.attribute-name</em>' is read only
3057 </pre>
3058 <p>There is no data member named <em>attribute-name</em> in the class <em>class-name</em>,
3059 or there's no setter-function registered on that property name. See the
3060 <a class="reference" href="#properties">Properties</a> section.</p>
3061 </li>
3062 <li><pre class="first literal-block">
3063 the attribute '<em>class-name.attribute-name</em>' is of type: (<em>class-name</em>) and does not match (<em>class_name</em>)
3064 </pre>
3065 <p>This error is generated if you try to assign an attribute with a value
3066 of a type that cannot be converted to the attribute's type.</p>
3067 </li>
3068 <li><pre class="first literal-block">
3069 <em>class-name()</em> threw an exception, <em>class-name:function-name()</em> threw an exception
3070 </pre>
3071 <p>The class' constructor or member function threw an unknown exception.
3072 Known exceptions are const char*, std::exception. See the
3073 <a class="reference" href="#exceptions">exceptions</a> section.</p>
3074 </li>
3075 <li><pre class="first literal-block">
3076 no overload of '<em>class-name:function-name</em>' matched the arguments (<em>parameter-types</em>)
3077 no match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>)
3078 no constructor of <em>class-name</em> matched the arguments (<em>parameter-types</em>)
3079 no operator <em>operator-name</em> matched the arguments (<em>parameter-types</em>)
3080 </pre>
3081 <p>No function/operator with the given name takes the parameters you gave
3082 it. You have either misspelled the function name, or given it incorrect
3083 parameters. This error is followed by a list of possible candidate
3084 functions to help you figure out what parameter has the wrong type. If
3085 the candidate list is empty there's no function at all with that name.
3086 See the signature matching section.</p>
3087 </li>
3088 <li><pre class="first literal-block">
3089 call of overloaded '<em>class-name:function-name*(*parameter-types</em>)' is ambiguous
3090 ambiguous match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>)
3091 call of overloaded constructor '<em>class-name*(*parameter-types</em>)' is ambiguous
3092 call of overloaded operator <em>operator-name</em> (<em>parameter-types</em>) is ambiguous
3093 </pre>
3094 <p>This means that the function/operator you are trying to call has at least
3095 one other overload that matches the arguments just as good as the first
3096 overload.</p>
3097 </li>
3098 <li><pre class="first literal-block">
3099 cannot derive from C++ class '<em>class-name</em>'. It does not have a wrapped type.
3100 </pre>
3101 </li>
3102 </ul>
3103 </div>
3104 </div>
3105 <div class="section">
3106 <h1><a id="build-options" name="build-options">15&nbsp;&nbsp;&nbsp;Build options</a></h1>
3107 <p>There are a number of configuration options available when building luabind.
3108 It is very important that your project has the exact same configuration
3109 options as the ones given when the library was build! The exceptions are the
3110 <tt class="docutils literal"><span class="pre">LUABIND_MAX_ARITY</span></tt> and <tt class="docutils literal"><span class="pre">LUABIND_MAX_BASES</span></tt> which are template-based
3111 options and only matters when you use the library (which means they can
3112 differ from the settings of the library).</p>
3113 <p>The default settings which will be used if no other settings are given
3114 can be found in <tt class="docutils literal"><span class="pre">luabind/config.hpp</span></tt>.</p>
3115 <p>If you want to change the settings of the library, you can modify the
3116 config file. It is included and used by all makefiles. You can change paths
3117 to Lua and boost in there as well.</p>
3118 <dl class="docutils">
3119 <dt>LUABIND_MAX_ARITY</dt>
3120 <dd>Controls the maximum arity of functions that are registered with luabind.
3121 You can't register functions that takes more parameters than the number
3122 this macro is set to. It defaults to 5, so, if your functions have greater
3123 arity you have to redefine it. A high limit will increase compilation time.</dd>
3124 <dt>LUABIND_MAX_BASES</dt>
3125 <dd>Controls the maximum number of classes one class can derive from in
3126 luabind (the number of classes specified within <tt class="docutils literal"><span class="pre">bases&lt;&gt;</span></tt>).
3127 <tt class="docutils literal"><span class="pre">LUABIND_MAX_BASES</span></tt> defaults to 4. A high limit will increase
3128 compilation time.</dd>
3129 <dt>LUABIND_NO_ERROR_CHECKING</dt>
3130 <dd><p class="first">If this macro is defined, all the Lua code is expected only to make legal
3131 calls. If illegal function calls are made (e.g. giving parameters that
3132 doesn't match the function signature) they will not be detected by luabind
3133 and the application will probably crash. Error checking could be disabled
3134 when shipping a release build (given that no end-user has access to write
3135 custom Lua code). Note that function parameter matching will be done if a
3136 function is overloaded, since otherwise it's impossible to know which one
3137 was called. Functions will still be able to throw exceptions when error
3138 checking is disabled.</p>
3139 <p class="last">If a function throws an exception it will be caught by luabind and
3140 propagated with <tt class="docutils literal"><span class="pre">lua_error()</span></tt>.</p>
3141 </dd>
3142 <dt>LUABIND_NO_EXCEPTIONS</dt>
3143 <dd><p class="first">This define will disable all usage of try, catch and throw in luabind.
3144 This will in many cases disable run-time errors, when performing invalid
3145 casts or calling Lua functions that fails or returns values that cannot
3146 be converted by the given policy. luabind requires that no function called
3147 directly or indirectly by luabind throws an exception (throwing exceptions
3148 through Lua has undefined behavior).</p>
3149 <p class="last">Where exceptions are the only way to get an error report from luabind,
3150 they will be replaced with calls to the callback functions set with
3151 <tt class="docutils literal"><span class="pre">set_error_callback()</span></tt> and <tt class="docutils literal"><span class="pre">set_cast_failed_callback()</span></tt>.</p>
3152 </dd>
3153 <dt>LUA_API</dt>
3154 <dd>If you want to link dynamically against Lua, you can set this define to
3155 the import-keyword on your compiler and platform. On Windows in Visual Studio
3156 this should be <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt> if you want to link against Lua
3157 as a dll.</dd>
3158 <dt>LUABIND_EXPORT, LUABIND_IMPORT</dt>
3159 <dd>If you want to link against luabind as a dll (in Visual Studio), you can
3160 define <tt class="docutils literal"><span class="pre">LUABIND_EXPORT</span></tt> to <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> and
3161 <tt class="docutils literal"><span class="pre">LUABIND_IMPORT</span></tt> to <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt> or
3162 <tt class="docutils literal"><span class="pre">__attribute__</span> <span class="pre">((visibility(&quot;default&quot;)))</span></tt> on GCC 4.
3163 Note that you have to link against Lua as a dll aswell, to make it work.</dd>
3164 <dt>LUABIND_NO_RTTI</dt>
3165 <dd>You can define this if you don't want luabind to use <tt class="docutils literal"><span class="pre">dynamic_cast&lt;&gt;</span></tt>.
3166 It will disable <a class="reference" href="#object-identity">Object identity</a>.</dd>
3167 <dt>LUABIND_TYPE_INFO, LUABIND_TYPE_INFO_EQUAL(i1,i2), LUABIND_TYPEID(t), LUABIND_INVALID_TYPE_INFO</dt>
3168 <dd><p class="first">If you don't want to use the RTTI supplied by C++ you can supply your own
3169 type-info structure with the <tt class="docutils literal"><span class="pre">LUABIND_TYPE_INFO</span></tt> define. Your type-info
3170 structure must be copyable and must be able to compare itself against
3171 other type-info structures. You supply the compare function through the
3172 <tt class="docutils literal"><span class="pre">LUABIND_TYPE_INFO_EQUAL()</span></tt> define. It should compare the two type-info
3173 structures it is given and return true if they represent the same type and
3174 false otherwise. You also have to supply a function to generate your
3175 type-info structure. You do this through the <tt class="docutils literal"><span class="pre">LUABIND_TYPEID()</span></tt> define.
3176 It should return your type-info structure and it takes a type as its
3177 parameter. That is, a compile time parameter.
3178 <tt class="docutils literal"><span class="pre">LUABIND_INVALID_TYPE_INFO</span></tt> macro should be defined to an invalid type.
3179 No other type should be able to produce this type info. To use it you
3180 probably have to make a traits class with specializations for all classes
3181 that you have type-info for. Like this:</p>
3182 <pre class="literal-block">
3183 class A;
3184 class B;
3185 class C;
3186
3187 template&lt;class T&gt; struct typeinfo_trait;
3188
3189 template&lt;&gt; struct typeinfo_trait&lt;A&gt; { enum { type_id = 0 }; };
3190 template&lt;&gt; struct typeinfo_trait&lt;B&gt; { enum { type_id = 1 }; };
3191 template&lt;&gt; struct typeinfo_trait&lt;C&gt; { enum { type_id = 2 }; };
3192 </pre>
3193 <p>If you have set up your own RTTI system like this (by using integers to
3194 identify types) you can have luabind use it with the following defines:</p>
3195 <pre class="literal-block">
3196 #define LUABIND_TYPE_INFO const std::type_info*
3197 #define LUABIND_TYPEID(t) &amp;typeid(t)
3198 #define LUABIND_TYPE_INFO_EQUAL(i1, i2) *i1 == *i2
3199 #define LUABIND_INVALID_TYPE_INFO &amp;typeid(detail::null_type)
3200 </pre>
3201 <p class="last">Currently the type given through <tt class="docutils literal"><span class="pre">LUABIND_TYPE_INFO</span></tt> must be less-than
3202 comparable!</p>
3203 </dd>
3204 <dt>NDEBUG</dt>
3205 <dd>This define will disable all asserts and should be defined in a release
3206 build.</dd>
3207 </dl>
3208 </div>
3209 <div class="section">
3210 <h1><a id="implementation-notes" name="implementation-notes">16&nbsp;&nbsp;&nbsp;Implementation notes</a></h1>
3211 <p>The classes and objects are implemented as user data in Lua. To make sure that
3212 the user data really is the internal structure it is supposed to be, we tag
3213 their metatables. A user data who's metatable contains a boolean member named
3214 <tt class="docutils literal"><span class="pre">__luabind_classrep</span></tt> is expected to be a class exported by luabind. A user
3215 data who's metatable contains a boolean member named <tt class="docutils literal"><span class="pre">__luabind_class</span></tt> is
3216 expected to be an instantiation of a luabind class.</p>
3217 <p>This means that if you make your own user data and tags its metatable with the
3218 exact same names, you can very easily fool luabind and crash the application.</p>
3219 <p>In the Lua registry, luabind keeps an entry called <tt class="docutils literal"><span class="pre">__luabind_classes</span></tt>. It
3220 should not be removed or overwritten.</p>
3221 <p>In the global table, a variable called <tt class="docutils literal"><span class="pre">super</span></tt> is used every time a
3222 constructor in a lua-class is called. This is to make it easy for that
3223 constructor to call its base class' constructor. So, if you have a global
3224 variable named super it may be overwritten. This is probably not the best
3225 solution, and this restriction may be removed in the future.</p>
3226 <p>Luabind uses two upvalues for functions that it registers. The first is a
3227 userdata containing a list of overloads for the function, the other is a light
3228 userdata with the value 0x1337, this last value is used to identify functions
3229 registered by luabind. It should be virtually impossible to have such a pointer
3230 as secondary upvalue by pure chance. This means, if you are trying to replace
3231 an existing function with a luabind function, luabind will see that the
3232 secondary upvalue isn't the magic id number and replace it. If it can identify
3233 the function to be a luabind function, it won't replace it, but rather add
3234 another overload to it.</p>
3235 <p>Inside the luabind namespace, there's another namespace called detail. This
3236 namespace contains non-public classes and are not supposed to be used directly.</p>
3237 </div>
3238 <div class="section">
3239 <h1><a id="faq" name="faq">17&nbsp;&nbsp;&nbsp;FAQ</a></h1>
3240 <dl class="docutils">
3241 <dt>What's up with __cdecl and __stdcall?</dt>
3242 <dd>If you're having problem with functions
3243 that cannot be converted from <tt class="docutils literal"><span class="pre">void</span> <span class="pre">(__stdcall</span> <span class="pre">*)(int,int)</span></tt> to
3244 <tt class="docutils literal"><span class="pre">void</span> <span class="pre">(__cdecl*)(int,int)</span></tt>. You can change the project settings to make the
3245 compiler generate functions with __cdecl calling conventions. This is
3246 a problem in developer studio.</dd>
3247 <dt>What's wrong with functions taking variable number of arguments?</dt>
3248 <dd>You cannot register a function with ellipses in its signature. Since
3249 ellipses don't preserve type safety, those should be avoided anyway.</dd>
3250 <dt>Internal structure overflow in VC</dt>
3251 <dd>If you, in visual studio, get fatal error C1204: compiler limit :
3252 internal structure overflow. You should try to split that compilation
3253 unit up in smaller ones. See <a class="reference" href="#splitting-up-the-registration">Splitting up the registration</a> and
3254 <a class="reference" href="#splitting-class-registrations">Splitting class registrations</a>.</dd>
3255 <dt>What's wrong with precompiled headers in VC?</dt>
3256 <dd>Visual Studio doesn't like anonymous namespace's in its precompiled
3257 headers. If you encounter this problem you can disable precompiled
3258 headers for the compilation unit (cpp-file) that uses luabind.</dd>
3259 <dt>error C1076: compiler limit - internal heap limit reached in VC</dt>
3260 <dd>In visual studio you will probably hit this error. To fix it you have to
3261 increase the internal heap with a command-line option. We managed to
3262 compile the test suit with /Zm300, but you may need a larger heap then
3263 that.</dd>
3264 <dt>error C1055: compiler limit : out of keys in VC</dt>
3265 <dd>It seems that this error occurs when too many assert() are used in a
3266 program, or more specifically, the __LINE__ macro. It seems to be fixed by
3267 changing /ZI (Program database for edit and continue) to /Zi
3268 (Program database).</dd>
3269 <dt>How come my executable is huge?</dt>
3270 <dd><p class="first">If you're compiling in debug mode, you will probably have a lot of
3271 debug-info and symbols (luabind consists of a lot of functions). Also,
3272 if built in debug mode, no optimizations were applied, luabind relies on
3273 that the compiler is able to inline functions. If you built in release
3274 mode, try running strip on your executable to remove export-symbols,
3275 this will trim down the size.</p>
3276 <p class="last">Our tests suggests that cygwin's gcc produces much bigger executables
3277 compared to gcc on other platforms and other compilers.</p>
3278 </dd>
3279 </dl>
3280 <!-- HUH?! // check the magic number that identifies luabind's functions -->
3281 <dl class="docutils">
3282 <dt>Can I register class templates with luabind?</dt>
3283 <dd><p class="first">Yes you can, but you can only register explicit instantiations of the
3284 class. Because there's no Lua counterpart to C++ templates. For example,
3285 you can register an explicit instantiation of std::vector&lt;&gt; like this:</p>
3286 <pre class="last literal-block">
3287 module(L)
3288 [
3289     class_&lt;std::vector&lt;int&gt; &gt;(&quot;vector&quot;)
3290         .def(constructor&lt;int&gt;)
3291         .def(&quot;push_back&quot;, &amp;std::vector&lt;int&gt;::push_back)
3292 ];
3293 </pre>
3294 </dd>
3295 </dl>
3296 <!-- Again, irrelevant to docs: Note that the space between the two > is required by C++. -->
3297 <dl class="docutils">
3298 <dt>Do I have to register destructors for my classes?</dt>
3299 <dd><p class="first">No, the destructor of a class is always called by luabind when an
3300 object is collected. Note that Lua has to own the object to collect it.
3301 If you pass it to C++ and gives up ownership (with adopt policy) it will
3302 no longer be owned by Lua, and not collected.</p>
3303 <p class="last">If you have a class hierarchy, you should make the destructor virtual if
3304 you want to be sure that the correct destructor is called (this apply to C++
3305 in general).</p>
3306 </dd>
3307 </dl>
3308 <!-- And again, the above is irrelevant to docs. This isn't a general C++ FAQ. But it saves us support questions. -->
3309 <dl class="docutils">
3310 <dt>Fatal Error C1063 compiler limit : compiler stack overflow in VC</dt>
3311 <dd>VC6.5 chokes on warnings, if you are getting alot of warnings from your
3312 code try suppressing them with a pragma directive, this should solve the
3313 problem.</dd>
3314 <dt>Crashes when linking against luabind as a dll in Windows</dt>
3315 <dd>When you build luabind, Lua and you project, make sure you link against
3316 the runtime dynamically (as a dll).</dd>
3317 <dt>I cannot register a function with a non-const parameter</dt>
3318 <dd>This is because there is no way to get a reference to a Lua value. Have
3319 a look at <a class="reference" href="#out-value">out_value</a> and <a class="reference" href="#pure-out-value">pure_out_value</a> policies.</dd>
3320 </dl>
3321 </div>
3322 <div class="section">
3323 <h1><a id="known-issues" name="known-issues">18&nbsp;&nbsp;&nbsp;Known issues</a></h1>
3324 <ul class="simple">
3325 <li>You cannot use strings with extra nulls in them as member names that refers
3326 to C++ members.</li>
3327 <li>If one class registers two functions with the same name and the same
3328 signature, there's currently no error. The last registered function will
3329 be the one that's used.</li>
3330 <li>In VC7, classes can not be called test.</li>
3331 <li>If you register a function and later rename it, error messages will use the
3332 original function name.</li>
3333 <li>luabind does not support class hierarchies with virtual inheritance. Casts are
3334 done with static pointer offsets.</li>
3335 </ul>
3336 </div>
3337 <div class="section">
3338 <h1><a id="acknowledgments" name="acknowledgments">19&nbsp;&nbsp;&nbsp;Acknowledgments</a></h1>
3339 <p>Written by Daniel Wallin and Arvid Norberg. © Copyright 2003.
3340 All rights reserved.</p>
3341 <p>Evan Wies has contributed with thorough testing, countless bug reports
3342 and feature ideas.</p>
3343 <p>This library was highly inspired by Dave Abrahams' <a class="reference" href="http://www.boost.org/libraries/python">Boost.Python</a> library.</p>
3344 </div>
3345 </div>
3346 </body>
3347 </html>