diff --git a/docs/source/api/compatibility.rst b/docs/source/api/compatibility.rst index c91afeaf..b5e9069d 100644 --- a/docs/source/api/compatibility.rst +++ b/docs/source/api/compatibility.rst @@ -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` code in some places and also from the `lua-compat` 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`. +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>` \ No newline at end of file +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 \ No newline at end of file diff --git a/docs/source/api/coroutine.rst b/docs/source/api/coroutine.rst index dcd19861..63edb05f 100644 --- a/docs/source/api/coroutine.rst +++ b/docs/source/api/coroutine.rst @@ -5,7 +5,7 @@ resumable/yielding functions from Lua A ``coroutine`` is a :doc:`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` that was used to create it (see :doc:`thread` for an example on how to get a coroutine that runs on a thread separate from your usual "main" :doc:`lua_State`). -The ``coroutine`` object is entirely similar to the :doc:`protected_function` object, with additional member functions to check if a coroutine has yielded (:doc:`call_status::yielded`) and is thus runnable again, whether it has completed (:doc:`call_status::ok`) and thus cannot yield anymore values, or whether it has suffered an error (see `status()` and :doc:`call_status`'s error codes). +The ``coroutine`` object is entirely similar to the :doc:`protected_function` object, with additional member functions to check if a coroutine has yielded (:doc:`call_status::yielded`) and is thus runnable again, whether it has completed (:ref:`call_status::ok`) and thus cannot yield anymore values, or whether it has suffered an error (see :ref:`status()` and :ref:`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 decltype(auto) operator()( types, Args&&... args ); -Calls the coroutine. The second ``operator()`` lets you specify the templated return types using the ``my_co(sol::types, ...)`` syntax. Check :ref:`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`. \ No newline at end of file +Calls the coroutine. The second ``operator()`` lets you specify the templated return types using the ``my_co(sol::types, ...)`` 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`. \ No newline at end of file diff --git a/docs/source/api/error.rst b/docs/source/api/error.rst index 50340dfe..ed7e01a4 100644 --- a/docs/source/api/error.rst +++ b/docs/source/api/error.rst @@ -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`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are :doc:`nil`. +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`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are :doc:`nil`. 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. \ No newline at end of file diff --git a/docs/source/api/function.rst b/docs/source/api/function.rst index 1301587f..d6c69d31 100644 --- a/docs/source/api/function.rst +++ b/docs/source/api/function.rst @@ -7,7 +7,7 @@ calling functions bound to Lua class function : public reference; -Function is a correct-assuming version of :doc:`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( ... )`` template type list, it generates a :doc:`function_result` class that gets implicitly converted to the requested return type. For example: +Function is a correct-assuming version of :doc:`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( ... )`` template type list, it generates a :ref:`function_result` class that gets implicitly converted to the requested return type. For example: .. code-block:: lua :caption: func_barks.lua diff --git a/docs/source/api/proxy.rst b/docs/source/api/proxy.rst index 70e6abd2..157c17d1 100644 --- a/docs/source/api/proxy.rst +++ b/docs/source/api/proxy.rst @@ -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` and the results of function calls on :doc:`sol::function` and :doc:`sol::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::value == true ) template @@ -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` and not a :doc:`primitive lua type` .. code-block:: c++ - :caption: [overloaded] implicit set + :caption: functions: [overloaded] implicit set + :name: implicit-set requires( sol::detail::Function == false ) template @@ -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` .. code-block:: c++ + :caption: function: set a callable template 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 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` 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` 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 ------------------------- diff --git a/docs/source/api/state.rst b/docs/source/api/state.rst index 14a99116..25ae9a6e 100644 --- a/docs/source/api/state.rst +++ b/docs/source/api/state.rst @@ -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; + class state : state_view, std::unique_ptr; 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
` 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 void open_libraries(Args&&... args); -This function takes a number of :ref:`sol::lib` as arguments and opens up the associated Lua core libraries. +This function takes a number of :ref:`sol::lib` 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
`, w .. code-block:: cpp :caption: function: Lua set_panic + :name: set-panic void set_panic(lua_CFunction panic); diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst index 34785c65..52f4e6a4 100644 --- a/docs/source/api/types.rst +++ b/docs/source/api/types.rst @@ -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` 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` or a :doc:`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 struct lua_type_of; -This type trait maps a C++ type to a :ref:`type enumation` value. The default value is ``type::userdata``. +This type trait maps a C++ type to a :ref:`type enumeration` value. The default value is ``type::userdata``. .. code-block:: cpp :caption: primitive checking traits + :name: is-primitive template 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\>`, does n .. code-block:: cpp :caption: type list + :name: type-list template 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`. +Gets the Lua-specified name of the :ref:`type`. structs ------- diff --git a/docs/source/features.rst b/docs/source/features.rst index 2e4a99e2..41feb77c 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -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 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+ diff --git a/docs/source/index.rst b/docs/source/index.rst index 53e729a6..7c1ef16c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,32 +3,34 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Sol 2.0.0 +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` 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` 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 \ No newline at end of file