docs.rst.svn-base

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

.. include:: pure_out_value.rst
.. include:: return_reference_to.rst
.. include:: copy.rst
.. include:: discard_result.rst
.. include:: return_stl_iterator.rst
.. include:: raw.rst
.. include:: yield.rst

..  old policies section
    ===================================================

    Copy
    ----

    This will make a copy of the parameter. This is the default behavior when
    passing parameters by-value. Note that this can only be used when passing from
    C++ to Lua. This policy requires that the parameter type has a copy
    constructor.

    To use this policy you need to include ``luabind/copy_policy.hpp``.


    Adopt
    -----

    This will transfer ownership of the parameter.

    Consider making a factory function in C++ and exposing it to lua::

        base* create_base()
        {
            return new base();
        }

        ...

        module(L)
        [
            def("create_base", create_base)
        ];

    Here we need to make sure Lua understands that it should adopt the pointer
    returned by the factory-function. This can be done using the adopt-policy.

    ::

        module(L)
        [
            def(L, "create_base", adopt(return_value))
        ];

    To specify multiple policies we just separate them with '+'.

    ::

        base* set_and_get_new(base* ptr)
        {
            base_ptrs.push_back(ptr);
            return new base();
        }

        module(L)
        [
            def("set_and_get_new", &set_and_get_new, 
                adopt(return_value) + adopt(_1))
        ];

    When Lua adopts a pointer, it will call delete on it. This means that it cannot
    adopt pointers allocated with another allocator than new (no malloc for
    example).

    To use this policy you need to include ``luabind/adopt_policy.hpp``.


    Dependency
    ----------

    The dependency policy is used to create life-time dependencies between values.
    Consider the following example::

        struct A
        {
            B member;

            const B& get_member()
            {
                return member;
            }
        };

    When wrapping this class, we would do something like::

        module(L)
        [
            class_<A>("A")
                .def(constructor<>())
                .def("get_member", &A::get_member)
        ];


    However, since the return value of get_member is a reference to a member of A,
    this will create some life-time issues. For example::

        Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
        a = A()
        b = a:get_member() -- b points to a member of a
        a = nil
        collectgarbage(0)  -- since there are no references left to a, it is
                           -- removed
                           -- at this point, b is pointing into a removed object

    When using the dependency-policy, it is possible to tell luabind to tie the
    lifetime of one object to another, like this::

        module(L)
        [
            class_<A>("A")
                .def(constructor<>())
                .def("get_member", &A::get_member, dependency(result, _1))
        ];

    This will create a dependency between the return-value of the function, and the
    self-object. This means that the self-object will be kept alive as long as the
    result is still alive. ::

        Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
        a = A()
        b = a:get_member() -- b points to a member of a
        a = nil
        collectgarbage(0)  -- a is dependent on b, so it isn't removed
        b = nil
        collectgarbage(0)  -- all dependencies to a gone, a is removed

    To use this policy you need to include ``luabind/dependency_policy.hpp``.


    Return reference to
    -------------------

    It is very common to return references to arguments or the this-pointer to
    allow for chaining in C++.

    ::

        struct A
        {
            float val;

            A& set(float v)
            {
                val = v;
                return *this;
            }
        };

    When luabind generates code for this, it will create a new object for the
    return-value, pointing to the self-object. This isn't a problem, but could be a
    bit inefficient. When using the return_reference_to-policy we have the ability
    to tell luabind that the return-value is already on the Lua stack.

    ::

        module(L)
        [
            class_<A>("A")
                .def(constructor<>())
                .def("set", &A::set, return_reference_to(_1))
        ];

    Instead of creating a new object, luabind will just copy the object that is
    already on the stack.

    .. warning:: 
       This policy ignores all type information and should be used only it 
       situations where the parameter type is a perfect match to the 
       return-type (such as in the example).

    To use this policy you need to include ``luabind/return_reference_to_policy.hpp``.


    Out value
    ---------

    This policy makes it possible to wrap functions that take non const references
    as its parameters with the intention to write return values to them.

    ::

        void f(float& val) { val = val + 10.f; }

    or

    ::

        void f(float* val) { *val = *val + 10.f; }

    Can be wrapped by doing::

        module(L)
        [
            def("f", &f, out_value(_1))
        ];

    When invoking this function from Lua it will return the value assigned to its 
    parameter.

    ::

        Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
        > a = f(10)
        > print(a)
        20

    When this policy is used in conjunction with user define types we often need 
    to do ownership transfers.

    ::

        struct A;

        void f1(A*& obj) { obj = new A(); }
        void f2(A** obj) { *obj = new A(); }

    Here we need to make sure luabind takes control over object returned, for 
    this we use the adopt policy::

        module(L)
        [
            class_<A>("A"),
            def("f1", &f1, out_value(_1, adopt(_2)))
            def("f2", &f2, out_value(_1, adopt(_2)))
        ];

    Here we are using adopt as an internal policy to out_value. The index 
    specified, _2, means adopt will be used to convert the value back to Lua. 
    Using _1 means the policy will be used when converting from Lua to C++.

    To use this policy you need to include ``luabind/out_value_policy.hpp``.

    Pure out value
    --------------

    This policy works in exactly the same way as out_value, except that it 
    replaces the parameters with default-constructed objects.

    ::

        void get(float& x, float& y)
        {
            x = 3.f;
            y = 4.f;
        }

        ...

        module(L)
        [
            def("get", &get, 
                pure_out_value(_1) + pure_out_value(_2))
        ];

    ::

        Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
        > x, y = get()
        > print(x, y)
        3    5

    Like out_value, it is possible to specify an internal policy used then 
    converting the values back to Lua.

    ::

        void get(test_class*& obj)
        {
            obj = new test_class();
        }

        ...

        module(L)
        [
            def("get", &get, pure_out_value(_1, adopt(_1)))
        ];


    Discard result
    --------------

    This is a very simple policy which makes it possible to throw away 
    the value returned by a C++ function, instead of converting it to 
    Lua. This example makes sure the this reference never gets converted 
    to Lua.

    ::

        struct simple
        {
            simple& set_name(const std::string& n)
            {
                name = n;
                return *this;
            }

            std::string name;
        };

        ...

        module(L)
        [
            class_<simple>("simple")
                .def("set_name", &simple::set_name, discard_result)
        ];

    To use this policy you need to include ``luabind/discard_result_policy.hpp``.


    Return STL iterator
    -------------------

    This policy converts an STL container to a generator function that can be used
    in Lua to iterate over the container. It works on any container that defines
    ``begin()`` and ``end()`` member functions (they have to return iterators). It
    can be used like this::

        struct A
        {
            std::vector<std::string> names;
        };


        module(L)
        [
            class_<A>("A")
                .def_readwrite("names", &A::names, return_stl_iterator)
        ];

    The Lua code to iterate over the container::

        a = A()

        for name in a.names do
          print(name)
        end


    To use this policy you need to include ``luabind/iterator_policy.hpp``.


    Yield
    -----    

    This policy will cause the function to always yield the current thread when 
    returning. See the Lua manual for restrictions on yield.


Splitting up the registration
=============================

It is possible to split up a module registration into several
translation units without making each registration dependent
on the module it's being registered in.

``a.cpp``::

    luabind::scope register_a()
    {
        return 
            class_<a>("a")
                .def("f", &a::f)
                ;
    }

``b.cpp``::

    luabind::scope register_b()
    {
        return 
            class_<b>("b")
                .def("g", &b::g)
                ;
    }

``module_ab.cpp``::

    luabind::scope register_a();
    luabind::scope register_b();

    void register_module(lua_State* L)
    {
        module("b", L)
        [
            register_a(),
            register_b()
        ];
    }


Error Handling
==============

pcall errorfunc
---------------

As mentioned in the `Lua documentation`_, it is possible to pass an
error handler function to ``lua_pcall()``. Luabind makes use of 
``lua_pcall()`` internally when calling member functions and free functions.
It is possible to set the error handler function that Luabind will use
globally::

    typedef int(*pcall_callback_fun)(lua_State*);
    void set_pcall_callback(pcall_callback_fun fn);

This is primarily useful for adding more information to the error message
returned by a failed protected call. For more information on how to use the
pcall_callback function, see ``errfunc`` under the
`pcall section of the lua manual`_.

For more information on how to retrieve debugging information from lua, see
`the debug section of the lua manual`_.

The message returned by the ``pcall_callback`` is accessable as the top lua
value on the stack. For example, if you would like to access it as a luabind
object, you could do like this::

    catch(error& e)
    {
        object error_msg(from_stack(e.state(), -1));
        std::cout << error_msg << std::endl;
    }

.. _Lua docu