docs.html.svn-base

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

<thead valign="bottom">
<tr><th class="head">Source</th>
<th class="head">Target</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span> <span class="pre">const&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">holder_type&lt;A&gt;</span></tt></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span> <span class="pre">const&amp;</span></tt></td>
<td><tt class="docutils literal"><span class="pre">holder_type&lt;A</span> <span class="pre">const&gt;</span></tt></td>
</tr>
</tbody>
</table>
</div>
<p>When using a holder type, it can be useful to know if the pointer is valid
(i.e. not null). For example when using std::auto_ptr, the holder will be
invalidated when passed as a parameter to a function. For this purpose there
is a member of all object instances in luabind: <tt class="docutils literal"><span class="pre">__ok</span></tt>.</p>
<pre class="literal-block">
struct X {};
void f(std::auto_ptr&lt;X&gt;);

module(L)
[
    class_&lt;X, std::auto_ptr&lt;X&gt; &gt;(&quot;X&quot;)
        .def(constructor&lt;&gt;()),

    def(&quot;f&quot;, &amp;f)
];
</pre>
<pre class="literal-block">
Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
&gt; a = X()
&gt; f(a)
&gt; print a.__ok
false
</pre>
<p>When registering a hierarchy of classes, where all instances are to be held
by a smart pointer, all the classes should have the baseclass' holder type.
Like this:</p>
<pre class="literal-block">
module(L)
[
    class_&lt;base, boost::shared_ptr&lt;base&gt; &gt;(&quot;base&quot;)
        .def(constructor&lt;&gt;()),
    class_&lt;derived, base, <strong>boost::shared_ptr&lt;base&gt;</strong> &gt;(&quot;base&quot;)
        .def(constructor&lt;&gt;())
];
</pre>
<p>Internally, luabind will do the necessary conversions on the raw pointers, which
are first extracted from the holder type.</p>
</div>
<div class="section">
<h2><a id="splitting-class-registrations" name="splitting-class-registrations">8.8&nbsp;&nbsp;&nbsp;Splitting class registrations</a></h2>
<p>In some situations it may be desirable to split a registration of a class
across different compilation units. Partly to save rebuild time when changing
in one part of the binding, and in some cases compiler limits may force you
to split it. To do this is very simple. Consider the following sample code:</p>
<pre class="literal-block">
void register_part1(class_&lt;X&gt;&amp; x)
{
    x.def(/*...*/);
}

void register_part2(class_&lt;X&gt;&amp; x)
{
    x.def(/*...*/);
}

void register_(lua_State* L)
{
    class_&lt;X&gt; x(&quot;x&quot;);

    register_part1(x);
    register_part2(x);

    module(L) [ x ];
}
</pre>
<p>Here, the class <tt class="docutils literal"><span class="pre">X</span></tt> is registered in two steps. The two functions
<tt class="docutils literal"><span class="pre">register_part1</span></tt> and <tt class="docutils literal"><span class="pre">register_part2</span></tt> may be put in separate compilation
units.</p>
<p>To separate the module registration and the classes to be registered, see
<a class="reference" href="#splitting-up-the-registration">Splitting up the registration</a>.</p>
</div>
</div>
<div class="section">
<h1><a id="object" name="object">9&nbsp;&nbsp;&nbsp;Object</a></h1>
<p>Since functions have to be able to take Lua values (of variable type) we need a
wrapper around them. This wrapper is called <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. If the
function you register takes an object, it will match any Lua value. To use it,
you need to include <tt class="docutils literal"><span class="pre">&lt;luabind/object.hpp&gt;</span></tt>.</p>
<div class="topic">
<p class="topic-title first">Synopsis</p>
<pre class="literal-block">
class object
{
public:
    template&lt;class T&gt;
    object(lua_State*, T const&amp; value);
    object(from_stack const&amp;);
    object(object const&amp;);
    object();

    ~object();

    lua_State* interpreter() const;
    void push() const;
    bool is_valid() const;
    operator <em>safe_bool_type</em> () const;

    template&lt;class Key&gt;
    <em>implementation-defined</em> operator[](Key const&amp;);

    template&lt;class T&gt;
    object&amp; operator=(T const&amp;);
    object&amp; operator=(object const&amp;);

    bool operator==(object const&amp;) const;
    bool operator&lt;(object const&amp;) const;
    bool operator&lt;=(object const&amp;) const;
    bool operator&gt;(object const&amp;) const;
    bool operator&gt;=(object const&amp;) const;
    bool operator!=(object const&amp;) const;

    template &lt;class T&gt;
    <em>implementation-defined</em> operator[](T const&amp; key) const

    void swap(object&amp;);

    <em>implementation-defined</em> operator()();

    template&lt;class A0&gt;
    <em>implementation-defined</em> operator()(A0 const&amp; a0);

    template&lt;class A0, class A1&gt;
    <em>implementation-defined</em> operator()(A0 const&amp; a0, A1 const&amp; a1);

    /* ... */
};
</pre>
</div>
<p>When you have a Lua object, you can assign it a new value with the assignment
operator (=). When you do this, the <tt class="docutils literal"><span class="pre">default_policy</span></tt> will be used to make the
conversion from C++ value to Lua. If your <tt class="docutils literal"><span class="pre">luabind::object</span></tt> is a table you
can access its members through the operator[] or the <a class="reference" href="#iterators">Iterators</a>. The value
returned from the operator[] is a proxy object that can be used both for
reading and writing values into the table (using operator=).</p>
<p>Note that it is impossible to know if a Lua value is indexable or not
(<tt class="docutils literal"><span class="pre">lua_gettable</span></tt> doesn't fail, it succeeds or crashes). This means that if
you're trying to index something that cannot be indexed, you're on your own.
Lua will call its <tt class="docutils literal"><span class="pre">panic()</span></tt> function. See <a class="reference" href="#lua-panic">lua panic</a>.</p>
<p>There are also free functions that can be used for indexing the table, see
<a class="reference" href="#related-functions">Related functions</a>.</p>
<p>The constructor that takes a <tt class="docutils literal"><span class="pre">from_stack</span></tt> object is used when you want to
initialize the object with a value from the lua stack. The <tt class="docutils literal"><span class="pre">from_stack</span></tt>
type has the following constructor:</p>
<pre class="literal-block">
from_stack(lua_State* L, int index);
</pre>
<p>The index is an ordinary lua stack index, negative values are indexed from the
top of the stack. You use it like this:</p>
<pre class="literal-block">
object o(from_stack(L, -1));
</pre>
<p>This will create the object <tt class="docutils literal"><span class="pre">o</span></tt> and copy the value from the top of the lua stack.</p>
<p>The <tt class="docutils literal"><span class="pre">interpreter()</span></tt> function returns the Lua state where this object is stored.
If you want to manipulate the object with Lua functions directly you can push
it onto the Lua stack by calling <tt class="docutils literal"><span class="pre">push()</span></tt>.</p>
<p>The operator== will call lua_equal() on the operands and return its result.</p>
<p>The <tt class="docutils literal"><span class="pre">is_valid()</span></tt> function tells you whether the object has been initialized
or not. When created with its default constructor, objects are invalid. To make
an object valid, you can assign it a value. If you want to invalidate an object
you can simply assign it an invalid object.</p>
<p>The <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">safe_bool_type()</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">is_valid()</span></tt>. This means
that these snippets are equivalent:</p>
<pre class="literal-block">
object o;
// ...
if (o)
{
    // ...
}

...

object o;
// ...
if (o.is_valid())
{
    // ...
}
</pre>
<p>The application operator will call the value as if it was a function. You can
give it any number of parameters (currently the <tt class="docutils literal"><span class="pre">default_policy</span></tt> will be used
for the conversion). The returned object refers to the return value (currently
only one return value is supported). This operator may throw <tt class="docutils literal"><span class="pre">luabind::error</span></tt>
if the function call fails. If you want to specify policies to your function
call, you can use index-operator (operator[]) on the function call, and give
the policies within the [ and ]. Like this:</p>
<pre class="literal-block">
my_function_object(
    2
  , 8
  , new my_complex_structure(6)
) [ adopt(_3) ];
</pre>
<p>This tells luabind to make Lua adopt the ownership and responsibility for the
pointer passed in to the lua-function.</p>
<p>It's important that all instances of object have been destructed by the time
the Lua state is closed. The object will keep a pointer to the lua state and
release its Lua object in its destructor.</p>
<p>Here's an example of how a function can use a table:</p>
<pre class="literal-block">
void my_function(object const&amp; table)
{
    if (type(table) == LUA_TTABLE)
    {
        table[&quot;time&quot;] = std::clock();
        table[&quot;name&quot;] = std::rand() &lt; 500 ? &quot;unusual&quot; : &quot;usual&quot;;

        std::cout &lt;&lt; object_cast&lt;std::string&gt;(table[5]) &lt;&lt; &quot;\n&quot;;
    }
}
</pre>
<p>If you take a <tt class="docutils literal"><span class="pre">luabind::object</span></tt> as a parameter to a function, any Lua value
will match that parameter. That's why we have to make sure it's a table before
we index into it.</p>
<pre class="literal-block">
std::ostream&amp; operator&lt;&lt;(std::ostream&amp;, object const&amp;);
</pre>
<p>There's a stream operator that makes it possible to print objects or use
<tt class="docutils literal"><span class="pre">boost::lexical_cast</span></tt> to convert it to a string. This will use lua's string
conversion function. So if you convert a C++ object with a <tt class="docutils literal"><span class="pre">tostring</span></tt>
operator, the stream operator for that type will be used.</p>
<div class="section">
<h2><a id="iterators" name="iterators">9.1&nbsp;&nbsp;&nbsp;Iterators</a></h2>
<p>There are two kinds of iterators. The normal iterator that will use the metamethod
of the object (if there is any) when the value is retrieved. This iterator is simply
called <tt class="docutils literal"><span class="pre">luabind::iterator</span></tt>. The other iterator is called <tt class="docutils literal"><span class="pre">luabind::raw_iterator</span></tt>
and will bypass the metamethod and give the true contents of the table. They have
identical interfaces, which implements the <a class="reference" href="http://www.sgi.com/tech/stl/ForwardIterator.html">ForwardIterator</a> concept. Apart from
the members of standard iterators, they have the following members and constructors:</p>
<pre class="literal-block">
class iterator
{
    iterator();
    iterator(object const&amp;);

    object key() const;

    <em>standard iterator members</em>
};
</pre>
<p>The constructor that takes a <tt class="docutils literal"><span class="pre">luabind::object</span></tt> is actually a template that can be
used with object. Passing an object as the parameter to the iterator will
construct the iterator to refer to the first element in the object.</p>
<p>The default constructor will initialize the iterator to the one-past-end
iterator. This is used to test for the end of the sequence.</p>
<p>The value type of the iterator is an implementation defined proxy type which
supports the same operations as <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. Which means that in most
cases you can just treat it as an ordinary object. The difference is that any
assignments to this proxy will result in the value being inserted at the
iterators position, in the table.</p>
<p>The <tt class="docutils literal"><span class="pre">key()</span></tt> member returns the key used by the iterator when indexing the
associated Lua table.</p>
<p>An example using iterators:</p>
<pre class="literal-block">
for (iterator i(globals(L)[&quot;a&quot;]), end; i != end; ++i)
{
  *i = 1;
}
</pre>
<p>The iterator named <tt class="docutils literal"><span class="pre">end</span></tt> will be constructed using the default constructor
and hence refer to the end of the sequence. This example will simply iterate
over the entries in the global table <tt class="docutils literal"><span class="pre">a</span></tt> and set all its values to 1.</p>
</div>
<div class="section">
<h2><a id="related-functions" name="related-functions">9.2&nbsp;&nbsp;&nbsp;Related functions</a></h2>
<p>There are a couple of functions related to objects and tables.</p>
<pre class="literal-block">
int type(object const&amp;);
</pre>
<p>This function will return the lua type index of the given object.
i.e. <tt class="docutils literal"><span class="pre">LUA_TNIL</span></tt>, <tt class="docutils literal"><span class="pre">LUA_TNUMBER</span></tt> etc.</p>
<pre class="literal-block">
template&lt;class T, class K&gt;
void settable(object const&amp; o, K const&amp; key, T const&amp; value);
template&lt;class K&gt;
object gettable(object const&amp; o, K const&amp; key);
template&lt;class T, class K&gt;
void rawset(object const&amp; o, K const&amp; key, T const&amp; value);
template&lt;class K&gt;
object rawget(object const&amp; o, K const&amp; key);
</pre>
<p>These functions are used for indexing into tables. <tt class="docutils literal"><span class="pre">settable</span></tt> and <tt class="docutils literal"><span class="pre">gettable</span></tt>
translates into calls to <tt class="docutils literal"><span class="pre">lua_settable</span></tt> and <tt class="docutils literal"><span class="pre">lua_gettable</span></tt> respectively. Which
means that you could just as well use the index operator of the object.</p>
<p><tt class="docutils literal"><span class="pre">rawset</span></tt> and <tt class="docutils literal"><span class="pre">rawget</span></tt> will translate into calls to <tt class="docutils literal"><span class="pre">lua_rawset</span></tt> and
<tt class="docutils literal"><span class="pre">lua_rawget</span></tt> respectively. So they will bypass any metamethod and giv