?login_element?

Subversion Repositories NedoOS

Rev

Blame | Last modification | View Log | Download

  1. <!doctype html>
  2. <html>
  3. <head>
  4. <title>LuaBridge 2.8 Reference Manual</title>
  5. <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
  6.  
  7. <!--=========================================================================-->
  8. <style TYPE="text/css">
  9.  
  10. body {
  11.   color: #000000 ;
  12.   background-color: #FFFFFF ;
  13.   font-family: Helvetica, Arial, sans-serif ;
  14.   text-align: justify ;
  15.   margin-right: 30px ;
  16.   margin-left: 30px ;
  17. }
  18.  
  19. h1, h2, h3, h4 {
  20.   font-family: Verdana, Geneva, sans-serif ;
  21.   font-weight: normal ;
  22.   font-style: normal ;
  23. }
  24.  
  25. h1 {
  26.   padding-top: 0.4em ;
  27.   padding-bottom: 0.4em ;
  28.   padding-left: 24px ;
  29.   margin-left: -24px ;
  30.   background-color: #ffe668 ;
  31.   border-radius: 8px ;
  32. }
  33.  
  34. h2 {
  35.   padding-top: 0.4em ;
  36.   padding-bottom: 0.4em ;
  37.   padding-left: 1em ;
  38.   padding-right: 1em ;
  39.   background-color: #ffe668 ;
  40.   border-radius: 8px ;
  41. }
  42.  
  43. h3 {
  44.   padding-left: 0.5em ;
  45.   border-left: solid #ffe668 1em ;
  46. }
  47.  
  48. a:link {
  49.   color: #8d5c00 ;
  50.   background-color: inherit ;
  51.   text-decoration: none ;
  52. }
  53.  
  54. a:visited {
  55.   color: #b17b26;
  56.   background-color: inherit ;
  57.   text-decoration: none ;
  58. }
  59.  
  60. a:link:hover, a:visited:hover {
  61.   color: #8d5c00 ;
  62.   background-color: #ffe668 ;
  63. }
  64.  
  65. a:link:active, a:visited:active {
  66.   color: inherit;
  67. }
  68.  
  69. hr {
  70.   border: 0 ;
  71.   height: 1px ;
  72.   color: #a0a0a0 ;
  73.   background-color: #a0a0a0 ;
  74. }
  75.  
  76. :target {
  77.   background-color: #F8F8F8 ;
  78.   padding-top: 2px ;
  79.   padding-bottom: 2px ;
  80.   padding-left: 8px;
  81.   padding-right: 8px;
  82.   border: solid #a0a0a0 2px ;
  83. }
  84.  
  85. .footer {
  86.   color: gray ;
  87.   font-size: small ;
  88. }
  89.  
  90. ul {
  91.   list-style-type: none ;
  92.   list-style-position: outside ;
  93. }
  94.  
  95. ul.bullets {
  96.   list-style-type: disc ;
  97. }
  98.  
  99. img {
  100.   border: 0;
  101. }
  102.  
  103. table {
  104.   margin-left: 2em;
  105. }
  106.  
  107. pre, code {
  108.   font-size: 12pt ;
  109. }
  110.  
  111. pre {
  112.   margin-left: 2em;
  113. }
  114.  
  115. pre.split {
  116.   padding-left: 2em;
  117.   display: table-cell ;
  118.   white-space: pre-wrap ;
  119.   vertical-align: text-top ;
  120.   padding-right: 2em;
  121. }
  122.  
  123. pre.split + pre.split {
  124.   border-left: 1px solid #ccc;
  125. }
  126.  
  127. </style>
  128.  
  129. </head>
  130.  
  131. <!--=========================================================================-->
  132.  
  133. <body>
  134.  
  135. <header>
  136. <hr>
  137. <h1>LuaBridge 2.8 Reference Manual</h1>
  138. <hr>
  139. </header>
  140.  
  141. <small>
  142. Official repository is located at
  143. <a href="https://github.com/vinniefalco/LuaBridge">https://github.com/vinniefalco/LuaBridge</a>.
  144. <br>
  145. Copyright &copy; 2012 Vinnie Falco. Freely available under the terms of the
  146. <a href="http://www.opensource.org/licenses/mit-license.html">MIT License</a>.
  147. </small>
  148.  
  149. <nav>
  150. <h2>Contents</h2>
  151. <UL id="toc" style="padding: 0">
  152. <li><A href="#s1">1 - Introduction</A>
  153. <ul>
  154.   <li><A href="#s1.1">1.1 - Design</A>
  155.   <li><A href="#s1.2">1.2 - Repository</A>
  156.   <li><A href="#s1.3">1.3 - License and Credits</A>
  157. </ul>
  158. <p>
  159. <li><A href="#s2">2 - Accessing C++ from Lua</A>
  160. <ul>
  161.   <li><A href="#s2.1">2.1 - Namespaces</A>
  162.   <li><A href="#s2.2">2.2 - Data, Properties, Functions, and CFunctions</A>
  163.   <li><A href="#s2.3">2.3 - Class Objects</A>
  164.   <li><A href="#s2.4">2.4 - Property Member Proxies</A>
  165.   <li><A href="#s2.5">2.5 - Function Member Proxies</A>
  166.   <li><A href="#s2.6">2.6 - Constructors</A>
  167.   <li><A href="#s2.7">2.7 - Lua Stack</A>
  168.   <li><A href="#s2.8">2.8 - lua_State</A>
  169. </ul>
  170. <p>
  171. <li><A href="#s3">3 - Passing Objects</A>
  172. <ul>
  173.   <li><A href="#s3.1">3.1 - C++ Lifetime</A>
  174.   <li><A href="#s3.2">3.2 - Lua Lifetime</A>
  175.   <li><A href="#s3.3">3.3 - Pointers, References, and Pass by Value</A>
  176.   <li><A href="#s3.4">3.4 - Shared Lifetime</A>
  177.   <ul>
  178.     <li><A href="#s3.4.1">3.4.1 - Class RefCountedObjectPtr</A>
  179.     <li><A href="#s3.4.2">3.4.2 - Class RefCountedPtr</A>
  180.     <li><A href="#s3.4.3">3.4.3 - User-defined Containers</A>
  181.     <li><A href="#s3.4.4">3.4.4 - Container Constructors</A>
  182.   </ul>
  183.   <li><A href="#s3.5">3.5 - Mixing Lifetimes</A>
  184.   <li><A href="#s3.6">3.6 - Convenience Functions</A>
  185. </ul>
  186. <p>
  187. <li><A href="#s4">4 - Accessing Lua from C++</A>
  188. <ul>
  189.   <li><A href="#s4.1">4.1 - Class LuaRef</A>
  190.   <ul>
  191.     <li><A href="#s4.1.1">4.1.1 - Type Conversions</A>
  192.     <li><A href="#s4.1.2">4.1.2 - Visual Studio 2010, 2012</A>
  193.   </ul>
  194.   <li><A href="#s4.2">4.2 - Table Proxies</A>
  195.   <li><A href="#s4.3">4.3 - Calling Lua</A>
  196.   <ul>
  197.     <li><A href="#s4.3.1">4.3.1 - Class LuaException</A>
  198.   </ul>
  199. </ul>
  200. <p>
  201. <li><A href="#s5">5 - Security</A>
  202. <p>
  203. <li><a href="#appendix">Appendix - API Reference</a>
  204. </ul>
  205. </nav>
  206.  
  207. <!--========================================================================-->
  208.  
  209. <section>
  210.  
  211. <h1>1 - <span id="s1">Introduction</span></h1>
  212.  
  213. <p>
  214. <a href="https://github.com/vinniefalco/LuaBridge">LuaBridge</a> is a
  215. lightweight and dependency-free library for mapping data, functions, and
  216. classes back and forth between C++ and <a href="http://wwww.lua.org">Lua</a>,
  217. a powerful, fast, lightweight, embeddable scripting language. LuaBridge has
  218. been tested and works with Lua revisions starting from 5.1.5, although it
  219. should work in any version of Lua from 5.1.0 and later. It also works
  220. transparently with <a href="http://luajit.org/">LuaJIT</a>.
  221. </p>
  222.  
  223. <p>
  224. LuaBridge offers the following features:
  225. </p>
  226.  
  227. <ul class="bullets" title="Features">
  228. <li><a href="http://www.opensource.org/licenses/mit-license.html">MIT Licensed</a>, no usage restrictions!</li>
  229. <li>Headers-only: No Makefile, no .cpp files, just one <code>#include</code>!</li>
  230. <li>Simple, light, and nothing else needed (like Boost).</li>
  231. <li>No macros, settings, or configuration scripts needed.</li>
  232. <li>Supports different object lifetime management models.</li>
  233. <li>Convenient, type-safe access to the Lua stack.</li>
  234. <li>Automatic function parameter type binding.</li>
  235. <li>Easy access to Lua objects like tables and functions.</li>
  236. <li>Written in a clear and easy to debug style.</li>
  237. <li>C++11 compliant.</li>
  238. </ul>
  239.  
  240. <p>
  241. LuaBridge is distributed as a a collection of header files. You simply add
  242. one line, <code>#include "LuaBridge/LuaBridge.h"</code> where you want to
  243. pass functions, classes, and variables back and forth between C++ and Lua.
  244. There are no additional source files, no compilation settings, and no
  245. Makefiles or IDE-specific project files. LuaBridge is easy to integrate.
  246. </p>
  247.  
  248. <p>
  249. C++ concepts like variables and classes are made available to Lua through a
  250. process called <em>registration</em>. Because Lua is weakly typed, the resulting
  251. structure is not rigid. The API is based on C++ template metaprogramming. It
  252. contains template code to automatically generate at compile-time the various
  253. Lua C API calls necessary to export your program's classes and functions to
  254. the Lua environment.
  255. </p>
  256.  
  257. <p>
  258. To expose Lua objects to C++, a class called <code>LuaRef</code> is provided.
  259. The implementation allows C++ code to access Lua objects such as numbers
  260. or strings, but more importantly to access things like tables and their
  261. values. Using this class makes idioms like calling Lua functions simple
  262. and clean.
  263. </p>
  264.  
  265. <!--========================================================================-->
  266.  
  267. <section>
  268.  
  269. <h2>1.1 - <span id="s1.1">Design</span></h2>
  270.  
  271. <p>
  272. LuaBridge tries to be efficient as possible when creating the "glue" that
  273. exposes C++ data and functions to Lua. At the same time, the code was
  274. written with the intention that it is all as simple and clear as possible,
  275. without resorting to obscure C++ idioms, ugly preprocessor macros, or
  276. configuration settings. Furthermore, it is designed to be "header-only",
  277. making it very easy to integrate into your projects.
  278. </p>
  279.  
  280. <p>
  281. Because LuaBridge was written with simplicity in mind there are some features
  282. that are not available. Although it comes close to the highest possible
  283. performance, LuaBridge is not quite the fastest,
  284. <a href="http://code.google.com/p/oolua/">OOLua</a> slightly outperforms
  285. LuaBridge in some tests. LuaBridge also does not try to implement every
  286. possible feature,
  287. <a href="http://www.rasterbar.com/products/luabind.html">LuaBind</a>
  288. explores every corner of the C++ language (but it requires Boost).
  289. </p>
  290.  
  291. <p>
  292. LuaBridge does not support:
  293. </p>
  294.  
  295. <ul class="bullets">
  296. <li>Enumerated constants
  297. <li>More than 8 parameters on a function or method (although this can be
  298.    increased by adding more <code>TypeListValues</code> specializations).
  299. <li>Overloaded functions, methods, or constructors.
  300. <li>Global variables (variables must be wrapped in a named scope).
  301. <li>Automatic conversion between STL container types and Lua tables
  302.    (conversion can be enabled for <code>std::list</code>, <code>std::vector</code>,
  303.    <code>std::array</code>, <code>std::map</code>, <code>std::unordered_map</code>
  304.    or <code>std::optional</code> by including <code>List.h</code>,
  305.    <code>Vector.h</code>, <code>Array.h</code>, <code>Map.h</code>,
  306.    <code>UnorderedMap.h</code> or <code>Optional.h</code> respectively)
  307. <li>Inheriting Lua classes from C++ classes.
  308. <li>Passing nil to a C++ function that expects a pointer or reference.
  309. <li>Standard containers like <code>std::shared_ptr</code>.
  310. </ul>
  311.  
  312. </section>
  313.  
  314. <!--========================================================================-->
  315.  
  316. <section>
  317.  
  318. <h2>1.2 - <span id="s1.2">Repository</span></h2>
  319.  
  320. <p>
  321. The official repository is located at
  322. <a href="https://github.com/vinniefalco/LuaBridge">https://github.com/vinniefalco/LuaBridge</a>.
  323. </p>
  324.  
  325. <p>
  326. The <b>master</b> branch contains published library versions. Release versions are marked with tags.
  327. </p>
  328.  
  329. <p>
  330. These repositories are also available:
  331. </p>
  332.  
  333. <table>
  334. <tr>
  335.  <td><b><a href="https://github.com/vinniefalco/LuaBridgeUnitTests">LuaBridgeUnitTests</a></b></td>
  336.  <td>A stand alone command line application to exercise LuaBridge functionality.</td>
  337. </tr>
  338. <tr>
  339.  <td><b><a href="https://github.com/vinniefalco/LuaBridgeDemo">LuaBridgeUnitDemo</a></b></td>
  340.  <td>A stand alone GUI application that provides an interactive console.</td>
  341. </tr>
  342. </table>
  343.  
  344. </section>
  345.  
  346. <!--========================================================================-->
  347.  
  348. <section>
  349.  
  350. <h2>1.3 - <span id="s1.3">License and Credits</span></h2>
  351.  
  352. <p>
  353. LuaBridge is published under the terms of the
  354. <a href="http://www.opensource.org/licenses/mit-license.html">MIT License</a>:
  355. </p>
  356.  
  357. <pre>
  358. Permission is hereby granted, free of charge, to any person obtaining a copy
  359. of this software and associated documentation files (the "Software"), to deal
  360. in the Software without restriction, including without limitation the rights
  361. to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  362. copies of the Software, and to permit persons to whom the Software is
  363. furnished to do so, subject to the following conditions:
  364.  
  365. The above copyright notice and this permission notice shall be included in
  366. all copies or substantial portions of the Software.
  367.  
  368. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  369. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  370. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  371. AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  372. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  373. OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  374. SOFTWARE.
  375. </pre>
  376.  
  377. <p>
  378. The original version of LuaBridge was written by Nathan Reed. The project
  379. has been taken over by Vinnie Falco, who added new functionality and wrote
  380. the new documentation. Vinnie also incorporated <code>LuaRef</code> and
  381. other Lua to C++ binding contributions from Nigel Atkinson.
  382. </p>
  383.  
  384. <p>
  385. For questions, comments, or bug reports feel free to open a Github issue
  386. or contact Vinnie Falco directly at the email address indicated below.
  387. </p>
  388.  
  389. <ul>
  390. <li>Copyright 2019, Dmitry Tarakanov</li>
  391. <li>Copyright 2012, Vinnie Falco <a href="mailto:vinnie.falco@gmail.com">&lt;vinnie.falco@gmail.com&gt;</a>
  392. <li>Copyright 2008, Nigel Atkinson <a href="mailto:suprapilot+LuaCode@gmail.com">&lt;suprapilot+LuaCode@gmail.com&gt;</a>
  393. <li>Copyright 2007, Nathan Reed
  394. <li>Portions from The Loki Library: Copyright 2001 by Andrei Alexandrescu
  395. </ul>
  396.  
  397. <p>
  398. Older versions of LuaBridge up to and including 0.2 (available separately) are
  399. distributed under the BSD 3-Clause License. See the corresponding license file
  400. in those versions (distributed separately) for more details.
  401. </p>
  402.  
  403. </section>
  404.  
  405. <!--========================================================================-->
  406.  
  407. </section>
  408.  
  409. <section>
  410.  
  411. <h1>2 - <span id="s2">Accessing C++ from Lua</span></h1>
  412.  
  413. <p>
  414. In order to expose C++ data and functions to Lua, each piece of exported
  415. information must be <em>registered</em>. There are five types of objects that
  416. LuaBridge can register:
  417. </p>
  418.  
  419. <table>
  420. <tr>
  421.  <td><b>Namespaces</b>&nbsp;&nbsp;</td>
  422.  <td>A Lua table that contains other registrations.</td>
  423. </tr>
  424. <tr>
  425.  <td><b>Data</b>&nbsp;&nbsp;</td>
  426.  <td>Global or static variables, data members, and static data members.</td>
  427. </tr>
  428. <tr>
  429.  <td><b>Functions&nbsp;&nbsp;</b></td>
  430.  <td>Regular functions, member functions, and static member functions.</td>
  431. </tr>
  432. <tr>
  433.  <td><b>CFunctions&nbsp;&nbsp;</b></td>
  434.  <td>A regular function, member function, or static member function that
  435.      uses the <code>lua_CFunction</code> calling convention.</td>
  436. </tr>
  437. <tr>
  438.  <td><b>Properties&nbsp;&nbsp;</b></td>
  439.  <td>Global properties, property members, and static property members.
  440.      These appear like data to Lua, but are implemented in C++ using
  441.      functions to get and set the values.</td>
  442.  </tr>
  443. </table>
  444.  
  445. <p>
  446. Both data and properties can be marked as <em>read-only</em> at the time of
  447. registration. This is different from <code>const</code>; the values of these
  448. objects can be modified on the C++ side, but Lua scripts cannot change them.
  449. Code samples that follow are in C++ or Lua, depending on context. For brevity
  450. of exposition code samples in C++ assume the traditional variable
  451. <code>lua_State* L</code> is defined, and that a <code>using namespace luabridge</code>
  452. using-directive is in effect.
  453. </p>
  454.  
  455. <!--========================================================================-->
  456.  
  457. <section>
  458.  
  459. <h2>2.1 - <span id="s2.1">Namespaces</span></h2>
  460.  
  461. <p>
  462. All LuaBridge registrations take place in a <em>namespace</em>. When we refer
  463. to a <em>namespace</em> we are always talking about a namespace in the Lua
  464. sense, which is implemented using tables. The namespace need not correspond
  465. to a C++ namespace; in fact no C++ namespaces need to exist at all unless you
  466. want them to. LuaBridge namespaces are visible only to Lua scripts; they are
  467. used as a logical grouping tool. To obtain access to the global namespace
  468. we write:
  469. </p>
  470.  
  471. <pre>
  472. getGlobalNamespace (L);
  473. </pre>
  474.  
  475. <p>
  476. This returns an object on which further registrations can be performed. The
  477. subsequent registrations will go into the global namespace, a practice which
  478. is not recommended. Instead, we can add our own namespace by writing:
  479. </p>
  480.  
  481. <pre>
  482. getGlobalNamespace (L)
  483.  .beginNamespace ("test");
  484. </pre>
  485.  
  486. <p>
  487. This creates a table in <code>_G</code> called "test". Since we have not
  488. performed any registrations, this table will be empty except for some
  489. bookkeeping key/value pairs. LuaBridge reserves all identifiers that start
  490. with a double underscore. So <code>__test</code> would be an invalid name
  491. (although LuaBridge will silently accept it). Functions like
  492. <code>beginNamespace</code> return the corresponding object on which we can
  493. make more registrations. Given:
  494. </p>
  495.  
  496. <pre>
  497. getGlobalNamespace (L)
  498.  .beginNamespace ("test")
  499.    .beginNamespace ("detail")
  500.    .endNamespace ()
  501.    .beginNamespace ("utility")
  502.    .endNamespace ()
  503.  .endNamespace ();
  504. </pre>
  505.  
  506. <p>
  507. The results are accessible to Lua as <code>test</code>, <code>test.detail</code>,
  508. and <code>test.utility</code>. Here we introduce the <code>endNamespace</code>
  509. function; it returns an object representing the original enclosing namespace.
  510. All LuaBridge functions which  create registrations return an object upon which
  511. subsequent registrations can be made, allowing for an unlimited number of
  512. registrations to be chained together using the dot operator. Adding two objects
  513. with the same name, in the same namespace, results in undefined behavior
  514. (although LuaBridge will silently accept it).
  515. </p>
  516.  
  517. <p>
  518. A namespace can be re-opened later to add more functions. This lets you split
  519. up the registration between different source files. These are equivalent:
  520. </p>
  521.  
  522. <pre>
  523. getGlobalNamespace (L)
  524.  .beginNamespace ("test")
  525.    .addFunction ("foo", foo)
  526.  .endNamespace ();
  527.  
  528. getGlobalNamespace (L)
  529.  .beginNamespace ("test")
  530.    .addFunction ("bar", bar)
  531.  .endNamespace ();
  532. </pre>
  533.  
  534. <p>
  535. and
  536. </p>
  537.  
  538. <pre>
  539. getGlobalNamespace (L)
  540.  .beginNamespace ("test")
  541.    .addFunction ("foo", foo)
  542.    .addFunction ("bar", bar)
  543.  .endNamespace ();
  544. </pre>
  545.  
  546. </section>
  547.  
  548. <!--========================================================================-->
  549.  
  550. <section>
  551.  
  552. <h2>2.2 - <span id="s2.2">Properties and Functions</span></h2>
  553.  
  554. <p>
  555. These are registered into a namespace using <code>addProperty</code>
  556. and <code>addFunction</code>.
  557. When registered functions are called by scripts, LuaBridge automatically takes
  558. care of the conversion of arguments into the appropriate data type when doing
  559. so is possible. This automated system works for the function's return value,
  560. and up to 8 parameters although more can be added by extending the templates.
  561. Pointers, references, and objects of class type as parameters are treated
  562. specially, and explained later.
  563. </p>
  564. <p>
  565. If we have:
  566. </p>
  567.  
  568. <pre>
  569. int globalVar;
  570. static float staticVar;
  571.  
  572. std::string stringProperty;
  573. std::string getString () { return stringProperty; }
  574. void setString (std::string s) { stringProperty = s; }
  575.  
  576. int foo () { return 42; }
  577. void bar (char const*) { }
  578. int cFunc (lua_State* L) { return 0; }
  579. </pre>
  580.  
  581. <p>
  582. These are registered with:
  583. </p>
  584.  
  585. <pre>
  586. getGlobalNamespace (L)
  587.   .beginNamespace ("test")
  588.     .addProperty ("var1", &amp;globalVar)
  589.     .addProperty ("var2", &amp;staticVar, false) // read-only
  590.     .addProperty ("prop1", getString, setString)
  591.     .addProperty ("prop2", getString)            // read only
  592.     .addFunction ("foo", foo)
  593.     .addFunction ("bar", bar)
  594.     .addFunction ("cfunc", cFunc)
  595.   .endNamespace ();
  596. </pre>
  597.  
  598. <p>
  599. Variables can be marked <em>read-only</em> by passing <code>false</code> in
  600. the second optional parameter. If the parameter is omitted, <em>true</em> is
  601. used making the variable read/write. Properties are marked read-only by
  602. omitting the set function. After the registrations above, the following Lua
  603. identifiers are valid:
  604. </p>
  605.  
  606. <pre>
  607. test        -- a namespace
  608. test.var1   -- a lua_Number property
  609. test.var2   -- a read-only lua_Number property
  610. test.prop1  -- a lua_String property
  611. test.prop2  -- a read-only lua_String property
  612. test.foo    -- a function returning a lua_Number
  613. test.bar    -- a function taking a lua_String as a parameter
  614. test.cfunc  -- a function with a variable argument list and multi-return
  615. </pre>
  616.  
  617. <p>
  618. Note that <code>test.prop1</code> and <code>test.prop2</code> both refer to the
  619. same value. However, since <code>test.prop2</code> is read-only, assignment
  620. attempts will generate a run-time error. These Lua statements have the stated effects:
  621. </p>
  622.  
  623. <pre>
  624. test.var1 = 5         -- okay
  625. test.var2 = 6         -- error: var2 is not writable
  626. test.prop1 = "Hello"  -- okay
  627. test.prop1 = 68       -- okay, Lua converts the number to a string
  628. test.prop2 = "bar"    -- error: prop2 is not writable
  629.  
  630. test.foo ()           -- calls foo and discards the return value
  631. test.var1 = foo ()    -- calls foo and stores the result in var1
  632. test.bar ("Employee") -- calls bar with a string
  633. test.bar (test)       -- error: bar expects a string not a table
  634. </pre>
  635.  
  636. <p>
  637. LuaBridge does not support overloaded functions nor is it likely to in the
  638. future. Since Lua is dynamically typed, any system that tries to resolve a set
  639. of parameters passed from a script will face considerable ambiguity when
  640. trying to choose an appropriately matching C++ function signature.
  641. </p>
  642.  
  643. </section>
  644.  
  645. <!--========================================================================-->
  646.  
  647. <section>
  648.  
  649. <h2>2.3 - <span id="s2.3">Class Objects</span></h2>
  650.  
  651. <p>
  652. A class registration is opened using either <code>beginClass</code> or
  653. <code>deriveClass</code> and ended using <code>endClass</code>. Once
  654. registered, a class can later be re-opened for more registrations using
  655. <code>beginClass</code>. However, <code>deriveClass</code> should only be
  656. used once. To add more registrations to an already registered derived class,
  657. use <code>beginClass</code> on it.
  658. </p>
  659. <p>
  660. These declarations:
  661. </p>
  662.  
  663. <pre>
  664. struct A {
  665.   static int staticData;
  666.   static float staticProperty;
  667.  
  668.   static float getStaticProperty () { return staticProperty; }
  669.   static void setStaticProperty (float f) { staticProperty = f; }
  670.   static void staticFunc () { }
  671.  
  672.   static int staticCFunc (lua_State *L) { return 0; }
  673.  
  674.   std::string dataMember;
  675.  
  676.   char dataProperty;
  677.   char getProperty () const { return dataProperty; }
  678.   void setProperty (char v) { dataProperty = v; }
  679.   std::string toString () const { return dataMember; }
  680.  
  681.   void func1 () { }
  682.   virtual void virtualFunc () { }
  683.  
  684.   int cfunc (lua_State* L) { return 0; }
  685. };
  686.  
  687. struct B : public A {
  688.   double dataMember2;
  689.  
  690.   void func1 () { }
  691.   void func2 () { }
  692.   void virtualFunc () { }
  693. };
  694.  
  695. int A::staticData;
  696. float A::staticProperty;
  697. </pre>
  698.  
  699. <p>
  700. are registered using:
  701. </p>
  702.  
  703. <pre>
  704. getGlobalNamespace (L)
  705.   .beginNamespace ("test")
  706.     .beginClass &lt;A&gt; ("A")
  707.       .addStaticProperty ("staticData", &amp;A::staticData)
  708.       .addStaticProperty ("staticProperty", &amp;A::getStaticProperty, &amp;A::setStaticProperty)
  709.       .addStaticFunction ("staticFunc", &amp;A::staticFunc)
  710.       .addStaticFunction ("staticCFunc", &amp;A::staticCFunc)
  711.       .addProperty ("data", &amp;A::dataMember)
  712.       .addProperty ("prop", &amp;A::getProperty, &amp;A::setProperty)
  713.       .addFunction ("func1", &amp;A::func1)
  714.       .addFunction ("virtualFunc", &amp;A::virtualFunc)
  715.       .addFunction ("__tostring", &amp;A::toString)     // Metamethod
  716.       .addFunction ("cfunc", &amp;A::cfunc)
  717.     .endClass ()
  718.     .deriveClass &lt;B, A&gt; ("B")
  719.       .addProperty ("data", &amp;B::dataMember2)
  720.       .addFunction ("func1", &amp;B::func1)
  721.       .addFunction ("func2", &amp;B::func2)
  722.     .endClass ()
  723.   .endNameSpace ();
  724. </pre>
  725.  
  726. <p>
  727. Method registration works just like function registration.  Virtual methods
  728. work normally; no special syntax is needed. const methods are detected and
  729. const-correctness is enforced, so if a function returns a const object (or
  730. a container holding to a const object) to Lua, that reference to the object
  731. will be considered const and only const methods can be called on it.
  732. It is possible to register Lua metamethods (except <code>__gc</code>).
  733. Destructors are registered automatically for each class.
  734. </p>
  735.  
  736. <p>
  737. As with regular variables and properties, class properties can be
  738. marked read-only by passing false in the second parameter, or omitting the set
  739. set function. The <code>deriveClass</code> takes two template arguments: the
  740. class to be registered, and its base class.  Inherited methods do not have to
  741. be re-declared and will function normally in Lua. If a class has a base class
  742. that is **not** registered with Lua, there is no need to declare it as a
  743. subclass.
  744. </p>
  745.  
  746. <p>
  747. Remember that in Lua, the colon operator '<code>:</code>' is used for
  748. method call syntax:
  749. </p>
  750.  
  751. <pre>
  752. local a = A ()
  753.  
  754. a.func1 ()  -- error: func1 expects an object of a registered class
  755. a.func1 (a) -- okay, verbose, this how OOP works in Lua
  756. a:func1 ()  -- okay, less verbose, equvalent to the previous
  757. </pre>
  758.  
  759. </section>
  760.  
  761. <!--========================================================================-->
  762.  
  763. <section>
  764.  
  765. <h2>2.4 - <span id="s2.4">Property Member Proxies</span></h2>
  766.  
  767. <p>
  768. Sometimes when registering a class which comes from a third party library, the
  769. data is not exposed in a way that can be expressed as a pointer to member,
  770. there are no get or set functions, or the get and set functons do not have the
  771. right function signature. Since the class declaration is closed for changes,
  772. LuaBridge allows for a <em>property member proxy</em>. This is a pair of get
  773. and set flat functions which take as their first parameter a pointer to
  774. the object. This is easily understood with the following example:
  775. </p>
  776.  
  777. <pre>
  778. // Third party declaration, can't be changed
  779. struct Vec
  780. {
  781.  float coord [3];
  782. };
  783. </pre>
  784.  
  785. <p>
  786. Taking the address of an array element, e.g. <code>&amp;Vec::coord [0]</code>
  787. results in an error instead of a pointer-to-member. The class is closed for
  788. modifications, but we want to export Vec objects to Lua using the familiar
  789. object notation. To do this, first we add a "helper" class:
  790. </p>
  791.  
  792. <pre>
  793. struct VecHelper
  794. {
  795.  template &lt;unsigned index&gt;
  796.  static float get (Vec const* vec)
  797.  {
  798.    return vec->coord [index];
  799.  }
  800.  
  801.  template &lt;unsigned index&gt;
  802.  static void set (Vec* vec, float value)
  803.  {
  804.    vec->coord [index] = value;
  805.  }
  806. };
  807. </pre>
  808.  
  809. <p>
  810. This helper class is only used to provide property member proxies.
  811. <code>Vec</code> continues to be used in the C++ code as it was before.
  812. Now we can register the <code>Vec</code> class with property member proxies for
  813. <code>x</code>, <code>y</code>, and <code>z</code>:
  814. </p>
  815.  
  816. <pre>
  817. getGlobalNamespace (L)
  818.  .beginNamespace ("test")
  819.    .beginClass &lt;Vec&gt; ("Vec")
  820.      .addProperty ("x", &amp;VecHelper::get &lt;0&gt;, &amp;VecHelper::set &lt;0&gt;)
  821.      .addProperty ("y", &amp;VecHelper::get &lt;1&gt;, &amp;VecHelper::set &lt;1&gt;)
  822.      .addProperty ("z", &amp;VecHelper::get &lt;2&gt;, &amp;VecHelper::set &lt;2&gt;)
  823.    .endClass ()
  824.  .endNamespace ();
  825. </pre>
  826.  
  827. <p>
  828. It is also possible to use <code>std::function &lt;&gt;</code> instances as proxies:
  829. </p>
  830.  
  831. <pre>
  832. getGlobalNamespace (L)
  833.  .beginNamespace ("test")
  834.    .beginClass &lt;Vec&gt; ("Vec")
  835.      .addProperty ("x",
  836.        std::function &lt;float (const Vec*)&gt; (
  837.          [] (const Vec* vec) {return vec->coord [0];}),
  838.        std::function &lt;void (Vec*, float)&gt; (
  839.          [] (Vec* vec, float v) {vec->coord [0] = v;}))
  840.      // ... same for "y" and "z"
  841.    .endClass ()
  842.  .endNamespace ();
  843. </pre>
  844.  
  845. </section>
  846.  
  847. <!--========================================================================-->
  848.  
  849. <section>
  850.  
  851. <h2>2.5 - <span id="s2.5">Function Member Proxies</span></h2>
  852.  
  853. <p>
  854. Where it is not possible or inconvenient to add a member to be registered,
  855. LuaBridge also allows for a <em>function member proxy</em>. This is a flat
  856. function which take as its first parameter a pointer to the object:
  857. </p>
  858.  
  859. <pre>
  860. // Third party declaration, can't be changed
  861. struct Vec
  862. {
  863.   float coord [3];
  864. };
  865. </pre>
  866.  
  867. <p>
  868. The class is closed for modifications, but we want to extend Vec objects
  869. with our member function. To do this, first we add a "helper" function:
  870. </p>
  871.  
  872. <pre>
  873. void scale (float value)
  874. {
  875.   value->coord [0] *= value;
  876.   value->coord [1] *= value;
  877.   value->coord [2] *= value;
  878. };
  879. </pre>
  880.  
  881. <p>
  882. Now we can register the <code>Vec</code> class with a member function
  883. <code>scale</code>:
  884. </p>
  885.  
  886. <pre>
  887. getGlobalNamespace (L)
  888.   .beginNamespace ("test")
  889.     .beginClass &lt;Vec&gt; ("Vec")
  890.       .addFunction ("scale", &amp;scale)
  891.     .endClass ()
  892.   .endNamespace ();
  893. </pre>
  894.  
  895. <p>
  896. It is also possible to use <code>std::function &lt;&gt;</code> instances as proxies:
  897. </p>
  898.  
  899. <pre>
  900. getGlobalNamespace (L)
  901.   .beginClass &lt;Vec&gt; ("Vec")
  902.     .addFunction ("scaleX",
  903.       std::function &lt;void (Vec*, float)&gt; (
  904.         [] (Vec* vec, float v) {vec->coord [0] *= v;}))
  905.   .endClass ()
  906. </pre>
  907.  
  908. </section>
  909.  
  910. <!--========================================================================-->
  911.  
  912. <section>
  913.  
  914. <h2>2.6 - <span id="s2.6">Constructors</span></h2>
  915.  
  916. <p>
  917. A single constructor may be added for a class using <code>addConstructor</code>.
  918. LuaBridge cannot automatically determine the number and types of constructor
  919. parameters like it can for functions and methods, so you must provide them.
  920. This is done by specifying the signature of the desired constructor function
  921. as the first template parameter to <code>addConstructor</code>. The parameter
  922. types will be extracted from this (the return type is ignored).  For example,
  923. these statements register constructors for the given classes:
  924. </p>
  925.  
  926. <pre>
  927. struct A
  928. {
  929.   A ();
  930. };
  931.  
  932. struct B
  933. {
  934.   explicit B (char const* s, int nChars);
  935. };
  936.  
  937. getGlobalNamespace (L)
  938.   .beginNamespace ("test")
  939.     .beginClass &lt;A&gt; ("A")
  940.       .addConstructor &lt;void (*) (void)&gt; ()
  941.     .endClass ()
  942.     .beginClass &lt;B&gt; ("B")
  943.       .addConstructor &lt;void (*) (char const*, int)&gt; ()
  944.     .endClass ()
  945.   .endNamespace ();
  946. </pre>
  947.  
  948. <p>
  949. Constructors added in this fashion are called from Lua using the fully
  950. qualified name of the class. This Lua code will create instances of
  951. <code>A</code> and <code>B</code>.
  952. </p>
  953.  
  954. <pre>
  955. a = test.A ()           -- Create a new A.
  956. b = test.B ("hello", 5) -- Create a new B.
  957. b = test.B ()           -- Error: expected string in argument 1
  958. </pre>
  959.  
  960. </section>
  961.  
  962. <!--========================================================================-->
  963.  
  964. <section>
  965.  
  966. <h2>2.7 - <span id="s2.7">Lua Stack</span></h2>
  967.  
  968. <p>
  969. In the Lua C API, all operations on the <code>lua_State</code> are performed
  970. through the Lua stack. In order to pass values back and forth between C++
  971. and Lua, LuaBridge uses specializations of this template class concept:
  972. </p>
  973.  
  974. <pre>
  975. template &lt;class T&gt;
  976. struct Stack
  977. {
  978.   static void push (lua_State* L, T t);
  979.   static T get (lua_State* L, int index);
  980.   static bool isInstance (lua_State* L, int index);
  981. };
  982. </pre>
  983.  
  984. <p>
  985. When a specialization of <code>Stack</code> exists for a given type
  986. <code>T</code> we say that the <code>T</code> is <em>convertible</em>.
  987. Throughout this document and the LuaBridge API, these types can be used
  988. anywhere a convertible type is expected.
  989. </p>
  990.  
  991. <p>
  992. The Stack template class specializations are used automatically for variables,
  993. properties, data members, property members, function arguments and return
  994. values. These basic types are supported:
  995. </p>
  996.  
  997. <ul class="bullets">
  998. <li><code>bool</code>
  999. <li><code>char</code>, converted to a string of length one.
  1000. <li><code>char const*</code> and <code>std::string</code> strings.
  1001. <li>Integers, <code>float</code>, and <code>double</code>,
  1002.     converted to <code>Lua_number</code>.
  1003. </ul>
  1004.  
  1005. <p>
  1006. User-defined types which are convertible to one of the basic types are
  1007. possible, simply provide a <code>Stack &lt;&gt;</code> specialization in the
  1008. <code>luabridge</code> namespace for your user-defined type, modeled after
  1009. the existing types. For example, here is a specialization for a
  1010. <code>juce::String</code>:
  1011. </p>
  1012.  
  1013. <pre>
  1014. template &lt;&gt;
  1015. struct Stack &lt;juce::String&gt;
  1016. {
  1017.   static void push (lua_State* L, juce::String s)
  1018.   {
  1019.     lua_pushstring (L, s.toUTF8 ());
  1020.   }
  1021.  
  1022.   static juce::String get (lua_State* L, int index)
  1023.   {
  1024.     return juce::String (luaL_checkstring (L, index));
  1025.   }
  1026.  
  1027.   static bool isInstance (lua_State* L, int index)
  1028.   {
  1029.     return lua_type (L, index) == LUA_TSTRING;
  1030.   }
  1031. };
  1032. </pre>
  1033.  
  1034. </section>
  1035.  
  1036. <!--========================================================================-->
  1037.  
  1038. <section>
  1039.  
  1040. <h2>2.8 - <span id="s2.8">lua_State</span></h2>
  1041.  
  1042. <p>
  1043. Sometimes it is convenient from within a bound function or member function
  1044. to gain access to the <code>lua_State*</code> normally available to a </code>lua_CFunction</code>.
  1045. With LuaBridge, all you need to do is add a <code>lua_State*</code> as the last
  1046. parameter of your bound function:
  1047. </p>
  1048.  
  1049. <pre>
  1050. void useState (lua_State* L);
  1051.  
  1052. getGlobalNamespace (L).addFunction ("useState", &amp;useState);
  1053. </pre>
  1054.  
  1055. <p>
  1056. You can still include regular arguments while receiving the state:
  1057. </p>
  1058.  
  1059. <pre>
  1060. void useStateAndArgs (int i, std::string s, lua_State* L);
  1061.  
  1062. getGlobalNamespace (L).addFunction ("useStateAndArgs", &amp;useStateAndArgs);
  1063. </pre>
  1064.  
  1065. <p>
  1066. When the script calls <code>useStateAndArgs</code>, it passes only the integer
  1067. and string parameters. LuaBridge takes care of inserting the <code>lua_State*</code>
  1068. into the argument list for the corresponding C++ function. This will work
  1069. correctly even for the state created by coroutines. Undefined behavior results
  1070. if the <code>lua_State*</code> is not the last parameter.
  1071. </p>
  1072.  
  1073. <p>
  1074. The same is applicable for properies.
  1075. </p>
  1076.  
  1077. </section>
  1078.  
  1079. <!--========================================================================-->
  1080.  
  1081. </section>
  1082.  
  1083. <section>
  1084.  
  1085. <h1>3 - <span id="s3">Passing Objects</span></h1>
  1086.  
  1087. <p>
  1088. An object of a registered class <code>T</code> may be passed to Lua as:
  1089. </p>
  1090.  
  1091. <table>
  1092. <tr>
  1093.   <td><b><code>T</code></b></td>
  1094.   <td>Passed by value (a copy), with <em>Lua lifetime</em>.</td>
  1095. </tr>
  1096. <tr>
  1097.   <td><b><code>T const</code></b></td>
  1098.   <td>Passed by value (a copy), with <em>Lua lifetime</em>.</td>
  1099. </tr>
  1100. <tr>
  1101.   <td><b><code>T*</code></b></td>
  1102.   <td>Passed by reference, with <em>C++ lifetime</em>.</td>
  1103. </tr>
  1104. <tr>
  1105.   <td><b><code>T&amp;</code></b></td>
  1106.   <td>Passed by reference, with <em>C++ lifetime</em>.</td>
  1107. </tr>
  1108. <tr>
  1109.   <td><b><code>T const*</code></b></td>
  1110.   <td>Passed by const reference, with <em>C++ lifetime</em>.</td>
  1111. </tr>
  1112. <tr>
  1113.   <td><b><code>T const&amp;</code></b></td>
  1114.   <td>Passed by const reference, with <em>C++ lifetime</em>.</td>
  1115. </tr>
  1116. </table>
  1117.  
  1118. <!--========================================================================-->
  1119.  
  1120. <section>
  1121.  
  1122. <h2>3.1 - <span id="s3.1">C++ Lifetime</span></h2>
  1123.  
  1124. <p>
  1125. The creation and deletion of objects with <em>C++ lifetime</em> is controlled by
  1126. the C++ code. Lua does nothing when it garbage collects a reference to such an
  1127. object. Specifically, the object's destructor is not called (since C++ owns
  1128. it). Care must be taken to ensure that objects with C++ lifetime are not
  1129. deleted while still being referenced by a <code>lua_State*</code>, or else
  1130. undefined behavior results. In the previous examples, an instance of <code>A</code>
  1131. can be passed to Lua with C++ lifetime, like this:
  1132. </p>
  1133.  
  1134. <pre>
  1135. A a;
  1136.  
  1137. push (L, &amp;a);             // pointer to 'a', C++ lifetime
  1138. lua_setglobal (L, "a");
  1139.  
  1140. push (L, (A const*) &amp;a);   // pointer to 'a const', C++ lifetime
  1141. lua_setglobal (L, "ac");
  1142.  
  1143. push &lt;A const*&gt; (L, &amp;a);  // equivalent to push (L, (A const*) &amp;a)
  1144. lua_setglobal (L, "ac2");
  1145.  
  1146. push (L, new A);          // compiles, but will leak memory
  1147. lua_setglobal (L, "ap");
  1148. </pre>
  1149.  
  1150. </section>
  1151.  
  1152. <!--========================================================================-->
  1153.  
  1154. <section>
  1155.  
  1156. <h2>3.2 - <span id="s3.2">Lua Lifetime</span></h2>
  1157.  
  1158. <p>
  1159. When an object of a registered class is passed by value to Lua, it will have
  1160. <em>Lua lifetime</em>. A copy of the passed object is constructed inside the
  1161. userdata. When Lua has no more references to the object, it becomes eligible
  1162. for garbage collection. When the userdata is collected, the destructor for
  1163. the class will be called on the object. Care must be taken to ensure that
  1164. objects with Lua lifetime are not accessed by C++ after they are garbage
  1165. collected, or else undefined behavior results. An instance of <code>B</code>
  1166. can be passed to Lua with Lua lifetime this way:
  1167. </p>
  1168.  
  1169. <pre>
  1170. B b;
  1171.  
  1172. push (L, b);                    // Copy of b passed, Lua lifetime.
  1173. lua_setglobal (L, "b");
  1174. </pre>
  1175.  
  1176. <p>
  1177. Given the previous code segments, these Lua statements are applicable:
  1178. </p>
  1179.  
  1180. <pre>
  1181. print (test.A.staticData)       -- Prints the static data member.
  1182. print (test.A.staticProperty)   -- Prints the static property member.
  1183. test.A.staticFunc ()            -- Calls the static method.
  1184.  
  1185. print (a.data)                  -- Prints the data member.
  1186. print (a.prop)                  -- Prints the property member.
  1187. a:func1 ()                      -- Calls A::func1 ().
  1188. test.A.func1 (a)                -- Equivalent to a:func1 ().
  1189. test.A.func1 ("hello")          -- Error: "hello" is not a class A.
  1190. a:virtualFunc ()                -- Calls A::virtualFunc ().
  1191.  
  1192. print (b.data)                  -- Prints B::dataMember.
  1193. print (b.prop)                  -- Prints inherited property member.
  1194. b:func1 ()                      -- Calls B::func1 ().
  1195. b:func2 ()                      -- Calls B::func2 ().
  1196. test.B.func2 (a)                -- Error: a is not a class B.
  1197. test.A.func1 (b)                -- Calls A::func1 ().
  1198. b:virtualFunc ()                -- Calls B::virtualFunc ().
  1199. test.B.virtualFunc (b)          -- Calls B::virtualFunc ().
  1200. test.A.virtualFunc (b)          -- Calls B::virtualFunc ().
  1201. test.B.virtualFunc (a)          -- Error: a is not a class B.
  1202.  
  1203. a = nil; collectgarbage ()      -- 'a' still exists in C++.
  1204. b = nil; collectgarbage ()      -- Lua calls ~B() on the copy of b.
  1205. </pre>
  1206.  
  1207. <p>
  1208. When Lua script creates an object of class type using a registered
  1209. constructor, the resulting value will have Lua lifetime. After Lua no longer
  1210. references the object, it becomes eligible for garbage collection. You can
  1211. still pass these to C++, either by reference or by value. If passed by
  1212. reference, the usual warnings apply about accessing the reference later,
  1213. after it has been garbage collected.
  1214. </p>
  1215.  
  1216. </section>
  1217.  
  1218. <!--========================================================================-->
  1219.  
  1220. <section>
  1221.  
  1222. <h2>3.3 - <span id="s3.3">Pointers, References, and Pass by Value</span></h2>
  1223.  
  1224. <p>
  1225. When C++ objects are passed from Lua back to C++ as arguments to functions,
  1226. or set as data members, LuaBridge does its best to automate the conversion.
  1227. Using the previous definitions, the following functions may be registered
  1228. to Lua:
  1229. </p>
  1230.  
  1231. <pre>
  1232. void func0 (A a);
  1233. void func1 (A* a);
  1234. void func2 (A const* a);
  1235. void func3 (A&amp; a);
  1236. void func4 (A const&amp; a);
  1237. </pre>
  1238.  
  1239. <p>
  1240. Executing this Lua code will have the prescribed effect:
  1241. </p>
  1242.  
  1243. <pre>
  1244. func0 (a)   -- Passes a copy of a, using A's copy constructor.
  1245. func1 (a)   -- Passes a pointer to a.
  1246. func2 (a)   -- Passes a pointer to a const a.
  1247. func3 (a)   -- Passes a reference to a.
  1248. func4 (a)   -- Passes a reference to a const a.
  1249. </pre>
  1250.  
  1251. <p>
  1252. In the example above, all functions can read the data members and property
  1253. members of <code>a</code>, or call const member functions of <code>a</code>.
  1254. Only <code>func0</code>, <code>func1</code>, and <code>func3</code> can
  1255. modify the data members and data properties, or call non-const member
  1256. functions of <code>a</code>.
  1257. </p>
  1258.  
  1259. <p>
  1260. The usual C++ inheritance and pointer assignment rules apply. Given:
  1261. </p>
  1262.  
  1263. <pre>
  1264. void func5 (B b);
  1265. void func6 (B* b);
  1266. </pre>
  1267.  
  1268. <p>
  1269. These Lua statements hold:
  1270. </p>
  1271.  
  1272. <pre>
  1273. func5 (b)   - Passes a copy of b, using B's copy constructor.
  1274. func6 (b)   - Passes a pointer to b.
  1275. func6 (a)   - Error: Pointer to B expected.
  1276. func1 (b)   - Okay, b is a subclass of a.
  1277. </pre>
  1278.  
  1279. <p>
  1280. When a pointer or pointer to const is passed to Lua and the pointer is null
  1281. (zero), LuaBridge will pass Lua a <code>nil</code> instead. When Lua passes a
  1282. <code>nil</code> to C++ where a pointer is expected, a null (zero) is passed
  1283. instead. Attempting to pass a null pointer to a C++ function expecting a
  1284. reference results in <code>lua_error</code> being called.
  1285. </p>
  1286.  
  1287. </section>
  1288.  
  1289. <!--========================================================================-->
  1290.  
  1291. <section>
  1292.  
  1293. <h2>3.4 - <span id="s3.4">Shared Lifetime</span></h2>
  1294.  
  1295. <p>
  1296. LuaBridge supports a <em>shared lifetime</em> model: dynamically allocated
  1297. and reference counted objects whose ownership is shared by both Lua and C++.
  1298. The object remains in existence until there are no remaining C++ or Lua
  1299. references, and Lua performs its usual garbage collection cycle. A container
  1300. is recognized by a specialization of the <code>ContainerTraits</code>
  1301. template class. LuaBridge will automatically recognize when a data type is
  1302. a container when the correspoding specialization is present. Two styles of
  1303. containers come with LuaBridge, including the necessary specializations.
  1304. </p>
  1305.  
  1306. <!--========================================================================-->
  1307.  
  1308. <section>
  1309.  
  1310. <h3>3.4.1 - <span id="s3.4.1">Class RefCountedObjectPtr</span></h3>
  1311.  
  1312. <p>
  1313. This is an intrusive style container. Your existing class declaration must be
  1314. changed to be also derived from <code>RefCountedObject</code>. Given
  1315. <code>class T</code>, derived from <code>RefCountedObject</code>, the container
  1316. <code>RefCountedObjectPtr &lt;T&gt;</code> may be used. In order for
  1317. reference counts to be maintained properly, all C++ code must store a
  1318. container instead of the pointer. This is similar in style to
  1319. <code>std::shared_ptr</code> although there are slight differences. For
  1320. example:
  1321. </p>
  1322.  
  1323. <pre>
  1324. // A is reference counted.
  1325. struct A : public RefCountedObject
  1326. {
  1327.  void foo () { }
  1328. };
  1329.  
  1330. struct B
  1331. {
  1332.  RefCountedObjectPtr &lt;A&gt; a; // holds a reference to A
  1333. };
  1334.  
  1335. void bar (RefCountedObjectPtr &lt;A&gt; a)
  1336. {
  1337.  a->foo ();
  1338. }
  1339. </pre>
  1340.  
  1341. </section>
  1342.  
  1343. <!--========================================================================-->
  1344.  
  1345. <section>
  1346.  
  1347. <h3>3.4.2 - <span id="s3.4.2">Class RefCountedPtr</span></h3>
  1348.  
  1349. <p>
  1350. This is a non intrusive reference counted pointer. The reference counts are
  1351. kept in a global hash table, which does incur a small performance penalty.
  1352. However, it does not require changing any already existing class declarations.
  1353. This is especially useful when the classes to be registered come from a third
  1354. party library and cannot be modified. To use it, simply wrap all pointers
  1355. to class objects with the container instead:
  1356. </p>
  1357.  
  1358. <pre>
  1359. struct A
  1360. {
  1361.  void foo () { }
  1362. };
  1363.  
  1364. struct B
  1365. {
  1366.  RefCountedPtr &lt;A&gt; a;
  1367. };
  1368.  
  1369. RefCountedPtr &lt;A&gt; createA ()
  1370. {
  1371.  return new A;
  1372. }
  1373.  
  1374. void bar (RefCountedPtr &lt;A&gt; a)
  1375. {
  1376.  a->foo ();
  1377. }
  1378.  
  1379. void callFoo ()
  1380. {
  1381.  bar (createA ());
  1382.  
  1383.  // The created A will be destroyed
  1384.  // when we leave this scope
  1385. }
  1386. </pre>
  1387.  
  1388. </section>
  1389.  
  1390. <!--========================================================================-->
  1391.  
  1392. <section>
  1393.  
  1394. <h3>3.4.3 - <span id="s3.4.3">User-defined Containers</span></h3>
  1395.  
  1396. <p>
  1397. If you have your own container, you must provide a specialization of
  1398. <code>ContainerTraits</code> in the <code>luabridge</code> namespace for your
  1399. type before it will be recognized by LuaBridge (or else the code will not
  1400. compile):
  1401. </p>
  1402.  
  1403. <pre>
  1404. template &lt;class T&gt;
  1405. struct ContainerTraits &lt;CustomContainer &lt;T&gt; &gt;
  1406. {
  1407.  typedef typename T Type;
  1408.  
  1409.  static T* get (CustomContainer &lt;T&gt; const&amp; c)
  1410.  {
  1411.    return c.getPointerToObject ();
  1412.  }
  1413. };
  1414. </pre>
  1415.  
  1416. <p>
  1417. Standard containers like <code>std::shared_ptr</code> or
  1418. <code>boost::shared_ptr</code> <b>will not work</b>. This is because of type
  1419. erasure; when the object goes from C++ to Lua and back to C++, there is no
  1420. way to associate the object with the original container. The new container is
  1421. constructed from a pointer to the object instead of an existing container.
  1422. The result is undefined behavior since there are now two sets of reference
  1423. counts.
  1424. </p>
  1425.  
  1426. </section>
  1427.  
  1428. <!--========================================================================-->
  1429.  
  1430. <section>
  1431.  
  1432. <h3>3.4.4 - <span id="s3.4.4">Container Constructors</span></h3>
  1433.  
  1434. <p>
  1435. When a constructor is registered for a class, there is an additional
  1436. optional second template parameter describing the type of container to use.
  1437. If this parameter is specified, calls to the constructor will create the
  1438. object dynamically, via operator new, and place it a container of that
  1439. type. The container must have been previously specialized in
  1440. <code>ContainerTraits</code>, or else a compile error will result. This code
  1441. will register two objects, each using a constructor that creates an object
  1442. with Lua lifetime using the specified container:
  1443. </p>
  1444.  
  1445. <pre>
  1446. class C : public RefCountedObject
  1447. {
  1448.  C () { }
  1449. };
  1450.  
  1451. class D
  1452. {
  1453.  D () { }
  1454. };
  1455.  
  1456. getGlobalNamespace (L)
  1457.  .beginNamespace ("test")
  1458.    .beginClass &lt;C&gt; ("C")
  1459.      .addConstructor &lt;void (*) (void), RefCountedObjectPtr &lt;C&gt; &gt; ()
  1460.    .endClass ()
  1461.    .beginClass &lt;D&gt; ("D")
  1462.      .addConstructor &lt;void (*) (void), RefCountedPtr &lt;D&gt; &gt; ()
  1463.    .endClass ();
  1464.  .endNamespace ()
  1465. </pre>
  1466.  
  1467. </section>
  1468.  
  1469. <!--========================================================================-->
  1470.  
  1471. </section>
  1472.  
  1473. <section>
  1474.  
  1475. <h2>3.5 - <span id="s3.5">Mixing Lifetimes</span></h2>
  1476.  
  1477. <p>
  1478. Mixing object lifetime models is entirely possible, subject to the usual
  1479. caveats of holding references to objects which could get deleted. For
  1480. example, C++ can be called from Lua with a pointer to an object of class
  1481. type; the function can modify the object or call non-const data members.
  1482. These modifications are visible to Lua (since they both refer to the same
  1483. object). An object store in a container can be passed to a function expecting
  1484. a pointer. These conversion work seamlessly.
  1485. <p>
  1486.  
  1487. </section>
  1488.  
  1489. <!--========================================================================-->
  1490.  
  1491. <section>
  1492.  
  1493. <h2>3.6 - <span id="s3.6">Convenience Functions</span></h2>
  1494.  
  1495. <p>
  1496. The <code>setGlobal</code> function can be used to assign any convertible
  1497. value into a global variable.
  1498. </p>
  1499.  
  1500. </section>
  1501.  
  1502. <!--========================================================================-->
  1503.  
  1504. </section>
  1505.  
  1506. <section>
  1507.  
  1508. <h1>4 - <span id="s4">Accessing Lua from C++</span></h1>
  1509.  
  1510. <p>
  1511. Because Lua is a <em>dynamically typed language</em>, special consideration
  1512. is required to map values in Lua to C++. The following sections describe the
  1513. classes and functions used for representing Lua types. Only the essential
  1514. operations are explained; To gain understanding of all available functions,
  1515. please refer to the documentation comments in the corresponding source files.
  1516. </p>
  1517.  
  1518. <!--========================================================================-->
  1519.  
  1520. <section>
  1521.  
  1522. <h2>4.1 - <span id="s4.1">Class LuaRef</span></h2>
  1523.  
  1524. <p>
  1525. The <code>LuaRef</code> class is a container which references any Lua type.
  1526. It can hold anything which a Lua variable can hold: <strong>nil</strong>,
  1527. number, boolean, string, table, function, thread, userdata, and
  1528. lightuserdata. Because <code>LuaRef</code> uses the <code>Stack</code>
  1529. template specializations to do its work, classes, functions, and data
  1530. exported to Lua through namespace registrations can also be stored (these
  1531. are instances of userdata). In general, a <code>LuaRef</code> can represent
  1532. any <em>convertible</em> C++ type as well as all Lua types.
  1533. </p>
  1534.  
  1535. <p>
  1536. A <code>LuaRef</code> variable constructed with no parameters produces a
  1537. reference to <strong>nil</strong>:
  1538. </p>
  1539.  
  1540. <pre>
  1541. LuaRef v (L); // References nil
  1542. </pre>
  1543.  
  1544. <p>
  1545. To construct a <code>LuaRef</code> to a specific value, the two parameter
  1546. constructor is used:
  1547. </p>
  1548.  
  1549. <pre>
  1550. LuaRef v1 (L, 1);                   // A LUA_TNUMBER
  1551. LuaRef v2 (L, 1.1);                 // Also a LUA_TNUMBER
  1552. LuaRef v3 (L, true);                // A LUA_TBOOLEAN
  1553. LuaRef v4 (L, "string");            // A LUA_TSTRING
  1554. </pre>
  1555.  
  1556. <p>
  1557. The functions <code>newTable</code> and <code>getGlobal</code> create
  1558. references to new empty table and an existing value in the global table
  1559. respectively:
  1560. </p>
  1561.  
  1562. <pre>
  1563. LuaRef v1 = newTable (L);           // Create a new table
  1564. LuaRef v2 = getGlobal (L, "print")  // Reference to _G ["print"]
  1565. </pre>
  1566.  
  1567. <p>
  1568. A <code>LuaRef</code> can hold classes <em>registered</em> using LuaBridge:
  1569. </p>
  1570.  
  1571. <pre>
  1572. class A;
  1573. //...
  1574. LuaRef v (L, new A); // A LuaBridge userdata holding a pointer to A
  1575. </pre>
  1576.  
  1577. <p>
  1578. Any convertible type may be assigned to an already-existing <code>LuaRef</code>:
  1579. </p>
  1580.  
  1581. <pre>
  1582. LuaRef v (L);         // Nil
  1583. v = newTable (L);     // An empty table
  1584. v = "string"          // A string. The prevous value becomes
  1585.                      // eligible for garbage collection.
  1586. </pre>
  1587.  
  1588. <p>
  1589. A <code>LuaRef</code> is itself a convertible type, and the convertible
  1590. type <code>Nil</code> can be used to represent a Lua <strong>nil</strong>.
  1591. </p>
  1592.  
  1593. <pre>
  1594. LuaRef v1 (L, "x");   // assign "x"
  1595. LuaRef v2 (L, "y");   // assign "y"
  1596. v2 = v1;              // v2 becomes "x"
  1597. v1 = "z";             // v1 becomes "z", v2 is unchanged
  1598. v1 = newTable (L);    // An empty table
  1599. v2 = v1;              // v2 references the same table as v1
  1600. v1 = Nil ();          // v1 becomes nil, table is still
  1601.                      // referenced by v2.
  1602. </pre>
  1603.  
  1604. <p>
  1605. Values stored in a <code>LuaRef</code> object obey the same rules as
  1606. variables in Lua: tables, functions, threads, and full userdata values are
  1607. <em>objects</em>. The <code>LuaRef</code> does not actually <em>contain</em>
  1608. these values, only <em>references</em> to them. Assignment, parameter
  1609. passing, and function returns always manipulate references to such values;
  1610. these operations do not imply any kind of copy.
  1611. </p>
  1612.  
  1613. <!--========================================================================-->
  1614.  
  1615. <section>
  1616.  
  1617. <h3>4.1.1 - <span id="s4.1.1">Type Conversions</span></h3>
  1618.  
  1619. <p>
  1620. A universal C++ conversion operator is provided for implicit conversions
  1621. which allow a <code>LuaRef</code> to be used where any convertible type is
  1622. expected. These operations will all compile:
  1623. </p>
  1624.  
  1625. <pre>
  1626. void passInt (int);
  1627. void passBool (bool);
  1628. void passString (std::string);
  1629. void passObject (A*);
  1630.  
  1631. LuaRef v (L);
  1632. //...
  1633. passInt (v);        // implicit conversion to int
  1634. passBool (v);       // implicit conversion to bool
  1635. passString (v);     // implicit conversion to string
  1636. passObject (v);     // must hold a registered LuaBridge class or a
  1637.                    // lua_error() will be called.
  1638. </pre>
  1639.  
  1640. <p>
  1641. Since Lua types are dynamic, the conversion is performed at run time using
  1642. traditional functions like <code>lua_toboolean</code> or
  1643. <code>lua_tostring</code>. In some cases, the type information may be
  1644. incorrect especially when passing objects of registered class types.
  1645. When performing these conversions, LuaBridge may raise a Lua error by
  1646. directly or indirectly calling <code>lua_error</code> To be bullet-proof,
  1647. such code must either be wrapped in a <code>lua_pcall</code>, or you must
  1648. install a Lua <em>panic function</em> that throws an exception which you
  1649. can catch.
  1650. </p>
  1651.  
  1652. <p>
  1653. When an explicit conversion is required (such as when writing templates),
  1654. use the <code>cast</code> template function or an explicit C++ style cast.
  1655. </p>
  1656.  
  1657. <pre>
  1658. void passString (std::string);
  1659.  
  1660. LuaRef v (L);
  1661.  
  1662. // The following are all equivalent:
  1663.  
  1664. passString (std::string (v));
  1665. passString ((std::string)v);
  1666. passString (static_cast &lt;std::string&gt; (v));
  1667. passString (v.cast &lt;std::string&gt; ());
  1668. </pre>
  1669.  
  1670. </section>
  1671.  
  1672. <!--========================================================================-->
  1673.  
  1674. </section>
  1675.  
  1676. <section>
  1677.  
  1678. <h2>4.2 - <span id="s4.2">Table Proxies</span></h2>
  1679.  
  1680. <p>
  1681. As tables are the sole data structuring mechanism in Lua, the
  1682. <code>LuaRef</code> class provides robust facilities for accessing and
  1683. manipulating table elements using a simple, precise syntax. Any convertible
  1684. type may be used as a key or value. Applying the array indexing operator
  1685. <code>[]</code> to a <code>LuaRef</code> returns a special temporary object
  1686. called a <em>table proxy</em> which supports all the operations which can
  1687. be performed on a <code>LuaRef</code>. In addition, assignments made to
  1688. table proxies change the underlying table. Because table proxies are
  1689. compiler-created temporary objects, you don't work with them directly. A
  1690. LuaBridge table proxy should not be confused with the Lua proxy table
  1691. technique described in the book "Programming in Lua"; the LuaBridge table
  1692. proxy is simply an intermediate C++ class object that works behind the
  1693. scenes to make table manipulation syntax conform to C++ idioms. These
  1694. operations all invoke table proxies:
  1695. </p>
  1696.  
  1697. <pre>
  1698. LuaRef v (L);
  1699. v = newTable (L);
  1700.  
  1701. v ["name"] = "John Doe";      // string key, string value
  1702. v [1] = 200;                  // integer key, integer value
  1703. v [2] = newTable (L);         // integer key, LuaRef value
  1704. v [3] = v [1];                // assign 200 to integer index 3
  1705. v [1] = 100;                  // v[1] is 100, v[3] is still 200
  1706. v [3] = v [2];                // v[2] and v[3] reference the same table
  1707. v [2] = Nil ();               // Removes the value with key = 2. The table
  1708.                               //   is still referenced by v[3].
  1709. </pre>
  1710.  
  1711. </section>
  1712.  
  1713. <!--========================================================================-->
  1714.  
  1715. <section>
  1716.  
  1717. <h2>4.3 - <span id="s4.3">Calling Lua</span></h2>
  1718.  
  1719. <p>
  1720. Table proxies and <code>LuaRef</code> objects provide a convenient syntax
  1721. for invoking <code>lua_pcall</code> on suitable referenced object. This
  1722. includes C functions, Lua functions, or Lua objects with an appropriate
  1723. <code>__call</code> metamethod set. The provided implementation supports
  1724. up to eight parameters (although more can be supported by adding new
  1725. functions). Any convertible C++ type can be passed as a parameter in its
  1726. native format. The return value of the function call is provided as a
  1727. <code>LuaRef</code>, which may be <strong>nil</strong>.
  1728. </p>
  1729.  
  1730. <pre class="split">
  1731. LuaRef same = getGlobal (L, "same");
  1732.  
  1733. // These all evaluate to true
  1734. same (1,1);
  1735. !same (1,2);
  1736. same ("text", "text");
  1737. !same (1, "text");
  1738. same (1, 1, 2); // third param ignored
  1739. </pre>
  1740.  
  1741. <pre class="split">
  1742. function same (arg1, arg)
  1743.   return arg1 == arg2
  1744. end
  1745. </pre>
  1746.  
  1747. <p>
  1748. Table proxies support all of the Lua call notation that <code>LuaRef</code>
  1749. supports, making these statements possible:
  1750. </p>
  1751.  
  1752. <pre class="split">
  1753. LuaRef v = getGlobal (L, "t");
  1754.  
  1755. t[1]();
  1756. t[2]("a", "b");
  1757. t[2](t[1]); // Call t[3] with the value in t[2]
  1758. t[4]=t[3]();   // Call t[3] and store the result in t[4].
  1759.  
  1760. t [t[5]()] = "wow"; // Store "wow" at the key returned by
  1761.                     //   the call to t[5]
  1762. </pre>
  1763.  
  1764. <pre class="split">
  1765. t = {}
  1766. t[1] = function () print ("hello") end
  1767. t[2] = function (u, v) print (u, v) end
  1768. t[3] = "foo"
  1769. </pre>
  1770.  
  1771. <!--========================================================================-->
  1772.  
  1773. <h3>4.3.1 - <span id="s4.3.1">Class LuaException</span></h3>
  1774.  
  1775. <section >
  1776.  
  1777. <p>
  1778. When <code>LuaRef</code> is used to call into Lua using the <code>()</code>
  1779. operator it issues a protected call using <code>lua_pcall</code>. LuaBridge
  1780. uses the C++ exception handling mechanism, throwing a <code>LuaException</code>
  1781. object:
  1782. </p>
  1783.  
  1784. <pre class="split">
  1785. LuaRef f (L) = getGlobal (L, "fail");
  1786.  
  1787. try {
  1788.   f ();
  1789. }
  1790. catch (LuaException const&amp; e) {
  1791.   std::cerr &amp;&amp; e.what ();
  1792. }
  1793. </pre>
  1794.  
  1795. <pre class="split">
  1796. function fail ()
  1797.   error ("A problem occurred")
  1798. end
  1799. </pre>
  1800.  
  1801. </section>
  1802.  
  1803. <!--========================================================================-->
  1804.  
  1805. </section>
  1806.  
  1807. <!--========================================================================-->
  1808.  
  1809. </section>
  1810.  
  1811. <section>
  1812.  
  1813. <h1>5 - <span id="s5">Security</span></h1>
  1814.  
  1815. <p>
  1816. The metatables and userdata that LuaBridge creates in the <code>lua_State*</code> are
  1817. protected using a security system, to eliminate the possibility of undefined
  1818. behavior resulting from scripted manipulation of the environment. The
  1819. security system has these components:
  1820. </p>
  1821.  
  1822. <ul class="bullets">
  1823. <li>
  1824. Class and const class tables use the <em>table proxy</em> technique. The
  1825. corresponding metatables have <code>__index</code> and <code>__newindex</code>
  1826. metamethods, so these class tables are immutable from Lua.
  1827. <li>
  1828. Metatables have <code>__metatable</code> set to a boolean value. Scripts
  1829. cannot obtain the metatable from a LuaBridge object.
  1830. <li>
  1831. Classes are mapped to metatables through the registry, which Lua scripts
  1832. cannot access. The global environment does not expose metatables
  1833. <li>
  1834. Metatables created by LuaBridge are tagged with a lightuserdata key which
  1835. is unique in the process. Other libraries cannot forge a LuaBridge
  1836. metatable.
  1837. </ul>
  1838.  
  1839. <p>
  1840. This security system can be easily bypassed if scripts are given access to
  1841. the debug library (or functionality similar to it, i.e. a raw <code>getmetatable</code>).
  1842. The security system can also be defeated by C code in the host, either by
  1843. revealing the unique lightuserdata key to another module or by putting a
  1844. LuaBridge metatable in a place that can be accessed by scripts.
  1845. </p>
  1846.  
  1847. <p>
  1848. When a class member function is called, or class property member accessed,
  1849. the <code>this</code> pointer is type-checked. This is because member functions exposed
  1850. to Lua are just plain functions that usually get called with the Lua colon
  1851. notation, which passes the object in question as the first parameter. Lua's
  1852. dynamic typing makes this type-checking mandatory to prevent undefined
  1853. behavior resulting from improper use.
  1854. </p>
  1855.  
  1856. <p>
  1857. If a type check error occurs, LuaBridge uses the <code>lua_error</code>
  1858. mechanism to trigger a failure. A host program can always recover from
  1859. an error through the use of <code>lua_pcall</code>; proper usage of
  1860. LuaBridge will never result in undefined behavior.
  1861. </p>
  1862.  
  1863. </section>
  1864.  
  1865. <!--========================================================================-->
  1866.  
  1867. <section>
  1868.  
  1869. <h1>Appendix - <span id="appendix">API Reference</span></h1>
  1870.  
  1871. <h2>Free Functions</h2>
  1872.  
  1873. <pre>
  1874. /// Gets a global Lua variable reference.
  1875. ///
  1876. LuaRef getGlobal(lua_State* L, const char* name);
  1877. </pre>
  1878.  
  1879. <pre>
  1880. /// Sets a global Lua variable.
  1881. ///
  1882. template&lt;class V&gt;
  1883. void setGlobal(lua_State* L, V* varPtr, const char* name);
  1884. </pre>
  1885.  
  1886. <pre>
  1887. /// Gets the global namespace registration object.
  1888. ///
  1889. Namespace getGlobalNamespace(lua_State* L);
  1890. </pre>
  1891.  
  1892. <h2>Namespace Registration - Namespace</h2>
  1893.  
  1894. <pre>
  1895. /// Begins or continues class registration, returns this class object.
  1896. ///
  1897. template&lt;class T&gt;
  1898. Class&lt;T&gt; beginClass(const char* name);
  1899. </pre>
  1900.  
  1901. <pre>
  1902. /// Begins derived class registration, returns this class object.
  1903. ///
  1904. template&lt;class T, class Base&gt;
  1905. Class&lt;T&gt; deriveClass(const char* name);
  1906. </pre>
  1907.  
  1908. <pre>
  1909. /// Begin or continues namespace registration, returns this namespace object.
  1910. ///
  1911. template&lt;class T&gt;
  1912. Namespace beginNamespace(const char* name);
  1913. </pre>
  1914.  
  1915. <pre>
  1916. /// Ends namespace registration, returns the parent namespace object.
  1917. ///
  1918. template&lt;class T&gt;
  1919. Namespace endNamespace();
  1920. </pre>
  1921.  
  1922. <pre>
  1923. /// Registers a function.
  1924. ///
  1925. template&lt;class R, class... Params>&gt;
  1926. Namespace addFunction(const char* name,
  1927.                      R (*fn)(Params...));
  1928. </pre>
  1929.  
  1930. <pre>
  1931. /// Registers a function.
  1932. ///
  1933. template&lt;class R, class... Params>&gt;
  1934. Namespace addFunction(const char* name,
  1935.                      std::function&lt;R (Params...)&gt; fn);
  1936. </pre>
  1937.  
  1938. <pre>
  1939. /// Registers a function with an extra Lua state parameter.
  1940. ///
  1941. template&lt;class R, class... Params>&gt;
  1942. Namespace addFunction(const char* name,
  1943.                      R (*fn)(Params..., lua_State*))
  1944. </pre>
  1945.  
  1946. <pre>
  1947. /// Registers a C-function.
  1948. ///
  1949. Namespace addFunction(const char* name,
  1950.                      int (*fn)(lua_State*));
  1951. </pre>
  1952.  
  1953. <pre>
  1954. /// Registers a property with a getter and setter.
  1955. ///
  1956. template&lt;class V&gt;
  1957. Namespace addProperty(const char* name,
  1958.                      V (*getFn)(),
  1959.                      void (*setFn)(V));
  1960. </pre>
  1961.  
  1962. <pre>
  1963. /// Registers a property with a getter and setter.
  1964. ///
  1965. template&lt;class V&gt;
  1966. Namespace addProperty(const char* name,
  1967.                      std::function&lt;V ()&gt; getFn,
  1968.                      std::function&lt;void (V)&gt; setFn);
  1969. </pre>
  1970.  
  1971. <pre>
  1972. /// Registers a property with a C-function getter and setter.
  1973. ///
  1974. Namespace addProperty(const char* name,
  1975.                      int (*getFn)(lua_State*),
  1976.                      int (*setFn)(lua_State*));
  1977. </pre>
  1978.  
  1979. <pre>
  1980. /// Registers a read-only property with a getter function.
  1981. ///
  1982. template&lt;class V&gt;
  1983. Namespace addProperty(const char* name,
  1984.                      V (*getFn)());
  1985. </pre>
  1986.  
  1987. <pre>
  1988. /// Registers a read-only property with a getter function.
  1989. ///
  1990. template&lt;class V&gt;
  1991. Namespace addProperty(const char* name,
  1992.                      std::function&lt;V ()&gt; getFn);
  1993. </pre>
  1994.  
  1995. <pre>
  1996. /// Registers a read-only property with a C-function getter.
  1997. ///
  1998. Namespace addProperty(const char* name,
  1999.                      int (*getFn)(lua_State*));
  2000. </pre>
  2001.  
  2002. <pre>
  2003. /// Registers a variable, writable or read-only.
  2004. ///
  2005. template&lt;class V&gt;
  2006. Namespace addVariable(const char* name,
  2007.                      V* varPtr,
  2008.                      bool isWritable = true);
  2009. </pre>
  2010.  
  2011. <h2>Class Registration - Class&lt;T&gt;</h2>
  2012.  
  2013. <pre>
  2014. /// Ends class registration, returns the parent namespace object.
  2015. ///
  2016. template&lt;class T&gt;
  2017. Namespace endClass();
  2018. </pre>
  2019.  
  2020. <h3>Member Function Registration</h3>
  2021.  
  2022. <pre>
  2023. /// Registers a member function.
  2024. ///
  2025. template&lt;class R, class... Params>&gt;
  2026. Namespace addFunction(const char* name,
  2027.                      R (T::* fn)(Params...));
  2028. </pre>
  2029.  
  2030. <pre>
  2031. /// Registers a function.
  2032. ///
  2033. template&lt;class R, class... Params>&gt;
  2034. Namespace addFunction(const char* name,
  2035.                      std::function&lt;R (Params...)&gt; fn);
  2036. </pre>
  2037.  
  2038. <pre>
  2039. /// Registers a function with an extra Lua state parameter.
  2040. ///
  2041. template&lt;class R, class... Params>&gt;
  2042. Namespace addFunction(const char* name,
  2043.                      R (T::* fn)(Params..., lua_State*))
  2044. </pre>
  2045.  
  2046. <pre>
  2047. /// Registers a C-function.
  2048. ///
  2049. Namespace addFunction(const char* name,
  2050.                      int (*fn)(lua_State*));
  2051. </pre>
  2052.  
  2053. <h3>Member Property Registration</h3>
  2054.  
  2055. <pre>
  2056. /// Registers a property with a getter and setter.
  2057. ///
  2058. template&lt;class V&gt;
  2059. Namespace addProperty(const char* name,
  2060.                      V (T::* getFn)(),
  2061.                      void (T::* setFn)(V));
  2062. </pre>
  2063.  
  2064. <pre>
  2065. /// Registers a property with a getter and setter.
  2066. ///
  2067. template&lt;class V&gt;
  2068. Namespace addProperty(const char* name,
  2069.                      std::function&lt;V ()&gt; getFn,
  2070.                      std::function&lt;void (V)&gt; setFn);
  2071. </pre>
  2072.  
  2073. <pre>
  2074. /// Registers a property with a C-function getter and setter.
  2075. ///
  2076. Namespace addProperty(const char* name,
  2077.                      int (*getFn)(lua_State*),
  2078.                      int (*setFn)(lua_State*));
  2079. </pre>
  2080.  
  2081. <pre>
  2082. /// Registers a read-only property with a getter member function.
  2083. ///
  2084. template&lt;class V&gt;
  2085. Namespace addProperty(const char* name,
  2086.                      V (T::* getFn)());
  2087. </pre>
  2088.  
  2089. <pre>
  2090. /// Registers a read-only property with a getter function.
  2091. ///
  2092. template&lt;class V&gt;
  2093. Namespace addProperty(const char* name,
  2094.                      std::function&lt;V ()&gt; getFn);
  2095. </pre>
  2096.  
  2097. <pre>
  2098. /// Registers a read-only property with a C-function getter.
  2099. ///
  2100. Namespace addProperty(const char* name,
  2101.                      int (*getFn)(lua_State*));
  2102. </pre>
  2103.  
  2104. <pre>
  2105. /// Registers a member variable, writable or read-only.
  2106. ///
  2107. template&lt;class V&gt;
  2108. Namespace addData(const char* name,
  2109.                  V T::* varPtr,
  2110.                  bool isWritable = true);
  2111. </pre>
  2112.  
  2113. <h3>Static Function Registration</h3>
  2114.  
  2115. <pre>
  2116. /// Registers a function.
  2117. ///
  2118. template&lt;class R, class... Params>&gt;
  2119. Namespace addStaticFunction(const char* name,
  2120.                            R (*fn)(Params...));
  2121. </pre>
  2122.  
  2123. <pre>
  2124. /// Registers a function.
  2125. ///
  2126. template&lt;class R, class... Params>&gt;
  2127. Namespace addStaticFunction(const char* name,
  2128.                            std::function&lt;R (Params...)&gt; fn);
  2129. </pre>
  2130.  
  2131. <pre>
  2132. /// Registers a function with an extra Lua state parameter.
  2133. ///
  2134. template&lt;class R, class... Params>&gt;
  2135. Namespace addStaticFunction(const char* name,
  2136.                            R (*fn)(Params..., lua_State*))
  2137. </pre>
  2138.  
  2139. <pre>
  2140. /// Registers a C-function.
  2141. ///
  2142. Namespace addStaticFunction(const char* name,
  2143.                            int (*fn)(lua_State*));
  2144. </pre>
  2145.  
  2146. <h3>Static Property Registration</h3>
  2147.  
  2148. <pre>
  2149. /// Registers a property with a getter and setter.
  2150. ///
  2151. template&lt;class V&gt;
  2152. Namespace addStaticProperty(const char* name,
  2153.                            V (*getFn)(),
  2154.                            void (*setFn)(V));
  2155. </pre>
  2156.  
  2157. <pre>
  2158. /// Registers a property with a getter and setter.
  2159. ///
  2160. template&lt;class V&gt;
  2161. Namespace addStaticProperty(const char* name,
  2162.                            std::function&lt;V ()&gt; getFn,
  2163.                            std::function&lt;void (V)&gt; setFn);
  2164. </pre>
  2165.  
  2166. <pre>
  2167. /// Registers a property with a C-function getter and setter.
  2168. ///
  2169. Namespace addStaticProperty(const char* name,
  2170.                            int (*getFn)(lua_State*),
  2171.                            int (*setFn)(lua_State*));
  2172. </pre>
  2173.  
  2174. <pre>
  2175. /// Registers a read-only property with a getter function.
  2176. ///
  2177. template&lt;class V&gt;
  2178. Namespace addStaticProperty(const char* name,
  2179.                            V (*getFn)());
  2180. </pre>
  2181.  
  2182. <pre>
  2183. /// Registers a read-only property with a getter function.
  2184. ///
  2185. template&lt;class V&gt;
  2186. Namespace addStaticProperty(const char* name,
  2187.                            std::function&lt;V ()&gt; getFn);
  2188. </pre>
  2189.  
  2190. <pre>
  2191. /// Registers a read-only property with a C-function getter.
  2192. ///
  2193. Namespace addStaticProperty(const char* name,
  2194.                            int (*getFn)(lua_State*));
  2195. </pre>
  2196.  
  2197. <pre>
  2198. /// Registers a variable, writable or read-only.
  2199. ///
  2200. Namespace addStaticData(const char* name,
  2201.                        T* varPtr,
  2202.                        bool isWritable = true);
  2203. </pre>
  2204.  
  2205. <h2>Lua Variable Reference - LuaRef</h2>
  2206.  
  2207. <pre>
  2208. /// Creates a nil reference.
  2209. ///
  2210. LuaRef(lua_State* L);
  2211. </pre>
  2212.  
  2213. <pre>
  2214. /// Returns native Lua string representation.
  2215. ///
  2216. std::string tostring() const;
  2217. </pre>
  2218.  
  2219. <pre>
  2220. /// Dumps reference to a stream.
  2221. ///
  2222. void print(std::ostream& stream) const;
  2223. </pre>
  2224.  
  2225. <pre>
  2226. /// Returns the Lua state.
  2227. ///
  2228. lua_State* state() const;
  2229. </pre>
  2230.  
  2231. <pre>
  2232. /// Place the object onto the Lua stack.
  2233. ///
  2234. void push(lua_State* L);
  2235. </pre>
  2236.  
  2237. <pre>
  2238. /// Return the lua_type.
  2239. ///
  2240. int type() const;
  2241. </pre>
  2242.  
  2243. <pre>
  2244. /// Perform the explicit type conversion.
  2245. ///
  2246. template&lt;class T&gt;
  2247. T cast() const;
  2248. </pre>
  2249.  
  2250. <pre>
  2251. /// Check if the Lua value is convertible to the type T.
  2252. ///
  2253. template&lt;class T&gt;
  2254. bool isInstance() const;
  2255. </pre>
  2256.  
  2257. <h2>Stack Traits - Stack&lt;T&gt;</h2>
  2258.  
  2259. <pre>
  2260. /// Converts the C++ value into the Lua value at the top of the Lua stack.
  2261. ///
  2262. void put (lua_State* L, T value);
  2263. </pre>
  2264.  
  2265. <pre>
  2266. /// Converts the Lua value at the index into the C++ value of the type T.
  2267. ///
  2268. T get (lua_State* L, int index);
  2269. </pre>
  2270.  
  2271. <pre>
  2272. /// Checks if the Lua value at the index is convertible into the C++ value of the type T.
  2273. ///
  2274. bool isInstance (lua_State* L, int index);
  2275. </pre>
  2276.  
  2277. </section>
  2278.  
  2279. </body>
  2280. </html>
  2281.