mirror of
https://github.com/ThePhD/sol2.git
synced 2024-03-22 13:10:44 +08:00
171 lines
12 KiB
ReStructuredText
171 lines
12 KiB
ReStructuredText
features
|
|
========
|
|
what does Sol (and other libraries) support?
|
|
--------------------------------------------
|
|
|
|
The goal of Sol is to provide an incredibly clean API that provides high performance (comparable or better than the C it was written on) and extreme ease of use. That is, users should be able to say: "this works pretty much how I expected it to."
|
|
|
|
For the hard technical components of Lua and its ecosystem we support, here is the full rundown:
|
|
|
|
what Sol supports
|
|
-----------------
|
|
|
|
* Support for Lua 5.1, 5.2, and 5.3. We achieve this through our "doc:`compatibility<compatibility>` header.
|
|
|
|
* :doc:`Table<api/table>` support: setting values, getting values of multiple (different) types
|
|
- :doc:`Lazy evaluation<api/proxy>` for nested/chained queries
|
|
``table["a"]["b"]["c"] = 24;``
|
|
- Implicit conversion to the types you want
|
|
``double b = table["computed_value"];``
|
|
|
|
* Support for callables (functions, lambdas, member functions)
|
|
- Pull out any Lua function with :doc:`sol::function<api/function>`
|
|
``sol::function fx = table["socket_send"];``
|
|
- Can also set callables into :doc:`operator[] proxies<api/proxy>`
|
|
``table["move_dude"] = engine::move_dude;``
|
|
- Safety: use :doc:`sol::protected_function<api/protected_function>` to catch any kind of error
|
|
+ ANY kind: C++ exception or Lua erors are trapped and run through the optional ``error_handler`` variable
|
|
- *Advanced:* Overloading of a single function so you don't need to do boring typechecks
|
|
|
|
* User-Defined Type (:doc:`sol::usertype<api/usertype>` in the API) support:
|
|
- Set member functions to be called
|
|
- Set member variables
|
|
- Use free-functions that take the Type as a first argument (pointer or reference)
|
|
- Support for "Factory" classes that do not expose constructor or destructor
|
|
- Modifying memory of userdata in C++ directly affects Lua without copying, and
|
|
- Modifying userdata in Lua directly affects C++ references/pointers
|
|
``my_class& a = table["a"];``
|
|
``my_class* a_ptr = table["a"];``
|
|
- If you want a copy, just use value semantics and get copies:
|
|
``my_class a = table["a"];``
|
|
|
|
* Thread/Coroutine support
|
|
- Use, resume, and play with :doc:`coroutines<api/coroutine>` like regular functions
|
|
- Get and use them even on a separate Lua :doc:`thread<api/thread>`
|
|
- Monitor status and get check errors
|
|
|
|
* *Advanced:* Customizable and extensible to your own types if you override :doc:`getter/pusher/checker<api/stack>` template struct definitions.
|
|
|
|
|
|
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
|
|
|
|
✗ no support
|
|
|
|
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| | plain C | luawrapper | lua-intf | luabind | Selene | Sol | oolua | lua-api-pp | kaguya |
|
|
| | | | | | | | | | |
|
|
+===========================+=============+============+==========+=========+==========+===========+===========+================+==========+
|
|
| tables | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| table chaining | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| arbitrary keys | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| user-defined types (udts) | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| udts: member functions | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| udts: variables | ~ | ~ | ~ | ~ | ~ | ✔ | ~ | ~ | ~ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| stack abstractions | ~ | ✔ | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| function binding | ~ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| protected function | ✔ | ✗ | ~ | ~ | ~ | ✔ | ~ | ✔ | ~ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| multi-return | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ~ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| inheritance | ~ | ✗ | ✗ | ✔ | ✔ | ✔ | ~ | ~ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| overloading | ~ | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| thread | ✔ | ✗ | ✗ | ✗ | ✗ | ✔ | ✗ | ✗ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| coroutines | ✔ | ✗ | ✗ | ✔ | ✔ | ✔ | ✗ | ✗ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| no-rtti support | ✔ | ✗ | ~ | ✗ | ✗ | ✔ | ✗ | ✗ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| no-exception support | ✔ | ✗ | ~ | ~ | ✗ | ✔ | ✗ | ✗ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| Lua 5.1 | ✔ | ✔ | ~ | ✔ | ✗ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| Lua 5.2 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| Lua 5.3 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| luajit | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
| distribution | compile | header | both | compile | header | header | compile | compile | header |
|
|
+---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+
|
|
|
|
notes on implementations
|
|
------------------------
|
|
|
|
Plain C -
|
|
|
|
* Obviously you can do anything you want with Plain C, but the effort involved is astronomical in comparison to what frameworks offer
|
|
* Does not scale very well (in terms of developer ease of use)
|
|
* Compilation (or package manager use) is obviously required for your platform and required to use ANY of these libraries whatsoever
|
|
|
|
luawrapper -
|
|
|
|
* Takes the approach of writing and reading tables using ``readVariable`` and ``writeVariable`` functions
|
|
* C++11
|
|
* No macros
|
|
* The interface can be clunky (no table-like data structures: most things go though ``readVariable`` / ``writeVariable``)
|
|
|
|
|
|
lua-intf -
|
|
|
|
* Can be both header-only or compiled
|
|
* C++11
|
|
* Macro-based registration (strange pseudo-language)
|
|
* Fairly fast in most regards
|
|
* Registering classes/"modules" in using C++ code is extremely verbose
|
|
|
|
luabind -
|
|
|
|
* One of the older frameworks, but has many people updating it and providing "deboostified" versions
|
|
* Strange in-lua keywords and parsing to allow for classes to be written in lua
|
|
- not sure if good feature; vendor lock-in to that library to depend on this specific class syntax?
|
|
|
|
Selene -
|
|
|
|
* member variables are automatically turned into ``obj:set_x( value )`` to set and ``obj:x()`` to get
|
|
* Registering classes/"modules" in using C++ code is extremely verbose
|
|
|
|
Sol -
|
|
|
|
* Overloading support can get messy with inheritance, see :doc:`here<api/overload>`
|
|
* Only (?) library that supports table-like use of variables as shown in the :doc:`sneak peek<index>`
|
|
* C++14/"C++1y" (-std=c++14, -std=c++1y, =std=c++1z) flags are used (available since GCC 4.9 and Clang 3.5)
|
|
|
|
oolua -
|
|
|
|
* The syntax for this library is thicker than a brick. No, seriously. `Go read the docs.`_
|
|
|
|
.. _ fn1:
|
|
|
|
lua-api-pp -
|
|
|
|
* Compiled, but the recommendation is to add the source files directly to your project
|
|
* Userdata registration with nice, thick macros: LUAPP_USERDATA( ... ) plus a bunch of free functions that take a ``T& self`` argument
|
|
* C++11-ish in some regards
|
|
|
|
kaguya -
|
|
|
|
* Probably the closest in implementation details and interface to Sol itself
|
|
* Inspired coroutine support for Sol
|
|
* Library author (satoren) is a nice guy!
|
|
* C++11/14, or boostified (which makes it C++03 compatible)
|
|
|
|
|
|
.. _Go read the docs.: https://oolua.org/docs/index.html |