diff options
Diffstat (limited to 'lib/LuaBridge/Manual.html')
| -rw-r--r-- | lib/LuaBridge/Manual.html | 1897 |
1 files changed, 1897 insertions, 0 deletions
diff --git a/lib/LuaBridge/Manual.html b/lib/LuaBridge/Manual.html new file mode 100644 index 0000000..69f7ba9 --- /dev/null +++ b/lib/LuaBridge/Manual.html @@ -0,0 +1,1897 @@ +<!doctype html> +<html> +<head> +<title>LuaBridge 2.3 Reference Manual</title> +<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> + +<!--=========================================================================--> +<style TYPE="text/css"> + +body { + color: #000000 ; + background-color: #FFFFFF ; + font-family: Helvetica, Arial, sans-serif ; + text-align: justify ; + margin-right: 30px ; + margin-left: 30px ; +} + +h1, h2, h3, h4 { + font-family: Verdana, Geneva, sans-serif ; + font-weight: normal ; + font-style: normal ; +} + +h1 { + padding-top: 0.4em ; + padding-bottom: 0.4em ; + padding-left: 24px ; + margin-left: -24px ; + background-color: #ffe668 ; + border-radius: 8px ; +} + +h2 { + padding-top: 0.4em ; + padding-bottom: 0.4em ; + padding-left: 1em ; + padding-right: 1em ; + background-color: #ffe668 ; + border-radius: 8px ; +} + +h3 { + padding-left: 0.5em ; + border-left: solid #ffe668 1em ; +} + +a:link { + color: #8d5c00 ; + background-color: inherit ; + text-decoration: none ; +} + +a:visited { + color: #b17b26; + background-color: inherit ; + text-decoration: none ; +} + +a:link:hover, a:visited:hover { + color: #8d5c00 ; + background-color: #ffe668 ; +} + +a:link:active, a:visited:active { + color: inherit; +} + +hr { + border: 0 ; + height: 1px ; + color: #a0a0a0 ; + background-color: #a0a0a0 ; +} + +:target { + background-color: #F8F8F8 ; + padding-top: 2px ; + padding-bottom: 2px ; + padding-left: 8px; + padding-right: 8px; + border: solid #a0a0a0 2px ; +} + +.footer { + color: gray ; + font-size: small ; +} + +ul { + list-style-type: none ; + list-style-position: outside ; +} + +ul.bullets { + list-style-type: disc ; +} + +img { + border: 0; +} + +table { + margin-left: 2em; +} + +pre, code { + font-size: 12pt ; +} + +pre { + margin-left: 2em; +} + +pre.split { + padding-left: 2em; + display: table-cell ; + white-space: pre-wrap ; + vertical-align: text-top ; + padding-right: 2em; +} + +pre.split + pre.split { + border-left: 1px solid #ccc; +} + +</style> + +</head> + +<!--=========================================================================--> + +<body> + +<header> +<hr> +<h1>LuaBridge 2.3 Reference Manual</h1> +<hr> +</header> + +<small> +Official repository is located at +<a href="https://github.com/vinniefalco/LuaBridge">https://github.com/vinniefalco/LuaBridge</a>. +<br> +Copyright © 2012 Vinnie Falco. Freely available under the terms of the +<A HREF="http://www.opensource.org/licenses/mit-license.html">MIT License</A>. +</small> + +<nav> +<H2>Contents</H2> +<UL id="toc" style="padding: 0"> +<LI><A href="#s1">1 - Introduction</A> +<UL> + <LI><A href="#s1.1">1.1 - Design</A> + <LI><A href="#s1.2">1.2 - Repository</A> + <LI><A href="#s1.3">1.3 - License and Credits</A> +</UL> +<P> +<LI><A href="#s2">2 - Accessing C++ from Lua</A> +<UL> + <LI><A href="#s2.1">2.1 - Namespaces</A> + <LI><A href="#s2.2">2.2 - Data, Properties, Functions, and CFunctions</A> + <LI><A href="#s2.3">2.3 - Class Objects</A> + <LI><A href="#s2.4">2.4 - Property Member Proxies</A> + <LI><A href="#s2.5">2.5 - Function Member Proxies</A> + <LI><A href="#s2.6">2.6 - Constructors</A> + <LI><A href="#s2.7">2.7 - Lua Stack</A> + <LI><A href="#s2.8">2.8 - lua_State</A> +</UL> +<p> +<LI><A href="#s3">3 - Passing Objects</A> +<UL> + <LI><A href="#s3.1">3.1 - C++ Lifetime</A> + <LI><A href="#s3.2">3.2 - Lua Lifetime</A> + <LI><A href="#s3.3">3.3 - Pointers, References, and Pass by Value</A> + <LI><A href="#s3.4">3.4 - Shared Lifetime</A> + <UL> + <LI><A href="#s3.4.1">3.4.1 - Class RefCountedObjectPtr</A> + <LI><A href="#s3.4.2">3.4.2 - Class RefCountedPtr</A> + <LI><A href="#s3.4.3">3.4.3 - User-defined Containers</A> + <LI><A href="#s3.4.4">3.4.4 - Container Constructors</A> + </UL> + <LI><A href="#s3.5">3.5 - Mixing Lifetimes</A> + <LI><A href="#s3.6">3.6 - Convenience Functions</A> +</UL> +<P> +<LI><A href="#s4">4 - Accessing Lua from C++</A> +<UL> + <LI><A href="#s4.1">4.1 - Class LuaRef</A> + <UL> + <LI><A href="#s4.1.1">4.1.1 - Type Conversions</A> + <LI><A href="#s4.1.2">4.1.2 - Visual Studio 2010, 2012</A> + </UL> + <LI><A href="#s4.2">4.2 - Table Proxies</A> + <LI><A href="#s4.3">4.3 - Calling Lua</A> + <UL> + <LI><A href="#s4.3.1">4.3.1 - Class LuaException</A> + </UL> +</uL> +<P> +<LI><A href="#s5">5 - Security</A> +</UL> +</nav> + +<!--========================================================================--> + +<section> + +<h1>1 - <span id="s1">Introduction</span></h1> + +<p> +<a href="https://github.com/vinniefalco/LuaBridge">LuaBridge</a> is a +lightweight and dependency-free library for mapping data, functions, and +classes back and forth between C++ and <a href="http://wwww.lua.org">Lua</a>, +a powerful, fast, lightweight, embeddable scripting language. LuaBridge has +been tested and works with Lua revisions starting from 5.1.5, although it +should work in any version of Lua from 5.1.0 and later. It also works +transparently with <a href="http://luajit.org/">LuaJIT</a>. +</p> + +<p> +LuaBridge offers the following features: +</p> + +<ul class="bullets" title="Features"> +<li><a href="http://www.opensource.org/licenses/mit-license.html">MIT Licensed</a>, no usage restrictions!</li> +<li>Headers-only: No Makefile, no .cpp files, just one <code>#include</code>!</li> +<li>Simple, light, and nothing else needed (like Boost).</li> +<li>No macros, settings, or configuration scripts needed.</li> +<li>Supports different object lifetime management models.</li> +<li>Convenient, type-safe access to the Lua stack.</li> +<li>Automatic function parameter type binding.</li> +<li>Easy access to Lua objects like tables and functions.</li> +<li>Written in a clear and easy to debug style.</li> +<li>Does not require C++11.</li> +</ul> + +<p> +LuaBridge is distributed as a a collection of header files. You simply add +one line, <code>#include "LuaBridge/LuaBridge.h"</code> where you want to +pass functions, classes, and variables back and forth between C++ and Lua. +There are no additional source files, no compilation settings, and no +Makefiles or IDE-specific project files. LuaBridge is easy to integrate. +</p> + +<p> +C++ concepts like variables and classes are made available to Lua through a +process called <em>registration</em>. Because Lua is weakly typed, the resulting +structure is not rigid. The API is based on C++ template metaprogramming. It +contains template code to automatically generate at compile-time the various +Lua C API calls necessary to export your program's classes and functions to +the Lua environment. +</p> + +<p> +To expose Lua objects to C++, a class called <code>LuaRef</code> is provided. +The implementation allows C++ code to access Lua objects such as numbers +or strings, but more importantly to access things like tables and their +values. Using this class makes idioms like calling Lua functions simple +and clean. +</p> + +<!--========================================================================--> + +<section> + +<h2>1.1 - <span id="s1.1">Design</span></h2> + +<p> +LuaBridge tries to be efficient as possible when creating the "glue" that +exposes C++ data and functions to Lua. At the same time, the code was +written with the intention that it is all as simple and clear as possible, +without resorting to obscure C++ idioms, ugly preprocessor macros, or +configuration settings. Furthermore, it is designed to be "header-only", +making it very easy to integrate into your projects. +</p> + +<p> +Because LuaBridge was written with simplicity in mind there are some features +that are not available. Although it comes close to the highest possible +performance, LuaBridge is not quite the fastest, +<a href="http://code.google.com/p/oolua/">OOLua</a> slightly outperforms +LuaBridge in some tests. LuaBridge also does not try to implement every +possible feature, +<a href="http://www.rasterbar.com/products/luabind.html">LuaBind</a> +explores every corner of the C++ language (but it requires Boost). +</p> + +<p> +LuaBridge does not support: +</p> + +<ul class="bullets"> +<li>Enumerated constants +<li>More than 8 parameters on a function or method (although this can be + increased by adding more <code>TypeListValues</code> specializations). +<li>Overloaded functions, methods, or constructors. +<li>Global variables (variables must be wrapped in a named scope). +<li>Automatic conversion between STL container types and Lua tables + (conversion can be enabled for <code>std::list</code>, <code>std::vector</code>, + <code>std::map</code> or <code>std::unordered_map</code> by including + <code>List.h</code>, <code>Vector.h</code>, <code>Map</code> or + <code>UnorderedMap.h</code> respectively) +<li>Inheriting Lua classes from C++ classes. +<li>Passing nil to a C++ function that expects a pointer or reference. +<li>Standard containers like <code>std::shared_ptr</code>. +</ul> + +</section> + +<!--========================================================================--> + +<section> + +<h2>1.2 - <span id="s1.2">Repository</span></h2> + +<p> +The official repository is located at +<a href="https://github.com/vinniefalco/LuaBridge">https://github.com/vinniefalco/LuaBridge</a>. +The branches are organized as follows: +</p> + +<table> +<tr> + <td><b>master</b></td> + <td>Tagged, stable release versions.</td> +</tr> +<tr> + <td><b>release</b></td> + <td>A temporarily created branch that holds a release candidate for review.</td> +</tr> +<tr> + <td><b>develop</b></td> + <td>Contains work in progress, possibly unfinished or with bugs.</td> +</tr> +</table> + +<p> +These repositories are also available: +</p> + +<table> +<tr> + <td><b><a href="https://github.com/vinniefalco/LuaBridgeUnitTests">LuaBridgeUnitTests</a></b></td> + <td>A stand alone command line application to exercise LuaBridge functionality.</td> +</tr> +<tr> + <td><b><a href="https://github.com/vinniefalco/LuaBridgeDemo">LuaBridgeUnitDemo</a></b></td> + <td>A stand alone GUI application that provides an interactive console.</td> +</tr> +</table> + +</section> + +<!--========================================================================--> + +<section> + +<h2>1.3 - <span id="s1.3">License and Credits</span></h2> + +<p> +LuaBridge is published under the terms of the +<a href="http://www.opensource.org/licenses/mit-license.html">MIT License</a>: +</p> + +<pre> +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +</pre> + +<p> +The original version of LuaBridge was written by Nathan Reed. The project +has been taken over by Vinnie Falco, who added new functionality and wrote +the new documentation. Vinnie also incorporated <code>LuaRef</code> and +other Lua to C++ binding contributions from Nigel Atkinson. +</p> + +<p> +For questions, comments, or bug reports feel free to open a Github issue +or contact Vinnie Falco directly at the email address indicated below. +</p> + +<ul> +<li>Copyright 2019, Dmitry Tarakanov</li> +<li>Copyright 2012, Vinnie Falco <a href="mailto:vinnie.falco@gmail.com"><vinnie.falco@gmail.com></a> +<li>Copyright 2008, Nigel Atkinson <a href="mailto:suprapilot+LuaCode@gmail.com"><suprapilot+LuaCode@gmail.com></a> +<li>Copyright 2007, Nathan Reed +<li>Portions from The Loki Library: Copyright 2001 by Andrei Alexandrescu +</ul> + +<p> +Older versions of LuaBridge up to and including 0.2 (available separately) are +distributed under the BSD 3-Clause License. See the corresponding license file +in those versions (distributed separately) for more details. +</p> + +</section> + +<!--========================================================================--> + +</section> + +<section> + +<h1>2 - <span id="s2">Accessing C++ from Lua</span></h1> + +<p> +In order to expose C++ data and functions to Lua, each piece of exported +information must be <em>registered</em>. There are five types of objects that +LuaBridge can register: +</p> + +<table> +<tr> + <td><b>Namespaces</b> </td> + <td>A Lua table that contains other registrations.</td> +</tr> +<tr> + <td><b>Data</b> </td> + <td>Global or static variables, data members, and static data members.</td> +</tr> +<tr> + <td><b>Functions </b></td> + <td>Regular functions, member functions, and static member functions.</td> +</tr> +<tr> + <td><b>CFunctions </b></td> + <td>A regular function, member function, or static member function that + uses the <code>lua_CFunction</code> calling convention.</td> +</tr> +<tr> + <td><b>Properties </b></td> + <td>Global properties, property members, and static property members. + These appear like data to Lua, but are implemented in C++ using + functions to get and set the values.</td> + </tr> +</table> + +<p> +Both data and properties can be marked as <em>read-only</em> at the time of +registration. This is different from <code>const</code>; the values of these +objects can be modified on the C++ side, but Lua scripts cannot change them. +Code samples that follow are in C++ or Lua, depending on context. For brevity +of exposition code samples in C++ assume the traditional variable +<code>lua_State* L</code> is defined, and that a <code>using namespace luabridge</code> +using-directive is in effect. +</p> + +<!--========================================================================--> + +<section> + +<h2>2.1 - <span id="s2.1">Namespaces</span></h2> + +<p> +All LuaBridge registrations take place in a <em>namespace</em>. When we refer +to a <em>namespace</em> we are always talking about a namespace in the Lua +sense, which is implemented using tables. The namespace need not correspond +to a C++ namespace; in fact no C++ namespaces need to exist at all unless you +want them to. LuaBridge namespaces are visible only to Lua scripts; they are +used as a logical grouping tool. To obtain access to the global namespace +we write: +</p> + +<pre> +getGlobalNamespace (L); +</pre> + +<p> +This returns an object on which further registrations can be performed. The +subsequent registrations will go into the global namespace, a practice which +is not recommended. Instead, we can add our own namespace by writing: +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test"); +</pre> + +<p> +This creates a table in <code>_G</code> called "test". Since we have not +performed any registrations, this table will be empty except for some +bookkeeping key/value pairs. LuaBridge reserves all identifiers that start +with a double underscore. So <code>__test</code> would be an invalid name +(although LuaBridge will silently accept it). Functions like +<code>beginNamespace</code> return the corresponding object on which we can +make more registrations. Given: +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test") + .beginNamespace ("detail") + .endNamespace () + .beginNamespace ("utility") + .endNamespace () + .endNamespace (); +</pre> + +<p> +The results are accessible to Lua as <code>test</code>, <code>test.detail</code>, +and <code>test.utility</code>. Here we introduce the <code>endNamespace</code> +function; it returns an object representing the original enclosing namespace. +All LuaBridge functions which create registrations return an object upon which +subsequent registrations can be made, allowing for an unlimited number of +registrations to be chained together using the dot operator. Adding two objects +with the same name, in the same namespace, results in undefined behavior +(although LuaBridge will silently accept it). +</p> + +<p> +A namespace can be re-opened later to add more functions. This lets you split +up the registration between different source files. These are equivalent: +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test") + .addFunction ("foo", foo) + .endNamespace (); + +getGlobalNamespace (L) + .beginNamespace ("test") + .addFunction ("bar", bar) + .endNamespace (); +</pre> + +<p> +and +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test") + .addFunction ("foo", foo) + .addFunction ("bar", bar) + .endNamespace (); +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h2>2.2 - <span id="s2.2">Properties and Functions</span></h2> + +<p> +These are registered into a namespace using <code>addProperty</code> +and <code>addFunction</code>. +When registered functions are called by scripts, LuaBridge automatically takes +care of the conversion of arguments into the appropriate data type when doing +so is possible. This automated system works for the function's return value, +and up to 8 parameters although more can be added by extending the templates. +Pointers, references, and objects of class type as parameters are treated +specially, and explained later. +</p> +<p> +If we have: +</p> + +<pre> +int globalVar; +static float staticVar; + +std::string stringProperty; +std::string getString () { return stringProperty; } +void setString (std::string s) { stringProperty = s; } + +int foo () { return 42; } +void bar (char const*) { } +int cFunc (lua_State* L) { return 0; } +</pre> + +<p> +These are registered with: +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test") + .addProperty ("var1", &globalVar) + .addProperty ("var2", &staticVar, false) // read-only + .addProperty ("prop1", getString, setString) + .addProperty ("prop2", getString) // read only + .addFunction ("foo", foo) + .addFunction ("bar", bar) + .addFunction ("cfunc", cFunc) + .endNamespace (); +</pre> + +<p> +Variables can be marked <em>read-only</em> by passing <code>false</code> in +the second optional parameter. If the parameter is omitted, <em>true</em> is +used making the variable read/write. Properties are marked read-only by +omitting the set function. After the registrations above, the following Lua +identifiers are valid: +</p> + +<pre> +test -- a namespace +test.var1 -- a lua_Number property +test.var2 -- a read-only lua_Number property +test.prop1 -- a lua_String property +test.prop2 -- a read-only lua_String property +test.foo -- a function returning a lua_Number +test.bar -- a function taking a lua_String as a parameter +test.cfunc -- a function with a variable argument list and multi-return +</pre> + +<p> +Note that <code>test.prop1</code> and <code>test.prop2</code> both refer to the +same value. However, since <code>test.prop2</code> is read-only, assignment +attempts will generate a run-time error. These Lua statements have the stated effects: +</p> + +<pre> +test.var1 = 5 -- okay +test.var2 = 6 -- error: var2 is not writable +test.prop1 = "Hello" -- okay +test.prop1 = 68 -- okay, Lua converts the number to a string +test.prop2 = "bar" -- error: prop2 is not writable + +test.foo () -- calls foo and discards the return value +test.var1 = foo () -- calls foo and stores the result in var1 +test.bar ("Employee") -- calls bar with a string +test.bar (test) -- error: bar expects a string not a table +</pre> + +<p> +LuaBridge does not support overloaded functions nor is it likely to in the +future. Since Lua is dynamically typed, any system that tries to resolve a set +of parameters passed from a script will face considerable ambiguity when +trying to choose an appropriately matching C++ function signature. +</p> + +</section> + +<!--========================================================================--> + +<section> + +<h2>2.3 - <span id="s2.3">Class Objects</span></h2> + +<p> +A class registration is opened using either <code>beginClass</code> or +<code>deriveClass</code> and ended using <code>endClass</code>. Once +registered, a class can later be re-opened for more registrations using +<code>beginClass</code>. However, <code>deriveClass</code> should only be +used once. To add more registrations to an already registered derived class, +use <code>beginClass</code> on it. +</p> +<p> +These declarations: +</p> + +<pre> +struct A { + static int staticData; + static float staticProperty; + + static float getStaticProperty () { return staticProperty; } + static void setStaticProperty (float f) { staticProperty = f; } + static void staticFunc () { } + + static int staticCFunc (lua_State *L) { return 0; } + + std::string dataMember; + + char dataProperty; + char getProperty () const { return dataProperty; } + void setProperty (char v) { dataProperty = v; } + std::string toString () const { return dataMember; } + + void func1 () { } + virtual void virtualFunc () { } + + int cfunc (lua_State* L) { return 0; } +}; + +struct B : public A { + double dataMember2; + + void func1 () { } + void func2 () { } + void virtualFunc () { } +}; + +int A::staticData; +float A::staticProperty; +</pre> + +<p> +are registered using: +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test") + .beginClass <A> ("A") + .addStaticProperty ("staticData", &A::staticData) + .addStaticProperty ("staticProperty", &A::getStaticProperty, &A::setStaticProperty) + .addStaticFunction ("staticFunc", &A::staticFunc) + .addStaticFunction ("staticCFunc", &A::staticCFunc) + .addProperty ("data", &A::dataMember) + .addProperty ("prop", &A::getProperty, &A::setProperty) + .addFunction ("func1", &A::func1) + .addFunction ("virtualFunc", &A::virtualFunc) + .addFunction ("__tostring", &A::toString) // Metamethod + .addFunction ("cfunc", &A::cfunc) + .endClass () + .deriveClass <B, A> ("B") + .addProperty ("data", &B::dataMember2) + .addFunction ("func1", &B::func1) + .addFunction ("func2", &B::func2) + .endClass () + .endNameSpace (); +</pre> + +<p> +Method registration works just like function registration. Virtual methods +work normally; no special syntax is needed. const methods are detected and +const-correctness is enforced, so if a function returns a const object (or +a container holding to a const object) to Lua, that reference to the object +will be considered const and only const methods can be called on it. +It is possible to register Lua metamethods (except <code>__gc</code>). +Destructors are registered automatically for each class. +</p> + +<p> +As with regular variables and properties, class properties can be +marked read-only by passing false in the second parameter, or omitting the set +set function. The <code>deriveClass</code> takes two template arguments: the +class to be registered, and its base class. Inherited methods do not have to +be re-declared and will function normally in Lua. If a class has a base class +that is **not** registered with Lua, there is no need to declare it as a +subclass. +</p> + +<p> +Remember that in Lua, the colon operator '<code>:</code>' is used for +method call syntax: +</p> + +<pre> +local a = A () + +a.func1 () -- error: func1 expects an object of a registered class +a.func1 (a) -- okay, verbose, this how OOP works in Lua +a:func1 () -- okay, less verbose, equvalent to the previous +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h2>2.4 - <span id="s2.4">Property Member Proxies</span></h2> + +<p> +Sometimes when registering a class which comes from a third party library, the +data is not exposed in a way that can be expressed as a pointer to member, +there are no get or set functions, or the get and set functons do not have the +right function signature. Since the class declaration is closed for changes, +LuaBridge allows for a <em>property member proxy</em>. This is a pair of get +and set flat functions which take as their first parameter a pointer to +the object. This is easily understood with the following example: +</p> + +<pre> +// Third party declaration, can't be changed +struct Vec +{ + float coord [3]; +}; +</pre> + +<p> +Taking the address of an array element, e.g. <code>&Vec::coord [0]</code> +results in an error instead of a pointer-to-member. The class is closed for +modifications, but we want to export Vec objects to Lua using the familiar +object notation. To do this, first we add a "helper" class: +</p> + +<pre> +struct VecHelper +{ + template <unsigned index> + static float get (Vec const* vec) + { + return vec->coord [index]; + } + + template <unsigned index> + static void set (Vec* vec, float value) + { + vec->coord [index] = value; + } +}; +</pre> + +<p> +This helper class is only used to provide property member proxies. +<code>Vec</code> continues to be used in the C++ code as it was before. +Now we can register the <code>Vec</code> class with property member proxies for +<code>x</code>, <code>y</code>, and <code>z</code>: +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test") + .beginClass <Vec> ("Vec") + .addProperty ("x", &VecHelper::get <0>, &VecHelper::set <0>) + .addProperty ("y", &VecHelper::get <1>, &VecHelper::set <1>) + .addProperty ("z", &VecHelper::get <2>, &VecHelper::set <2>) + .endClass () + .endNamespace (); +</pre> + +<p> +With a C++11 compilant compiler it is possible to use <code>std::function</code> +instances as proxies: +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test") + .beginClass <Vec> ("Vec") + .addProperty ("x", + std::function <float (const Vec*)> ( + [] (const Vec* vec) {return vec->coord [0];}), + std::function <void (Vec*, float)> ( + [] (Vec* vec, float v) {vec->coord [0] = v;})) + // ... same for "y" and "z" + .endClass () + .endNamespace (); +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h2>2.5 - <span id="s2.5">Function Member Proxies</span></h2> + +<p> +Where it is not possible or inconvenient to add a member to be registered, +LuaBridge also allows for a <em>function member proxy</em>. This is a flat +function which take as its first parameter a pointer to the object: +</p> + +<pre> +// Third party declaration, can't be changed +struct Vec +{ + float coord [3]; +}; +</pre> + +<p> +The class is closed for modifications, but we want to extend Vec objects +with our member function. To do this, first we add a "helper" function: +</p> + +<pre> +void scale (float value) +{ + value->coord [0] *= value; + value->coord [1] *= value; + value->coord [2] *= value; +}; +</pre> + +<p> +Now we can register the <code>Vec</code> class with a member function +<code>scale</code>: +</p> + +<pre> +getGlobalNamespace (L) + .beginNamespace ("test") + .beginClass <Vec> ("Vec") + .addFunction ("scale", &scale) + .endClass () + .endNamespace (); +</pre> + +<p> +With a C++11 compilant compiler it is possible to use <code>std::function</code> +instances as proxies: +</p> + +<pre> +getGlobalNamespace (L) + .beginClass <Vec> ("Vec") + .addFunction ("scaleX", + std::function <void (Vec*, float)> ( + [] (Vec* vec, float v) {vec->coord [0] *= v;})) + .endClass () +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h2>2.6 - <span id="s2.6">Constructors</span></h2> + +<p> +A single constructor may be added for a class using <code>addConstructor</code>. +LuaBridge cannot automatically determine the number and types of constructor +parameters like it can for functions and methods, so you must provide them. +This is done by specifying the signature of the desired constructor function +as the first template parameter to <code>addConstructor</code>. The parameter +types will be extracted from this (the return type is ignored). For example, +these statements register constructors for the given classes: +</p> + +<pre> +struct A { + A (); +}; + +struct B { + explicit B (char const* s, int nChars); +}; + +getGlobalNamespace (L) + .beginNamespace ("test") + .beginClass <A> ("A") + .addConstructor <void (*) (void)> () + .endClass () + .beginClass <B> ("B") + .addConstructor <void (*) (char const*, int)> () + .endClass () + .endNamespace (); +</pre> + +<p> +Constructors added in this fashion are called from Lua using the fully +qualified name of the class. This Lua code will create instances of +<code>A</code> and <code>B</code>. +</p> + +<pre> +a = test.A () -- Create a new A. +b = test.B ("hello", 5) -- Create a new B. +b = test.B () -- Error: expected string in argument 1 +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h2>2.7 - <span id="s2.7">Lua Stack</span></h2> + +<p> +In the Lua C API, all operations on the <code>lua_State</code> are performed +through the Lua stack. In order to pass values back and forth between C++ +and Lua, LuaBridge uses specializations of this template class concept: +</p> + +<pre> +template <class T> +struct Stack +{ + static void push (lua_State* L, T t); + static T get (lua_State* L, int index); +}; +</pre> + +<p> +When a specialization of <code>Stack</code> exists for a given type +<code>T</code> we say that the <code>T</code> is <em>convertible</em>. +Throughout this document and the LuaBridge API, these types can be used +anywhere a convertible type is expected. +</p> + +<p> +The Stack template class specializations are used automatically for variables, +properties, data members, property members, function arguments and return +values. These basic types are supported: +</p> + +<ul class="bullets"> +<li><code>bool</code> +<li><code>char</code>, converted to a string of length one. +<li><code>char const*</code> and <code>std::string</code> strings. +<li>Integers, <code>float</code>, and <code>double</code>, + converted to <code>Lua_number</code>. +</ul> + +<p> +User-defined types which are convertible to one of the basic types are +possible, simply provide a <code>Stack<></code> specialization in the +<code>luabridge</code> namespace for your user-defined type, modeled after +the existing types. For example, here is a specialization for a +<code>juce::String</code>: +</p> + +<pre> +template <> +struct Stack <juce::String> +{ + static void push (lua_State* L, juce::String s) + { + lua_pushstring (L, s.toUTF8 ()); + } + + static juce::String get (lua_State* L, int index) + { + return juce::String (luaL_checkstring (L, index)); + } +}; +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h2>2.8 - <span id="s2.8">lua_State</span></h2> + +<p> +Sometimes it is convenient from within a bound function or member function +to gain access to the <code>lua_State*</code> normally available to a </code>lua_CFunction</code>. +With LuaBridge, all you need to do is add a <code>lua_State*</code> as the last +parameter of your bound function: +</p> + +<pre> +void useState (lua_State* L); + +getGlobalNamespace (L).addFunction ("useState", &useState); +</pre> + +<p> +You can still include regular arguments while receiving the state: +</p> + +<pre> +void useStateAndArgs (int i, std::string s, lua_State* L); + +getGlobalNamespace (L).addFunction ("useStateAndArgs", &useStateAndArgs); +</pre> + +<p> +When the script calls <code>useStateAndArgs</code>, it passes only the integer +and string parameters. LuaBridge takes care of inserting the <code>lua_State*</code> +into the argument list for the corresponding C++ function. This will work +correctly even for the state created by coroutines. Undefined behavior results +if the <code>lua_State*</code> is not the last parameter. +</p> + +<p> +The same is applicable for properies. +</p> + +</section> + +<!--========================================================================--> + +</section> + +<section> + +<h1>3 - <span id="s3">Passing Objects</span></h1> + +<p> +An object of a registered class <code>T</code> may be passed to Lua as: +</p> + +<table> +<tr> + <td><b><code>T</code></b></td> + <td>Passed by value (a copy), with <em>Lua lifetime</em>.</td> +</tr> +<tr> + <td><b><code>T const</code></b></td> + <td>Passed by value (a copy), with <em>Lua lifetime</em>.</td> +</tr> +<tr> + <td><b><code>T*</code></b></td> + <td>Passed by reference, with <em>C++ lifetime</em>.</td> +</tr> +<tr> + <td><b><code>T&</code></b></td> + <td>Passed by reference, with <em>C++ lifetime</em>.</td> +</tr> +<tr> + <td><b><code>T const*</code></b></td> + <td>Passed by const reference, with <em>C++ lifetime</em>.</td> +</tr> +<tr> + <td><b><code>T const&</code></b></td> + <td>Passed by const reference, with <em>C++ lifetime</em>.</td> +</tr> +</table> + +<!--========================================================================--> + +<section> + +<h2>3.1 - <span id="s3.1">C++ Lifetime</span></h2> + +<p> +The creation and deletion of objects with <em>C++ lifetime</em> is controlled by +the C++ code. Lua does nothing when it garbage collects a reference to such an +object. Specifically, the object's destructor is not called (since C++ owns +it). Care must be taken to ensure that objects with C++ lifetime are not +deleted while still being referenced by a <code>lua_State*</code>, or else +undefined behavior results. In the previous examples, an instance of <code>A</code> +can be passed to Lua with C++ lifetime, like this: +</p> + +<pre> +A a; + +push (L, &a); // pointer to 'a', C++ lifetime +lua_setglobal (L, "a"); + +push (L, (A const*)&a); // pointer to 'a const', C++ lifetime +lua_setglobal (L, "ac"); + +push <A const*> (L, &a); // equivalent to push (L, (A const*)&a) +lua_setglobal (L, "ac2"); + +push (L, new A); // compiles, but will leak memory +lua_setglobal (L, "ap"); +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h2>3.2 - <span id="s3.2">Lua Lifetime</span></h2> + +<p> +When an object of a registered class is passed by value to Lua, it will have +<em>Lua lifetime</em>. A copy of the passed object is constructed inside the +userdata. When Lua has no more references to the object, it becomes eligible +for garbage collection. When the userdata is collected, the destructor for +the class will be called on the object. Care must be taken to ensure that +objects with Lua lifetime are not accessed by C++ after they are garbage +collected, or else undefined behavior results. An instance of <code>B</code> +can be passed to Lua with Lua lifetime this way: +</p> + +<pre> +B b; + +push (L, b); // Copy of b passed, Lua lifetime. +lua_setglobal (L, "b"); +</pre> + +<p> +Given the previous code segments, these Lua statements are applicable: +</p> + +<pre> +print (test.A.staticData) -- Prints the static data member. +print (test.A.staticProperty) -- Prints the static property member. +test.A.staticFunc () -- Calls the static method. + +print (a.data) -- Prints the data member. +print (a.prop) -- Prints the property member. +a:func1 () -- Calls A::func1 (). +test.A.func1 (a) -- Equivalent to a:func1 (). +test.A.func1 ("hello") -- Error: "hello" is not a class A. +a:virtualFunc () -- Calls A::virtualFunc (). + +print (b.data) -- Prints B::dataMember. +print (b.prop) -- Prints inherited property member. +b:func1 () -- Calls B::func1 (). +b:func2 () -- Calls B::func2 (). +test.B.func2 (a) -- Error: a is not a class B. +test.A.func1 (b) -- Calls A::func1 (). +b:virtualFunc () -- Calls B::virtualFunc (). +test.B.virtualFunc (b) -- Calls B::virtualFunc (). +test.A.virtualFunc (b) -- Calls B::virtualFunc (). +test.B.virtualFunc (a) -- Error: a is not a class B. + +a = nil; collectgarbage () -- 'a' still exists in C++. +b = nil; collectgarbage () -- Lua calls ~B() on the copy of b. +</pre> + +<p> +When Lua script creates an object of class type using a registered +constructor, the resulting value will have Lua lifetime. After Lua no longer +references the object, it becomes eligible for garbage collection. You can +still pass these to C++, either by reference or by value. If passed by +reference, the usual warnings apply about accessing the reference later, +after it has been garbage collected. +</p> + +</section> + +<!--========================================================================--> + +<section> + +<h2>3.3 - <span id="s3.3">Pointers, References, and Pass by Value</span></h2> + +<p> +When C++ objects are passed from Lua back to C++ as arguments to functions, +or set as data members, LuaBridge does its best to automate the conversion. +Using the previous definitions, the following functions may be registered +to Lua: +</p> + +<pre> +void func0 (A a); +void func1 (A* a); +void func2 (A const* a); +void func3 (A& a); +void func4 (A const& a); +</pre> + +<p> +Executing this Lua code will have the prescribed effect: +</p> + +<pre> +func0 (a) -- Passes a copy of a, using A's copy constructor. +func1 (a) -- Passes a pointer to a. +func2 (a) -- Passes a pointer to a const a. +func3 (a) -- Passes a reference to a. +func4 (a) -- Passes a reference to a const a. +</pre> + +<p> +In the example above, all functions can read the data members and property +members of <code>a</code>, or call const member functions of <code>a</code>. +Only <code>func0</code>, <code>func1</code>, and <code>func3</code> can +modify the data members and data properties, or call non-const member +functions of <code>a</code>. +</p> + +<p> +The usual C++ inheritance and pointer assignment rules apply. Given: +</p> + +<pre> +void func5 (B b); +void func6 (B* b); +</pre> + +<p> +These Lua statements hold: +</p> + +<pre> +func5 (b) - Passes a copy of b, using B's copy constructor. +func6 (b) - Passes a pointer to b. +func6 (a) - Error: Pointer to B expected. +func1 (b) - Okay, b is a subclass of a. +</pre> + +<p> +When a pointer or pointer to const is passed to Lua and the pointer is null +(zero), LuaBridge will pass Lua a <code>nil</code> instead. When Lua passes a +<code>nil</code> to C++ where a pointer is expected, a null (zero) is passed +instead. Attempting to pass a null pointer to a C++ function expecting a +reference results in <code>lua_error</code> being called. +</p> + +</section> + +<!--========================================================================--> + +<section> + +<h2>3.4 - <span id="s3.4">Shared Lifetime</span></h2> + +<p> +LuaBridge supports a <em>shared lifetime</em> model: dynamically allocated +and reference counted objects whose ownership is shared by both Lua and C++. +The object remains in existence until there are no remaining C++ or Lua +references, and Lua performs its usual garbage collection cycle. A container +is recognized by a specialization of the <code>ContainerTraits</code> +template class. LuaBridge will automatically recognize when a data type is +a container when the correspoding specialization is present. Two styles of +containers come with LuaBridge, including the necessary specializations. +</p> + +<!--========================================================================--> + +<section> + +<h3>3.4.1 - <span id="s3.4.1">Class RefCountedObjectPtr</span></h3> + +<p> +This is an intrusive style container. Your existing class declaration must be +changed to be also derived from <code>RefCountedObject</code>. Given +<code>class T</code>, derived from <code>RefCountedObject</code>, the container +<code>RefCountedObjectPtr <T></code> may be used. In order for +reference counts to be maintained properly, all C++ code must store a +container instead of the pointer. This is similar in style to +<code>std::shared_ptr</code> although there are slight differences. For +example: +</p> + +<pre> +// A is reference counted. +struct A : public RefCountedObject +{ + void foo () { } +}; + +struct B +{ + RefCountedObjectPtr <A> a; // holds a reference to A +}; + +void bar (RefCountedObjectPtr <A> a) +{ + a->foo (); +} +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h3>3.4.2 - <span id="s3.4.2">Class RefCountedPtr</span></h3> + +<p> +This is a non intrusive reference counted pointer. The reference counts are +kept in a global hash table, which does incur a small performance penalty. +However, it does not require changing any already existing class declarations. +This is especially useful when the classes to be registered come from a third +party library and cannot be modified. To use it, simply wrap all pointers +to class objects with the container instead: +</p> + +<pre> +struct A +{ + void foo () { } +}; + +struct B +{ + RefCountedPtr <A> a; +}; + +RefCountedPtr <A> createA () +{ + return new A; +} + +void bar (RefCountedPtr <A> a) +{ + a->foo (); +} + +void callFoo () +{ + bar (createA ()); + + // The created A will be destroyed + // when we leave this scope +} +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h3>3.4.3 - <span id="s3.4.3">User-defined Containers</span></h3> + +<p> +If you have your own container, you must provide a specialization of +<code>ContainerTraits</code> in the <code>luabridge</code> namespace for your +type before it will be recognized by LuaBridge (or else the code will not +compile): +</p> + +<pre> +template <class T> +struct ContainerTraits <CustomContainer <T> > +{ + typedef typename T Type; + + static T* get (CustomContainer <T> const& c) + { + return c.getPointerToObject (); + } +}; +</pre> + +<p> +Standard containers like <code>std::shared_ptr</code> or +<code>boost::shared_ptr</code> <b>will not work</b>. This is because of type +erasure; when the object goes from C++ to Lua and back to C++, there is no +way to associate the object with the original container. The new container is +constructed from a pointer to the object instead of an existing container. +The result is undefined behavior since there are now two sets of reference +counts. +</p> + +</section> + +<!--========================================================================--> + +<section> + +<h3>3.4.4 - <span id="s3.4.4">Container Constructors</span></h3> + +<p> +When a constructor is registered for a class, there is an additional +optional second template parameter describing the type of container to use. +If this parameter is specified, calls to the constructor will create the +object dynamically, via operator new, and place it a container of that +type. The container must have been previously specialized in +<code>ContainerTraits</code>, or else a compile error will result. This code +will register two objects, each using a constructor that creates an object +with Lua lifetime using the specified container: +</p> + +<pre> +class C : public RefCountedObject +{ + C () { } +}; + +class D +{ + D () { } +}; + +getGlobalNamespace (L) + .beginNamespace ("test") + .beginClass <C> ("C") + .addConstructor <void (*) (void), RefCountedObjectPtr <C> > () + .endClass () + .beginClass <D> ("D") + .addConstructor <void (*) (void), RefCountedPtr <D> > () + .endClass (); + .endNamespace () +</pre> + +</section> + +<!--========================================================================--> + +</section> + +<section> + +<h2>3.5 - <span id="s3.5">Mixing Lifetimes</span></h2> + +<p> +Mixing object lifetime models is entirely possible, subject to the usual +caveats of holding references to objects which could get deleted. For +example, C++ can be called from Lua with a pointer to an object of class +type; the function can modify the object or call non-const data members. +These modifications are visible to Lua (since they both refer to the same +object). An object store in a container can be passed to a function expecting +a pointer. These conversion work seamlessly. +<p> + +</section> + +<!--========================================================================--> + +<section> + +<h2>3.6 - <span id="s3.6">Convenience Functions</span></h2> + +<p> +The <code>setGlobal</code> function can be used to assign any convertible +value into a global variable. +</p> + +</section> + +<!--========================================================================--> + +</section> + +<section> + +<h1>4 - <span id="s4">Accessing Lua from C++</span></h1> + +<p> +Because Lua is a <em>dynamically typed language</em>, special consideration +is required to map values in Lua to C++. The following sections describe the +classes and functions used for representing Lua types. Only the essential +operations are explained; To gain understanding of all available functions, +please refer to the documentation comments in the corresponding source files. +</p> + +<!--========================================================================--> + +<section> + +<h2>4.1 - <span id="s4.1">Class LuaRef</span></h2> + +<p> +The <code>LuaRef</code> class is a container which references any Lua type. +It can hold anything which a Lua variable can hold: <strong>nil</strong>, +number, boolean, string, table, function, thread, userdata, and +lightuserdata. Because <code>LuaRef</code> uses the <code>Stack</code> +template specializations to do its work, classes, functions, and data +exported to Lua through namespace registrations can also be stored (these +are instances of userdata). In general, a <code>LuaRef</code> can represent +any <em>convertible</em> C++ type as well as all Lua types. +</p> + +<p> +A <code>LuaRef</code> variable constructed with no parameters produces a +reference to <strong>nil</strong>: +</p> + +<pre> +LuaRef v (L); // References nil +</pre> + +<p> +To construct a <code>LuaRef</code> to a specific value, the two parameter +constructor is used: +</p> + +<pre> +LuaRef v1 (L, 1); // A LUA_TNUMBER +LuaRef v2 (L, 1.1); // Also a LUA_TNUMBER +LuaRef v3 (L, true); // A LUA_TBOOLEAN +LuaRef v4 (L, "string"); // A LUA_TSTRING +</pre> + +<p> +The functions <code>newTable</code> and <code>getGlobal</code> create +references to new empty table and an existing value in the global table +respectively: +</p> + +<pre> +LuaRef v1 = newTable (L); // Create a new table +LuaRef v2 = getGlobal (L, "print") // Reference to _G ["print"] +</pre> + +<p> +A <code>LuaRef</code> can hold classes <em>registered</em> using LuaBridge: +</p> + +<pre> +class A; +//... +LuaRef v (L, new A); // A LuaBridge userdata holding a pointer to A +</pre> + +<p> +Any convertible type may be assigned to an already-existing <code>LuaRef</code>: +</p> + +<pre> +LuaRef v (L); // Nil +v = newTable (L); // An empty table +v = "string" // A string. The prevous value becomes + // eligible for garbage collection. +</pre> + +<p> +A <code>LuaRef</code> is itself a convertible type, and the convertible +type <code>Nil</code> can be used to represent a Lua <strong>nil</strong>. +</p> + +<pre> +LuaRef v1 (L, "x"); // assign "x" +LuaRef v2 (L, "y"); // assign "y" +v2 = v1; // v2 becomes "x" +v1 = "z"; // v1 becomes "z", v2 is unchanged +v1 = newTable (L); // An empty table +v2 = v1; // v2 references the same table as v1 +v1 = Nil (); // v1 becomes nil, table is still + // referenced by v2. +</pre> + +<p> +Values stored in a <code>LuaRef</code> object obey the same rules as +variables in Lua: tables, functions, threads, and full userdata values are +<em>objects</em>. The <code>LuaRef</code> does not actually <em>contain</em> +these values, only <em>references</em> to them. Assignment, parameter +passing, and function returns always manipulate references to such values; +these operations do not imply any kind of copy. +</p> + +<!--========================================================================--> + +<section> + +<h3>4.1.1 - <span id="s4.1.1">Type Conversions</span></h3> + +<p> +A universal C++ conversion operator is provided for implicit conversions +which allow a <code>LuaRef</code> to be used where any convertible type is +expected. These operations will all compile: +</p> + +<pre> +void passInt (int); +void passBool (bool); +void passString (std::string); +void passObject (A*); + +LuaRef v (L); +//... +passInt (v); // implicit conversion to int +passBool (v); // implicit conversion to bool +passString (v); // implicit conversion to string +passObject (v); // must hold a registered LuaBridge class or a + // lua_error() will be called. +</pre> + +<p> +Since Lua types are dynamic, the conversion is performed at run time using +traditional functions like <code>lua_toboolean</code> or +<code>lua_tostring</code>. In some cases, the type information may be +incorrect especially when passing objects of registered class types. +When performing these conversions, LuaBridge may raise a Lua error by +directly or indirectly calling <code>lua_error</code> To be bullet-proof, +such code must either be wrapped in a <code>lua_pcall</code>, or you must +install a Lua <em>panic function</em> that throws an exception which you +can catch. +</p> + +<p> +When an explicit conversion is required (such as when writing templates), +use the <code>cast</code> template function or an explicit C++ style cast. +</p> + +<pre> +void passString (std::string); + +LuaRef v (L); + +// The following are all equivalent: + +passString (std::string (v)); +passString ((std::string)v); +passString (static_cast <std::string> (v)); +passString (v.cast <std::string> ()); +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h3>4.1.2 - <span id="s4.1.2">Visual Studio 2010, 2012</span></h3> + +<p> +There is a defect with all versions of Visual Studio up to and including +Visual Studio 2012 which prevents the implicit conversion operator from +being applied when it is used as an operand in a boolean operator: +</p> + +<pre> +LuaRef v1 (L); +LuaRef v2 (L); + +if (v1 || v2) { } // Compile error in Visual Studio + +// Work-arounds: +if (v1.cast <bool> () || v2.cast <bool> ()) { } +if (bool (v1) || bool (v2)) { } +</pre> + +</section> + +<!--========================================================================--> + +</section> + +<section> + +<h2>4.2 - <span id="s4.2">Table Proxies</span></h2> + +<p> +As tables are the sole data structuring mechanism in Lua, the +<code>LuaRef</code> class provides robust facilities for accessing and +manipulating table elements using a simple, precise syntax. Any convertible +type may be used as a key or value. Applying the array indexing operator +<code>[]</code> to a <code>LuaRef</code> returns a special temporary object +called a <em>table proxy</em> which supports all the operations which can +be performed on a <code>LuaRef</code>. In addition, assignments made to +table proxies change the underlying table. Because table proxies are +compiler-created temporary objects, you don't work with them directly. A +LuaBridge table proxy should not be confused with the Lua proxy table +technique described in the book "Programming in Lua"; the LuaBridge table +proxy is simply an intermediate C++ class object that works behind the +scenes to make table manipulation syntax conform to C++ idioms. These +operations all invoke table proxies: +</p> + +<pre> +LuaRef v (L); +v = newTable (L); + +v ["name"] = "John Doe"; // string key, string value +v [1] = 200; // integer key, integer value +v [2] = newTable (L); // integer key, LuaRef value +v [3] = v [1]; // assign 200 to integer index 3 +v [1] = 100; // v[1] is 100, v[3] is still 200 +v [3] = v [2]; // v[2] and v[3] reference the same table +v [2] = Nil (); // Removes the value with key = 2. The table + // is still referenced by v[3]. +</pre> + +</section> + +<!--========================================================================--> + +<section> + +<h2>4.3 - <span id="s4.3">Calling Lua</span></h2> + +<p> +Table proxies and <code>LuaRef</code> objects provide a convenient syntax +for invoking <code>lua_pcall</code> on suitable referenced object. This +includes C functions, Lua functions, or Lua objects with an appropriate +<code>__call</code> metamethod set. The provided implementation supports +up to eight parameters (although more can be supported by adding new +functions). Any convertible C++ type can be passed as a parameter in its +native format. The return value of the function call is provided as a +<code>LuaRef</code>, which may be <strong>nil</strong>. +</p> + +<pre class="split"> +LuaRef same = getGlobal (L, "same"); + +// These all evaluate to true +same (1,1); +!same (1,2); +same ("text", "text"); +!same (1, "text"); +same (1, 1, 2); // third param ignored +</pre> + +<pre class="split"> +function same (arg1, arg) + return arg1 == arg2 +end +</pre> + +<p> +Table proxies support all of the Lua call notation that <code>LuaRef</code> +supports, making these statements possible: +</p> + +<pre class="split"> +LuaRef v = getGlobal (L, "t"); + +t[1](); +t[2]("a", "b"); +t[2](t[1]); // Call t[3] with the value in t[2] +t[4]=t[3](); // Call t[3] and store the result in t[4]. + +t [t[5]()] = "wow"; // Store "wow" at the key returned by + // the call to t[5] +</pre> + +<pre class="split"> +t = {} +t[1] = function () print ("hello") end +t[2] = function (u, v) print (u, v) end +t[3] = "foo" +</pre> + +<!--========================================================================--> + +<h3>4.3.1 - <span id="s4.3.1">Class LuaException</span></h3> + +<section > + +<p> +When <code>LuaRef</code> is used to call into Lua using the <code>()</code> +operator it issues a protected call using <code>lua_pcall</code>. LuaBridge +uses the C++ exception handling mechanism, throwing a <code>LuaException</code> +object: +</p> + +<pre class="split"> +LuaRef f (L) = getGlobal (L, "fail"); + +try { + f (); +} +catch (LuaException const& e) { + std::cerr && e.what (); +} +</pre> + +<pre class="split"> +function fail () + error ("A problem occurred") +end +</pre> + +</section> + +<!--========================================================================--> + +</section> + +<!--========================================================================--> + +</section> + +<section> + +<h1>5 - <span id="s5">Security</span></h1> + +<p> +The metatables and userdata that LuaBridge creates in the <code>lua_State*</code> are +protected using a security system, to eliminate the possibility of undefined +behavior resulting from scripted manipulation of the environment. The +security system has these components: +</p> + +<ul class="bullets"> +<li> +Class and const class tables use the <em>table proxy</em> technique. The +corresponding metatables have <code>__index</code> and <code>__newindex</code> +metamethods, so these class tables are immutable from Lua. +<li> +Metatables have <code>__metatable</code> set to a boolean value. Scripts +cannot obtain the metatable from a LuaBridge object. +<li> +Classes are mapped to metatables through the registry, which Lua scripts +cannot access. The global environment does not expose metatables +<li> +Metatables created by LuaBridge are tagged with a lightuserdata key which +is unique in the process. Other libraries cannot forge a LuaBridge +metatable. +</ul> + +<p> +This security system can be easily bypassed if scripts are given access to +the debug library (or functionality similar to it, i.e. a raw <code>getmetatable</code>). +The security system can also be defeated by C code in the host, either by +revealing the unique lightuserdata key to another module or by putting a +LuaBridge metatable in a place that can be accessed by scripts. +</p> + +<p> +When a class member function is called, or class property member accessed, +the <code>this</code> pointer is type-checked. This is because member functions exposed +to Lua are just plain functions that usually get called with the Lua colon +notation, which passes the object in question as the first parameter. Lua's +dynamic typing makes this type-checking mandatory to prevent undefined +behavior resulting from improper use. +</p> + +<p> +If a type check error occurs, LuaBridge uses the <code>lua_error</code> +mechanism to trigger a failure. A host program can always recover from +an error through the use of <code>lua_pcall</code>; proper usage of +LuaBridge will never result in undefined behavior. +</p> + +</section> + +<!--========================================================================--> + +</body> +</html> + |