mirror of
https://github.com/ThePhD/sol2.git
synced 2024-03-22 13:10:44 +08:00
fixing up da docs
This commit is contained in:
ThePhD
parent
d8bc6c8612
commit
ce4ebb367e
|
|
@ -3,8 +3,12 @@ compatibility.hpp
|
|||
Lua 5.3/5.2 compatibility for Lua 5.1/LuaJIT
|
||||
--------------------------------------------
|
||||
|
||||
This is a detail header used to maintain compatability with the 5.2 and 5.3 APIs. It contains code from the MIT-Licensed `Lua<http://www.Lua.org/>` code in some places and also from the `lua-compat<https://github.com/keplerproject/lua-compat-5.3>` repository by KeplerProject.
|
||||
This is a detail header used to maintain compatability with the 5.2 and 5.3 APIs. It contains code from the MIT-Licensed `Lua code`_ in some places and also from the `lua-compat`_ repository by KeplerProject.
|
||||
|
||||
It is not fully documented as this header's only purpose is for internal use to make sure Sol compiles across all platforms / distributions with no errors or missing Lua functionality. If you think there's some compatibility features we are missing or if you are running into redefinition errors, please make an `issue in the issue tracker<https://github.com/ThePhD/sol2/issues/>`.
|
||||
It is not fully documented as this header's only purpose is for internal use to make sure Sol compiles across all platforms / distributions with no errors or missing Lua functionality. If you think there's some compatibility features we are missing or if you are running into redefinition errors, please make an `issue in the issue tracker`_.
|
||||
|
||||
For the licenses, see :doc:`here<../licenses>`
|
||||
|
||||
.. _issue in the issue tracker: https://github.com/ThePhD/sol2/issues/
|
||||
.. _Lua code: http://www.Lua.org/
|
||||
.. _lua-compat: https://github.com/keplerproject/lua-compat-5.3
|
||||
|
|
@ -5,7 +5,7 @@ resumable/yielding functions from Lua
|
|||
|
||||
A ``coroutine`` is a :doc:`reference<reference>` to a function in Lua that can be called multiple times to yield a specific result. It is run on the :doc:`lua_State<state>` that was used to create it (see :doc:`thread<thread>` for an example on how to get a coroutine that runs on a thread separate from your usual "main" :doc:`lua_State<state>`).
|
||||
|
||||
The ``coroutine`` object is entirely similar to the :doc:`protected_function<protected_function>` object, with additional member functions to check if a coroutine has yielded (:doc:`call_status::yielded<types>`) and is thus runnable again, whether it has completed (:doc:`call_status::ok<types>`) and thus cannot yield anymore values, or whether it has suffered an error (see `status()` and :doc:`call_status<types>`'s error codes).
|
||||
The ``coroutine`` object is entirely similar to the :doc:`protected_function<protected_function>` object, with additional member functions to check if a coroutine has yielded (:doc:`call_status::yielded<types>`) and is thus runnable again, whether it has completed (:ref:`call_status::ok<call-status>`) and thus cannot yield anymore values, or whether it has suffered an error (see :ref:`status()<status>` and :ref:`call_status<call-status>`'s error codes).
|
||||
|
||||
For example, you can work with a coroutine like this:
|
||||
|
||||
|
|
@ -61,10 +61,9 @@ The following are the members of ``sol::coroutine``:
|
|||
members
|
||||
-------
|
||||
|
||||
.. _status:
|
||||
|
||||
.. code-block:: cpp
|
||||
:caption: returning the coroutine's status
|
||||
:name: status
|
||||
|
||||
call_status status() const noexcept;
|
||||
|
||||
|
|
@ -100,4 +99,4 @@ These functions allow you to check if a coroutine can still be called (has more
|
|||
template<typename... Ret, typename... Args>
|
||||
decltype(auto) operator()( types<Ret...>, Args&&... args );
|
||||
|
||||
Calls the coroutine. The second ``operator()`` lets you specify the templated return types using the ``my_co(sol::types<int, std::string>, ...)`` syntax. Check :ref:`status()<status>` afterwards for more information about the success of the run or just check the coroutine object in an ifs tatement, as shown :ref:`above<runnable>`.
|
||||
Calls the coroutine. The second ``operator()`` lets you specify the templated return types using the ``my_co(sol::types<int, std::string>, ...)`` syntax. Check ``status()`` afterwards for more information about the success of the run or just check the coroutine object in an ifs tatement, as shown :ref:`above<runnable>`.
|
||||
|
|
@ -10,6 +10,6 @@ the single exception type
|
|||
error(const std::string& str): std::runtime_error("Lua: error: " + str) {}
|
||||
};
|
||||
|
||||
If an eror is thrown by Sol, it is going to be of this type. We use this in a single place: the default ``at_panic`` function we bind on construction of a :doc:`sol::state<state>`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are :doc:`nil<types>`.
|
||||
If an eror is thrown by Sol, it is going to be of this type. We use this in a single place: the default ``at_panic`` function we bind on construction of a :ref:`sol::state<state#set-panic>`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are :doc:`nil<types>`.
|
||||
|
||||
As it derives from ``std::runtime_error``, which derives from ``std::exception``, you can catch it with a ``catch (const std::exception& )`` clause in your try/catch blocks.
|
||||
|
|
@ -7,7 +7,7 @@ calling functions bound to Lua
|
|||
|
||||
class function : public reference;
|
||||
|
||||
Function is a correct-assuming version of :doc:`protected_function<protected_function>`, omitting the need for typechecks and error handling. It is the default function type of Sol. When called without the return types being specified by either a ``sol::types<...>`` list or a ``call<Ret...>( ... )`` template type list, it generates a :doc:`function_result<proxy>` class that gets implicitly converted to the requested return type. For example:
|
||||
Function is a correct-assuming version of :doc:`protected_function<protected_function>`, omitting the need for typechecks and error handling. It is the default function type of Sol. When called without the return types being specified by either a ``sol::types<...>`` list or a ``call<Ret...>( ... )`` template type list, it generates a :ref:`function_result<proxy#function-result>` class that gets implicitly converted to the requested return type. For example:
|
||||
|
||||
.. code-block:: lua
|
||||
:caption: func_barks.lua
|
||||
|
|
|
|||
|
|
@ -18,8 +18,6 @@ proxy, (protected\_)function_result - proxy_base derivatives
|
|||
These classes provide implicit ``operator=`` (``set``) and ``operator T`` (``get``) support for items retrieved from the underlying Lua implementation in Sol, specifically :doc:`sol::table<table>` and the results of function calls on :doc:`sol::function<function>` and :doc:`sol::protected_function<protected_function>`.
|
||||
|
||||
|
||||
.. _proxy:
|
||||
|
||||
proxy
|
||||
-----
|
||||
|
||||
|
|
@ -78,7 +76,8 @@ members
|
|||
-------
|
||||
|
||||
.. code-block:: c++
|
||||
:caption: [overloaded] implicit conversion get
|
||||
:caption: functions: [overloaded] implicit conversion get
|
||||
:name: implicit-get
|
||||
|
||||
requires( sol::is_primitive_type<T>::value == true )
|
||||
template <typename T>
|
||||
|
|
@ -91,7 +90,8 @@ members
|
|||
Gets the value associated with the keys the proxy was generated and convers it to the type ``T``. Note that this function will always return ``T&``, a non-const reference, to types which are not based on :doc:`sol::reference<reference>` and not a :doc:`primitive lua type<types>`
|
||||
|
||||
.. code-block:: c++
|
||||
:caption: [overloaded] implicit set
|
||||
:caption: functions: [overloaded] implicit set
|
||||
:name: implicit-set
|
||||
|
||||
requires( sol::detail::Function<Fx> == false )
|
||||
template <typename T>
|
||||
|
|
@ -104,6 +104,7 @@ Gets the value associated with the keys the proxy was generated and convers it t
|
|||
Sets the value associated with the keys the proxy was generated with to ``value``. If this is a function, calls ``set_function``. If it is not, just calls ``set``. See :ref:`note<note 1>`
|
||||
|
||||
.. code-block:: c++
|
||||
:caption: function: set a callable
|
||||
|
||||
template <typename Fx>
|
||||
proxy& set_function( Fx&& fx );
|
||||
|
|
@ -111,6 +112,7 @@ Sets the value associated with the keys the proxy was generated with to ``value`
|
|||
Sets the value associated with the keys the proxy was generated with to a function ``fx``.
|
||||
|
||||
.. code-block:: c++
|
||||
:caption: function: get a value
|
||||
|
||||
template <typename T>
|
||||
T get( ) const;
|
||||
|
|
@ -139,18 +141,19 @@ Consider the following:
|
|||
|
||||
sol::state lua;
|
||||
lua["object"] = doge{}; // bind constructed doge to "object"
|
||||
// but it binds as a function
|
||||
|
||||
When you use the ``lua["object"] = doge{};`` from above, keep in mind that Sol detects if this is a function *callable with any kind of arguments*. If ``doge`` has overriden ``return_type operator()( argument_types... )`` on itself, it may result in satisfying the ``requires`` constraint from above. This means that if you have a user-defined type you want to bind as a :doc:`userdata with usertype semantics<usertype>` with this syntax, it might get bound as a function and not as a user-defined type. use ``lua["object"].set(doge)`` directly to avoid this, or ``lua["object"].set_function(doge{})`` to perform this explicitly.
|
||||
|
||||
|
||||
.. _function_result:
|
||||
.. _function-result:
|
||||
|
||||
function_result
|
||||
---------------
|
||||
|
||||
``function_result`` is a temporary-only, intermediate-only implicit conversion worker for when :doc:`function<function>` is called. It is *NOT* meant to be stored or captured with ``auto``. It provides fast access to the desired underlying value. It does not implement ``set`` / templated ``operator=``.
|
||||
|
||||
.. _protected_function_result:
|
||||
.. _protected-function-result:
|
||||
|
||||
protected_function_result
|
||||
-------------------------
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ owning and non-owning state holders for registry and globals
|
|||
.. code-block:: cpp
|
||||
|
||||
class state_view;
|
||||
class state : state_view, std::unique_ptr<lua_State*>;
|
||||
class state : state_view, std::unique_ptr<lua_State*, deleter>;
|
||||
|
||||
The most important class here is ``state_view``. This structure takes a ``lua_State*`` that was already created and gives you simple, easy access to Lua's interfaces without taking ownership. ``state`` derives from ``state_view``, inheriting all of this functionality, but has the additional purpose of creating a fresh ``lua_State*`` and managing its lifetime for you in the default constructor.
|
||||
|
||||
|
|
@ -15,10 +15,9 @@ The majority of the members between ``state_view`` and :doc:`sol::table<table>`
|
|||
enumerations
|
||||
------------
|
||||
|
||||
.. _libenum:
|
||||
|
||||
.. code-block:: cpp
|
||||
:caption: in-lua libraries
|
||||
:name: lib-enum
|
||||
|
||||
enum class lib : char {
|
||||
base,
|
||||
|
|
@ -42,11 +41,12 @@ members
|
|||
|
||||
.. code-block:: cpp
|
||||
:caption: function: open standard libraries/modules
|
||||
:name: open-libraries
|
||||
|
||||
template<typename... Args>
|
||||
void open_libraries(Args&&... args);
|
||||
|
||||
This function takes a number of :ref:`sol::lib<libenum>` as arguments and opens up the associated Lua core libraries.
|
||||
This function takes a number of :ref:`sol::lib<lib-enum>` as arguments and opens up the associated Lua core libraries.
|
||||
|
||||
.. code-block:: cpp
|
||||
:caption: function: script / script_file
|
||||
|
|
@ -67,6 +67,7 @@ Get either the global table or the Lua registry as a :doc:`sol::table<table>`, w
|
|||
|
||||
.. code-block:: cpp
|
||||
:caption: function: Lua set_panic
|
||||
:name: set-panic
|
||||
|
||||
void set_panic(lua_CFunction panic);
|
||||
|
||||
|
|
|
|||
|
|
@ -11,6 +11,7 @@ enumerations
|
|||
|
||||
.. code-block:: cpp
|
||||
:caption: syntax of a function called by Lua
|
||||
:name: call-syntax
|
||||
|
||||
enum class call_syntax {
|
||||
dot = 0,
|
||||
|
|
@ -19,10 +20,9 @@ enumerations
|
|||
|
||||
This enumeration indicates the syntax a function was called with in a specific scenario. There are two ways to call a function: with ``obj:func_name( ... )`` or ``obj.func_name( ... );`` The first one passes "obj" as the first argument: the second one does not. In the case of usertypes, this is used to determine whether the call to a :doc:`constructor/initializer<usertype>` was called with a ``:`` or a ``.``, and not misalign the arguments.
|
||||
|
||||
.. _call_status:
|
||||
|
||||
.. code-block:: cpp
|
||||
:caption: status of a Lua function call
|
||||
:name: call-status
|
||||
|
||||
enum class call_status : int {
|
||||
ok = LUA_OK,
|
||||
|
|
@ -35,10 +35,9 @@ This enumeration indicates the syntax a function was called with in a specific s
|
|||
|
||||
This strongly-typed enumeration contains the errors potentially generated by a call to a :doc:`protected function<protected_function>` or a :doc:`coroutine<coroutine>`.
|
||||
|
||||
.. _thread_status:
|
||||
|
||||
.. code-block:: cpp
|
||||
:caption: status of a Lua thread
|
||||
:name: thread-status
|
||||
|
||||
enum class thread_status : int {
|
||||
normal = LUA_OK,
|
||||
|
|
@ -52,10 +51,9 @@ This strongly-typed enumeration contains the errors potentially generated by a c
|
|||
|
||||
This enumeration contains the status of a thread. The ``thread_status::dead`` state is generated when the thread has nothing on its stack and it is not running anything.
|
||||
|
||||
.. _type:
|
||||
|
||||
.. code-block:: cpp
|
||||
:caption: type enumeration
|
||||
:name: type-enum
|
||||
|
||||
enum class type : int {
|
||||
none = LUA_TNONE,
|
||||
|
|
@ -80,14 +78,16 @@ type traits
|
|||
|
||||
.. code-block:: cpp
|
||||
:caption: lua_type_of trait
|
||||
:name: lua-type-of
|
||||
|
||||
template <typename T, typename = void>
|
||||
struct lua_type_of;
|
||||
|
||||
This type trait maps a C++ type to a :ref:`type enumation<type>` value. The default value is ``type::userdata``.
|
||||
This type trait maps a C++ type to a :ref:`type enumeration<type-enum>` value. The default value is ``type::userdata``.
|
||||
|
||||
.. code-block:: cpp
|
||||
:caption: primitive checking traits
|
||||
:name: is-primitive
|
||||
|
||||
template <typename T>
|
||||
struct is_lua_primitive;
|
||||
|
|
@ -104,6 +104,7 @@ special types
|
|||
-------------
|
||||
.. code-block:: cpp
|
||||
:caption: nil
|
||||
:name: nil
|
||||
|
||||
strunil_t {};
|
||||
const nil_t nil {};
|
||||
|
|
@ -124,6 +125,7 @@ A tag type that, when used with :doc:`stack::get\<non_null\<T*>><stack>`, does n
|
|||
|
||||
.. code-block:: cpp
|
||||
:caption: type list
|
||||
:name: type-list
|
||||
|
||||
template <typename... Args>
|
||||
struct types;
|
||||
|
|
@ -165,7 +167,7 @@ These functions get the type of a C++ type ``T`` or the type at the specified in
|
|||
|
||||
std::string type_name(lua_State*L, type t);
|
||||
|
||||
Gets the Lua-specified name of the :ref:`type<type>`.
|
||||
Gets the Lua-specified name of the :ref:`type<type-enum>`.
|
||||
|
||||
structs
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -53,9 +53,12 @@ The Feature Matrix™
|
|||
The below feature table checks for the presence of something. It, however, does not actually account for any kind of laborious syntax.
|
||||
|
||||
✔ full support
|
||||
- partial support / wonky support
|
||||
|
||||
~ partial support / wonky support
|
||||
|
||||
✗ no support
|
||||
|
||||
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| | plain C | luawrapper | lua-intf | luabind | Selene | Sol | oolua | lua-api-pp | kaguya |
|
||||
| | | | | | | | | | |
|
||||
|
|
@ -66,33 +69,33 @@ The below feature table checks for the presence of something. It, however, does
|
|||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| arbitrary keys | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| user-defined types (udts) | - | ✔ | ✔ | ✔ | ✔ | ✔ | - | ✔ | ✔ |
|
||||
| user-defined types (udts) | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| udts: member functions | - | ✔ | ✔ | ✔ | ✔ | ✔ | - | ✔ | ✔ |
|
||||
| udts: member functions | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| udts: variables | - | - | - | - | - | ✔ | - | - | - |
|
||||
| udts: variables | ~ | ~ | ~ | ~ | ~ | ✔ | ~ | ~ | ~ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| stack abstractions | - | ✔ | - | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
||||
| stack abstractions | ~ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| function binding | - | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
||||
| function binding | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| protected function | ✔ | ✗ | - | - | - | ✔ | - | ✔ | - |
|
||||
| protected function | ✔ | ✗ | ~ | ~ | ~ | ✔ | ~ | ✔ | ~ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| multi-return | - | ✗ | ✗ | ✔ | ✔ | ✔ | - | ✔ | ✔ |
|
||||
| multi-return | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| inheritance | - | ✗ | ✗ | ✔ | ✔ | ✔ | - | - | ✔ |
|
||||
| inheritance | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ~ | ~ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| overloading | - | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ |
|
||||
| overloading | ~ | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| thread | ✔ | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| coroutines | ✔ | ✗ | ✗ | ✔ | ✔ | ✔ | ✗ | ✗ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| no-rtti support | ✔ | ✗ | - | ✗ | ✗ | ✔ | ✗ | ✗ | ✔ |
|
||||
| no-rtti support | ✔ | ✗ | ~ | ✗ | ✗ | ✔ | ✗ | ✗ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| no-exception support | ✔ | ✗ | - | - | ✗ | ✔ | ✗ | ✗ | ✔ |
|
||||
| no-exception support | ✔ | ✗ | ~ | ~ | ✗ | ✔ | ✗ | ✗ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| Lua 5.1 | ✔ | ✔ | - | ✔ | ✗ | ✔ | ✔ | ✔ | ✔ |
|
||||
| Lua 5.1 | ✔ | ✔ | ~ | ✔ | ✗ | ✔ | ✔ | ✔ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
| Lua 5.2 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
||||
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
||||
|
|
|
|||
|
|
@ -8,27 +8,29 @@ Sol 2.0.0
|
|||
a fast, simple C++ and Lua Binding
|
||||
----------------------------------
|
||||
|
||||
Contents:
|
||||
---------
|
||||
When you need to hit the ground running with Lua and C++, `Sol`_ is the go-to framework for high-performance binding with an easy to use API.
|
||||
|
||||
get going:
|
||||
----------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:name: mastertoc
|
||||
:caption: Contents
|
||||
|
||||
api/top
|
||||
features
|
||||
benchmarks
|
||||
exceptions
|
||||
rtti
|
||||
api/top
|
||||
licenses
|
||||
|
||||
|
||||
"I need feature X, maybe you have it?"
|
||||
--------------------------------------
|
||||
Take a look at the :doc:`Features<features>` page: it links to much of the API. Don't see a feature you want? Send inquiries for support for a particular abstraction to the `issues`_ tracker.
|
||||
Take a look at the :doc:`Features<features>` page: it links to much of the API. You can also just straight up browse the API. Don't see a feature you want? Send inquiries for support for a particular abstraction to the `issues`_ tracker.
|
||||
|
||||
|
||||
The Basics:
|
||||
the basics:
|
||||
-----------
|
||||
|
||||
.. note::
|
||||
|
|
@ -96,8 +98,8 @@ Indices and tables
|
|||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
.. _issues: http://github.com/ThePhD/sol2/issues
|
||||
.. _Sol: https://github.com/ThePhD/sol2
|
||||
.. _issues: https://github.com/ThePhD/sol2/issues
|
||||
.. _examples directory: https://github.com/ThePhD/sol2/tree/develop/examples
|
||||
Loading…
Reference in New Issue
Block a user