diff --git a/docs/source/api/api-top.rst b/docs/source/api/api-top.rst index bb14b812..7fc1b896 100644 --- a/docs/source/api/api-top.rst +++ b/docs/source/api/api-top.rst @@ -43,6 +43,7 @@ Browse the various function and classes :doc:`Sol<../index>` utilizes to make yo property var protect + filters readonly as_function c_call diff --git a/docs/source/api/filters.rst b/docs/source/api/filters.rst new file mode 100644 index 00000000..ebe263ec --- /dev/null +++ b/docs/source/api/filters.rst @@ -0,0 +1,35 @@ +filters +======= +*stack modification right before lua call returns* + +``sol::filters`` is an advanced, low-level modification feature allowing you to take advantage of sol2's abstractions before applying your own stack-based modifications at the last moment. They cover the same functionality as `luabind's "return reference to" and "dependency"`_ types. A few pre-rolled filters are defined for your use: + ++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| filter | usage | modification | ++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sol::returns_self`` | ``sol::filters( some_function, sol::returns_self() )`` | - takes the argument at stack index 1 (``self`` in member function calls and lambdas that take a specific userdata first) and makes that to be the return value | +| | | - rather than creating a new userdata that references the same C++ memory, it copies the userdata, similar to writing ``obj2 = obj1`` just increases the reference count | +| | | - saves memory space on top of keeping original memory alive | ++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sol::returns_self_with`` | ``sol::filters( some_function, sol::returns_self_with<2, 3>() )`` | - same as above, with the caveat that the ``self`` is returned while also putting dependencies into the ``self`` | +| | | - can keep external dependencies alive | ++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sol::self_dependency`` | ``sol::filters( some_function, sol::self_dependency() );`` | - this makes the value returned by the bindable take a dependency on the ``self`` argument | +| | | - useful for returning a reference to a member variable and keeping the parent class of that member variable alive | ++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``sol::stack_dependencies`` | ``sol::filters( some_function, sol::stack_dependencies( target_index, 2, 1, ... ) );`` | - whatever is at ``target_index`` on the stack is given a special "keep alive" table with the elements on the stack specified by the integer indices after ``target_index`` | +| | | - allows you to keep arguments and other things alive for the duration of the existence of the class | ++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| custom | ``sol::filters( some_function, [](lua_State* L, int current_stack_return_count) -> int { ... } )`` | - whatever you want, so long as it has the form ``int (lua_State*, int )`` | +| | | - works with callables (such as lambdas), so long as it has the correct form | +| | | - expected to return the number of things on the stack to return to Lua | ++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| - "some_function" can be any callable function, member variable, or similar | +| - dependency additions only work on userdata | +| | +| - works with ``table::set( ... )``, ``table::set_function( ... );``, and on all usertype bindings | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +You can specify multiple filters on the same ``sol::filters`` call, and can also specify custom filters as long as the signature is correct. + +.. _luabind's "return reference to" and "dependency": http://www.rasterbar.com/products/luabind/docs.html#dependency diff --git a/docs/source/conf.py b/docs/source/conf.py index 3906305b..0e0c4ae7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -61,7 +61,7 @@ author = 'ThePhD' # The short X.Y version. version = '2.18' # The full version, including alpha/beta/rc tags. -release = '2.18.0' +release = '2.18.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/functions.rst b/docs/source/functions.rst index 31281f2d..0732a000 100644 --- a/docs/source/functions.rst +++ b/docs/source/functions.rst @@ -20,6 +20,8 @@ There are a number of examples dealing with functions and how they can be bound - :doc:`sol::this_environment`, for potentially retrieving the current Lua environment * Control serialization of arguments and return types with :doc:`sol::nested`, :doc:`sol::as_table`, :doc:`sol::as_args` and :doc:`sol::as_function` * Set environments for Lua functions and scripts with :doc:`sol::environment` +* You can use :doc:`filters` to control dependencies and streamline return values, as well as apply custom behavior to a functions return + .. _binding-callable-objects: diff --git a/docs/source/usertypes.rst b/docs/source/usertypes.rst index 5dc1c8bf..24e53bb4 100644 --- a/docs/source/usertypes.rst +++ b/docs/source/usertypes.rst @@ -16,6 +16,7 @@ The examples folder also has a number of really great examples for you to see. T * `Certain operators`_ are detected and bound automatically for usertypes * You can use bitfields but it requires some finesse on your part. We have an example to help you get started `here, that uses a few tricks`_. * All usertypes are runtime extensible in both `Lua`_ and `C++`_ +* You can use :doc:`filters` to control dependencies and streamline return values, as well as apply custom behavior to a functions return * Please note that the colon is necessary to "automatically" pass the ``this``/``self`` argument to Lua methods - ``obj:method_name()`` is how you call "member" methods in Lua - It is purely syntactic sugar that passes the object name as the first argument to the ``method_name`` function