docs.html.svn-base

来自「本人找过多个在linux下c++的lua5.1封装库,但很少.luabind已经」· SVN-BASE 代码 · 共 1,535 行 · 第 1/5 页

<pre class="literal-block">
module(L, &quot;my_library&quot;)
[
    // declarations

    namespace_(&quot;detail&quot;)
    [
        // library-private declarations
    ]
];
</pre>
<p>As you might have figured out, the following declarations are equivalent:</p>
<pre class="literal-block">
module(L)
[
    namespace_(&quot;my_library&quot;)
    [
        // declarations
    ]

];
</pre>
<pre class="literal-block">
module(L, &quot;my_library&quot;)
[
    // declarations
];
</pre>
<p>Each declaration must be separated by a comma, like this:</p>
<pre class="literal-block">
module(L)
[
    def(&quot;f&quot;, &amp;f),
    def(&quot;g&quot;, &amp;g),
    class_&lt;A&gt;(&quot;A&quot;)
        .def(constructor&lt;int, int&gt;),
    def(&quot;h&quot;, &amp;h)
];
</pre>
<p>More about the actual declarations in the <a class="reference" href="#binding-functions-to-lua">Binding functions to Lua</a> and
<a class="reference" href="#binding-classes-to-lua">Binding classes to Lua</a> sections.</p>
<p>A word of caution, if you are in really bad need for performance, putting your
functions in tables will increase the lookup time.</p>
</div>
<div class="section">
<h1><a id="binding-functions-to-lua" name="binding-functions-to-lua">7&nbsp;&nbsp;&nbsp;Binding functions to Lua</a></h1>
<p>To bind functions to Lua you use the function <tt class="docutils literal"><span class="pre">luabind::def()</span></tt>. It has the
following synopsis:</p>
<pre class="literal-block">
template&lt;class F, class policies&gt;
void def(const char* name, F f, const Policies&amp;);
</pre>
<ul class="simple">
<li>name is the name the function will have within Lua.</li>
<li>F is the function pointer you want to register.</li>
<li>The Policies parameter is used to describe how parameters and return values
are treated by the function, this is an optional parameter. More on this in
the <a class="reference" href="#policies">policies</a> section.</li>
</ul>
<p>An example usage could be if you want to register the function <tt class="docutils literal"><span class="pre">float</span>
<span class="pre">std::sin(float)</span></tt>:</p>
<pre class="literal-block">
module(L)
[
    def(&quot;sin&quot;, &amp;std::sin)
];
</pre>
<div class="section">
<h2><a id="overloaded-functions" name="overloaded-functions">7.1&nbsp;&nbsp;&nbsp;Overloaded functions</a></h2>
<p>If you have more than one function with the same name, and want to register
them in Lua, you have to explicitly give the signature. This is to let C++ know
which function you refer to. For example, if you have two functions, <tt class="docutils literal"><span class="pre">int</span>
<span class="pre">f(const</span> <span class="pre">char*)</span></tt> and <tt class="docutils literal"><span class="pre">void</span> <span class="pre">f(int)</span></tt>.</p>
<pre class="literal-block">
module(L)
[
    def(&quot;f&quot;, (int(*)(const char*)) &amp;f),
    def(&quot;f&quot;, (void(*)(int)) &amp;f)
];
</pre>
</div>
<div class="section">
<h2><a id="signature-matching" name="signature-matching">7.2&nbsp;&nbsp;&nbsp;Signature matching</a></h2>
<p>luabind will generate code that checks the Lua stack to see if the values there
can match your functions' signatures. It will handle implicit typecasts between
derived classes, and it will prefer matches with the least number of implicit
casts. In a function call, if the function is overloaded and there's no
overload that match the parameters better than the other, you have an
ambiguity. This will spawn a run-time error, stating that the function call is
ambiguous. A simple example of this is to register one function that takes an
int and one that takes a float. Since Lua doesn't distinguish between floats and
integers, both will always match.</p>
<p>Since all overloads are tested, it will always find the best match (not the
first match). This also means that it can handle situations where the only
difference in the signature is that one member function is const and the other
isn't.</p>
<div class="sidebar">
<p class="first sidebar-title">Ownership transfer</p>
<p class="last">To correctly handle ownership transfer, create_a() would need an adopt
return value policy. More on this in the <a class="reference" href="#policies">Policies</a> section.</p>
</div>
<p>For example, if the following function and class is registered:</p>
<pre class="literal-block">
struct A
{
    void f();
    void f() const;
};

const A* create_a();

struct B: A {};
struct C: B {};

void g(A*);
void g(B*);
</pre>
<p>And the following Lua code is executed:</p>
<pre class="literal-block">
a1 = create_a()
a1:f() -- the const version is called

a2 = A()
a2:f() -- the non-const version is called

a = A()
b = B()
c = C()

g(a) -- calls g(A*)
g(b) -- calls g(B*)
g(c) -- calls g(B*)
</pre>
</div>
<div class="section">
<h2><a id="calling-lua-functions" name="calling-lua-functions">7.3&nbsp;&nbsp;&nbsp;Calling Lua functions</a></h2>
<p>To call a Lua function, you can either use <tt class="docutils literal"><span class="pre">call_function()</span></tt> or
an <tt class="docutils literal"><span class="pre">object</span></tt>.</p>
<pre class="literal-block">
template&lt;class Ret&gt;
Ret call_function(lua_State* L, const char* name, ...)
template&lt;class Ret&gt;
Ret call_function(object const&amp; obj, ...)
</pre>
<p>There are two overloads of the <tt class="docutils literal"><span class="pre">call_function</span></tt> function, one that calls
a function given its name, and one that takes an object that should be a Lua
value that can be called as a function.</p>
<p>The overload that takes a name can only call global Lua functions. The ...
represents a variable number of parameters that are sent to the Lua
function. This function call may throw <tt class="docutils literal"><span class="pre">luabind::error</span></tt> if the function
call fails.</p>
<p>The return value isn't actually Ret (the template parameter), but a proxy
object that will do the function call. This enables you to give policies to the
call. You do this with the operator[]. You give the policies within the
brackets, like this:</p>
<pre class="literal-block">
int ret = call_function&lt;int&gt;(
    L
  , &quot;a_lua_function&quot;
  , new complex_class()
)[ adopt(_1) ];
</pre>
<p>If you want to pass a parameter as a reference, you have to wrap it with the
<a class="reference" href="http://www.boost.org/doc/html/ref.html">Boost.Ref</a>.</p>
<p>Like this:</p>
<pre class="literal-block">
int ret = call_function(L, &quot;fun&quot;, boost::ref(val));
</pre>
<p>If you want to use a custom error handler for the function call, see
<tt class="docutils literal"><span class="pre">set_pcall_callback</span></tt> under <a class="reference" href="#pcall-errorfunc">pcall errorfunc</a>.</p>
</div>
<div class="section">
<h2><a id="using-lua-threads" name="using-lua-threads">7.4&nbsp;&nbsp;&nbsp;Using Lua threads</a></h2>
<p>To start a Lua thread, you have to call <tt class="docutils literal"><span class="pre">lua_resume()</span></tt>, this means that you
cannot use the previous function <tt class="docutils literal"><span class="pre">call_function()</span></tt> to start a thread. You have
to use</p>
<pre class="literal-block">
template&lt;class Ret&gt;
Ret resume_function(lua_State* L, const char* name, ...)
template&lt;class Ret&gt;
Ret resume_function(object const&amp; obj, ...)
</pre>
<p>and</p>
<pre class="literal-block">
template&lt;class Ret&gt;
Ret resume(lua_State* L, ...)
</pre>
<p>The first time you start the thread, you have to give it a function to execute. i.e. you
have to use <tt class="docutils literal"><span class="pre">resume_function</span></tt>, when the Lua function yields, it will return the first
value passed in to <tt class="docutils literal"><span class="pre">lua_yield()</span></tt>. When you want to continue the execution, you just call
<tt class="docutils literal"><span class="pre">resume()</span></tt> on your <tt class="docutils literal"><span class="pre">lua_State</span></tt>, since it's already executing a function, you don't pass
it one. The parameters to <tt class="docutils literal"><span class="pre">resume()</span></tt> will be returned by <tt class="docutils literal"><span class="pre">yield()</span></tt> on the Lua side.</p>
<p>For yielding C++-functions (without the support of passing data back and forth between the
Lua side and the c++ side), you can use the <a class="reference" href="#yield">yield</a> policy.</p>
<p>With the overload of <tt class="docutils literal"><span class="pre">resume_function</span></tt> that takes an <a class="reference" href="#object">object</a>, it is important that the
object was constructed with the thread as its <tt class="docutils literal"><span class="pre">lua_State*</span></tt>. Like this:</p>
<pre class="literal-block">
lua_State* thread = lua_newthread(L);
object fun = get_global(<strong>thread</strong>)[&quot;my_thread_fun&quot;];
resume_function(fun);
</pre>
</div>
</div>
<div class="section">
<h1><a id="binding-classes-to-lua" name="binding-classes-to-lua">8&nbsp;&nbsp;&nbsp;Binding classes to Lua</a></h1>
<p>To register classes you use a class called <tt class="docutils literal"><span class="pre">class_</span></tt>. Its name is supposed to
resemble the C++ keyword, to make it look more intuitive. It has an overloaded
member function <tt class="docutils literal"><span class="pre">def()</span></tt> that is used to register member functions, operators,
constructors, enums and properties on the class. It will return its
this-pointer, to let you register more members directly.</p>
<p>Let's start with a simple example. Consider the following C++ class:</p>
<pre class="literal-block">
class testclass
{
public:
    testclass(const std::string&amp; s): m_string(s) {}
    void print_string() { std::cout &lt;&lt; m_string &lt;&lt; &quot;\n&quot;; }

private:
    std::string m_string;
};
</pre>
<p>To register it with a Lua environment, write as follows (assuming you are using
namespace luabind):</p>
<pre class="literal-block">
module(L)
[
    class_&lt;testclass&gt;(&quot;testclass&quot;)
        .def(constructor&lt;const std::string&amp;&gt;())
        .def(&quot;print_string&quot;, &amp;testclass::print_string)
];
</pre>
<p>This will register the class with the name testclass and constructor that takes
a string as argument and one member function with the name <tt class="docutils literal"><span class="pre">print_string</span></tt>.</p>
<pre class="literal-block">
Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
&gt; a = testclass('a string')
&gt; a:print_string()
a string
</pre>
<p>It is also possible to register free functions as member functions. The
requirement on the function is that it takes a pointer, const pointer,
reference or const reference to the class type as the first parameter. The rest
of the parameters are the ones that are visible in Lua, while the object
pointer is given as the first parameter. If we have the following C++ code:</p>
<pre class="literal-block">
struct A
{
    int a;
};

int plus(A* o, int v) { return o-&gt;a + v; }
</pre>
<p>You can register <tt class="docutils literal"><span class="pre">plus()</span></tt> as if it was a member function of A like this:</p>
<pre class="literal-block">
class_&lt;A&gt;(&quot;A&quot;)
    .def(&quot;plus&quot;, &amp;plus)
</pre>
<p><tt class="docutils literal"><span class="pre">plus()</span></tt> can now be called as a member function on A with one parameter, int.
If the object pointer parameter is const, the function will act as if it was a
const member function (it can be called on const objects).</p>
<div class="section">
<h2><a id="overloaded-member-functions" name="overloaded-member-functions">8.1&nbsp;&nbsp;&nbsp;Overloaded member functions</a></h2>
<p>When binding more than one overloads of a member function, or just binding
one overload of an overloaded member function, you have to disambiguate
the member function pointer you pass to <tt class="docutils literal"><span class="pre">def</span></tt>. To do this, you can use an
ordinary C-style cast, to cast it to the right overload. To do this, you have
to know how to express member function types in C++, here's a short tutorial
(for more info, refer to your favourite book on C++).</p>
<p>The syntax for member function pointer follows:</p>
<pre class="literal-block">
<em>return-value</em> (<em>class-name</em>::*)(<em>arg1-type</em>, <em>arg2-type</em>, <em>...</em>)
</pre>
<p>Here's an example illlustrating this:</p>
<pre class="literal-block">
struct A
{
    void f(int);
    void f(int, int);
};
</pre>
<pre class="literal-block">
class_&lt;A&gt;()
    .def(&quot;f&quot;, (void(A::*)(int))&amp;A::f)
</pre>
<p>This selects the first overload of the function <tt class="docutils literal"><span class="pre">f</span></tt> to bind. The second
overload is not bound.</p>
</div>
<div class="section">
<h2><a id="properties" name="properties">8.2&nbsp;&nbsp;&nbsp;Properties</a></h2>
<p>To register a global data member with a class is easily done. Consider the
following class:</p>
<pre class="literal-block">
struct A
{
    int a;
};
</pre>
<p>This class is registered like this:</p>
<pre class="literal-block">
module(L)
[
    class_&lt;A&gt;(&quot;A&quot;)
        .def_readwrite(&quot;a&quot;, &amp;A::a)
];
</pre>
<p>This gives read and write access to the member variable <tt class="docutils literal"><span class="pre">A::a</span></tt>. It is also