WebSVN – NedoOS – /tools/src/sjasmplus/LuaBridge/Manual.html

<!doctype html>
<html>
<head>
<title>LuaBridge 2.8 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.8 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>
<p>
<li><a href="#appendix">Appendix - API Reference</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>C++11 compliant.</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::array</code>, <code>std::map</code>, <code>std::unordered_map</code>
or <code>std::optional</code> by including <code>List.h</code>,
<code>Vector.h</code>, <code>Array.h</code>, <code>Map.h</code>,
<code>UnorderedMap.h</code> or <code>Optional.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>.
</p>
<p>
The <b>master</b> branch contains published library versions. Release versions are marked with tags.
</p>
<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>
It is also 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>
It is also 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);
static bool isInstance (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));
}
static bool isInstance (lua_State* L, int index)
{
return lua_type (L, index) == LUA_TSTRING;
}
};
</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>
<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>
<section>
<h1>Appendix - <span id="appendix">API Reference</span></h1>
<h2>Free Functions</h2>
<pre>
/// Gets a global Lua variable reference.
///
LuaRef getGlobal(lua_State* L, const char* name);
</pre>
<pre>
/// Sets a global Lua variable.
///
template<class V>
void setGlobal(lua_State* L, V* varPtr, const char* name);
</pre>
<pre>
/// Gets the global namespace registration object.
///
Namespace getGlobalNamespace(lua_State* L);
</pre>
<h2>Namespace Registration - Namespace</h2>
<pre>
/// Begins or continues class registration, returns this class object.
///
template<class T>
Class<T> beginClass(const char* name);
</pre>
<pre>
/// Begins derived class registration, returns this class object.
///
template<class T, class Base>
Class<T> deriveClass(const char* name);
</pre>
<pre>
/// Begin or continues namespace registration, returns this namespace object.
///
template<class T>
Namespace beginNamespace(const char* name);
</pre>
<pre>
/// Ends namespace registration, returns the parent namespace object.
///
template<class T>
Namespace endNamespace();
</pre>
<pre>
/// Registers a function.
///
template<class R, class... Params>>
Namespace addFunction(const char* name,
R (*fn)(Params...));
</pre>
<pre>
/// Registers a function.
///
template<class R, class... Params>>
Namespace addFunction(const char* name,
std::function<R (Params...)> fn);
</pre>
<pre>
/// Registers a function with an extra Lua state parameter.
///
template<class R, class... Params>>
Namespace addFunction(const char* name,
R (*fn)(Params..., lua_State*))
</pre>
<pre>
/// Registers a C-function.
///
Namespace addFunction(const char* name,
int (*fn)(lua_State*));
</pre>
<pre>
/// Registers a property with a getter and setter.
///
template<class V>
Namespace addProperty(const char* name,
V (*getFn)(),
void (*setFn)(V));
</pre>
<pre>
/// Registers a property with a getter and setter.
///
template<class V>
Namespace addProperty(const char* name,
std::function<V ()> getFn,
std::function<void (V)> setFn);
</pre>
<pre>
/// Registers a property with a C-function getter and setter.
///
Namespace addProperty(const char* name,
int (*getFn)(lua_State*),
int (*setFn)(lua_State*));
</pre>
<pre>
/// Registers a read-only property with a getter function.
///
template<class V>
Namespace addProperty(const char* name,
V (*getFn)());
</pre>
<pre>
/// Registers a read-only property with a getter function.
///
template<class V>
Namespace addProperty(const char* name,
std::function<V ()> getFn);
</pre>
<pre>
/// Registers a read-only property with a C-function getter.
///
Namespace addProperty(const char* name,
int (*getFn)(lua_State*));
</pre>
<pre>
/// Registers a variable, writable or read-only.
///
template<class V>
Namespace addVariable(const char* name,
V* varPtr,
bool isWritable = true);
</pre>
<h2>Class Registration - Class<T></h2>
<pre>
/// Ends class registration, returns the parent namespace object.
///
template<class T>
Namespace endClass();
</pre>
<h3>Member Function Registration</h3>
<pre>
/// Registers a member function.
///
template<class R, class... Params>>
Namespace addFunction(const char* name,
R (T::* fn)(Params...));
</pre>
<pre>
/// Registers a function.
///
template<class R, class... Params>>
Namespace addFunction(const char* name,
std::function<R (Params...)> fn);
</pre>
<pre>
/// Registers a function with an extra Lua state parameter.
///
template<class R, class... Params>>
Namespace addFunction(const char* name,
R (T::* fn)(Params..., lua_State*))
</pre>
<pre>
/// Registers a C-function.
///
Namespace addFunction(const char* name,
int (*fn)(lua_State*));
</pre>
<h3>Member Property Registration</h3>
<pre>
/// Registers a property with a getter and setter.
///
template<class V>
Namespace addProperty(const char* name,
V (T::* getFn)(),
void (T::* setFn)(V));
</pre>
<pre>
/// Registers a property with a getter and setter.
///
template<class V>
Namespace addProperty(const char* name,
std::function<V ()> getFn,
std::function<void (V)> setFn);
</pre>
<pre>
/// Registers a property with a C-function getter and setter.
///
Namespace addProperty(const char* name,
int (*getFn)(lua_State*),
int (*setFn)(lua_State*));
</pre>
<pre>
/// Registers a read-only property with a getter member function.
///
template<class V>
Namespace addProperty(const char* name,
V (T::* getFn)());
</pre>
<pre>
/// Registers a read-only property with a getter function.
///
template<class V>
Namespace addProperty(const char* name,
std::function<V ()> getFn);
</pre>
<pre>
/// Registers a read-only property with a C-function getter.
///
Namespace addProperty(const char* name,
int (*getFn)(lua_State*));
</pre>
<pre>
/// Registers a member variable, writable or read-only.
///
template<class V>
Namespace addData(const char* name,
V T::* varPtr,
bool isWritable = true);
</pre>
<h3>Static Function Registration</h3>
<pre>
/// Registers a function.
///
template<class R, class... Params>>
Namespace addStaticFunction(const char* name,
R (*fn)(Params...));
</pre>
<pre>
/// Registers a function.
///
template<class R, class... Params>>
Namespace addStaticFunction(const char* name,
std::function<R (Params...)> fn);
</pre>
<pre>
/// Registers a function with an extra Lua state parameter.
///
template<class R, class... Params>>
Namespace addStaticFunction(const char* name,
R (*fn)(Params..., lua_State*))
</pre>
<pre>
/// Registers a C-function.
///
Namespace addStaticFunction(const char* name,
int (*fn)(lua_State*));
</pre>
<h3>Static Property Registration</h3>
<pre>
/// Registers a property with a getter and setter.
///
template<class V>
Namespace addStaticProperty(const char* name,
V (*getFn)(),
void (*setFn)(V));
</pre>
<pre>
/// Registers a property with a getter and setter.
///
template<class V>
Namespace addStaticProperty(const char* name,
std::function<V ()> getFn,
std::function<void (V)> setFn);
</pre>
<pre>
/// Registers a property with a C-function getter and setter.
///
Namespace addStaticProperty(const char* name,
int (*getFn)(lua_State*),
int (*setFn)(lua_State*));
</pre>
<pre>
/// Registers a read-only property with a getter function.
///
template<class V>
Namespace addStaticProperty(const char* name,
V (*getFn)());
</pre>
<pre>
/// Registers a read-only property with a getter function.
///
template<class V>
Namespace addStaticProperty(const char* name,
std::function<V ()> getFn);
</pre>
<pre>
/// Registers a read-only property with a C-function getter.
///
Namespace addStaticProperty(const char* name,
int (*getFn)(lua_State*));
</pre>
<pre>
/// Registers a variable, writable or read-only.
///
Namespace addStaticData(const char* name,
T* varPtr,
bool isWritable = true);
</pre>
<h2>Lua Variable Reference - LuaRef</h2>
<pre>
/// Creates a nil reference.
///
LuaRef(lua_State* L);
</pre>
<pre>
/// Returns native Lua string representation.
///
std::string tostring() const;
</pre>
<pre>
/// Dumps reference to a stream.
///
void print(std::ostream& stream) const;
</pre>
<pre>
/// Returns the Lua state.
///
lua_State* state() const;
</pre>
<pre>
/// Place the object onto the Lua stack.
///
void push(lua_State* L);
</pre>
<pre>
/// Return the lua_type.
///
int type() const;
</pre>
<pre>
/// Perform the explicit type conversion.
///
template<class T>
T cast() const;
</pre>
<pre>
/// Check if the Lua value is convertible to the type T.
///
template<class T>
bool isInstance() const;
</pre>
<h2>Stack Traits - Stack<T></h2>
<pre>
/// Converts the C++ value into the Lua value at the top of the Lua stack.
///
void put (lua_State* L, T value);
</pre>
<pre>
/// Converts the Lua value at the index into the C++ value of the type T.
///
T get (lua_State* L, int index);
</pre>
<pre>
/// Checks if the Lua value at the index is convertible into the C++ value of the type T.
///
bool isInstance (lua_State* L, int index);
</pre>
</section>
</body>
</html>

Subversion Repositories NedoOS

(root)/tools/src/sjasmplus/LuaBridge/Manual.html @ 2087 – Rev 1537