diff options
Diffstat (limited to 'deps/sol2/docs/source/tutorial')
| -rw-r--r-- | deps/sol2/docs/source/tutorial/all-the-things.rst | 311 | ||||
| -rw-r--r-- | deps/sol2/docs/source/tutorial/customization.rst | 34 | ||||
| -rw-r--r-- | deps/sol2/docs/source/tutorial/cxx-in-lua.rst | 47 | ||||
| -rw-r--r-- | deps/sol2/docs/source/tutorial/existing.rst | 39 | ||||
| -rw-r--r-- | deps/sol2/docs/source/tutorial/functions.rst | 341 | ||||
| -rw-r--r-- | deps/sol2/docs/source/tutorial/getting-started.rst | 59 | ||||
| -rw-r--r-- | deps/sol2/docs/source/tutorial/ownership.rst | 62 | ||||
| -rw-r--r-- | deps/sol2/docs/source/tutorial/tutorial-top.rst | 21 | ||||
| -rw-r--r-- | deps/sol2/docs/source/tutorial/variables.rst | 70 |
9 files changed, 984 insertions, 0 deletions
diff --git a/deps/sol2/docs/source/tutorial/all-the-things.rst b/deps/sol2/docs/source/tutorial/all-the-things.rst new file mode 100644 index 0000000..5615cbf --- /dev/null +++ b/deps/sol2/docs/source/tutorial/all-the-things.rst @@ -0,0 +1,311 @@ +tutorial: quick 'n' dirty +========================= + +These are all the things. Use your browser's search to find things you want. + +.. note:: + + After you learn the basics of sol, it is usually advised that if you think something can work, you should TRY IT. It will probably work! + +.. note:: + + All of the code below is available at the `sol3 tutorial examples`_. + +.. note:: + + Make sure to add ``SOL_ALL_SAFETIES_ON`` preprocessor define to your build configuration to turn safety on. + +asserts / prerequisites +----------------------- + +You'll need to ``#include <sol/sol.hpp>`` somewhere in your code. sol is header-only, so you don't need to compile anything. However, **Lua must be compiled and available**. See the :doc:`getting started tutorial<getting-started>` for more details. + +The implementation for ``assert.hpp`` with ``c_assert`` looks like so: + +.. literalinclude:: ../../../examples/include/assert.hpp + :linenos: + :lines: 1-3, 19- + +This is the assert used in the quick code below. + +opening a state +--------------- + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/opening_a_state.cpp + :linenos: + + +.. _sol-state-on-lua-state: + +using sol3 on a lua_State\* +--------------------------- + +For your system/game that already has Lua or uses an in-house or pre-rolled Lua system (LuaBridge, kaguya, Luwra, etc.), but you'd still like sol3 and nice things: + + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/opening_state_on_raw_lua.cpp + :linenos: + +.. _running-lua-code: + +running lua code +---------------- + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/running_lua_code.cpp + :linenos: + :lines: 1-10, 16-26 + +To run Lua code but have an error handler in case things go wrong: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/running_lua_code.cpp + :linenos: + :lines: 28-39,47- + +You can see more use of safety by employing the use of `.safe_script`_, which returns a protected result you can use to properly check for errors and similar. + + +.. note:: + + If you have the safety definitions on, `.script` will call into the `.safe_script` versions automatically. Otherwise, it will call into the `.unsafe_script` versions. + + +running lua code (low-level) +---------------------------- + +You can use the individual load and function call operator to load, check, and then subsequently run and check code. + +.. warning:: + + This is ONLY if you need some sort of fine-grained control: for 99% of cases, :ref:`running lua code<running-lua-code>` is preferred and avoids pitfalls in not understanding the difference between script/load and needing to run a chunk after loading it. + + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/running_lua_code_low_level.cpp + :linenos: + :lines: 1-10, 16-40, 47-49 + +You can also `develop custom loaders`_ that pull from things that are not strings or files. + + +passing arguments to scripts +---------------------------- + +Arguments to Lua scripts can be passed by first loading the file or script blob, and then calling it using sol's abstractions. Then, in the script, access the variables with a `...` on the left hand side of an assignment: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/arguments_to_scripts.cpp + :linenos: + + +transferring functions (dumping bytecode) +----------------------------------------- + +You can dump the bytecode of a function, which allows you to transfer it to another state (or save it, or load it). Note that bytecode is *typically specific to the Lua version*! + +.. literalinclude:: ../../../examples/source//dump.cpp + :linenos: + + +set and get variables +--------------------- + +You can set/get everything using table-like syntax. + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp + :linenos: + :lines: 1-19 + +Equivalent to loading lua values like so: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp + :linenos: + :lines: 22-34 + +You can show they are equivalent: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp + :linenos: + :lines: 36-44 + +Retrieve these variables using this syntax: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp + :linenos: + :lines: 45-64 + +Retrieve Lua types using ``object`` and other ``sol::`` types. + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp + :linenos: + :lines: 66- + +You can erase things by setting it to ``nullptr`` or ``sol::lua_nil``. + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/set_and_get_variables_exists.cpp + :linenos: + +Note that if its a :doc:`userdata/usertype<../api/usertype>` for a C++ type, the destructor will run only when the garbage collector deems it appropriate to destroy the memory. If you are relying on the destructor being run when its set to ``sol::lua_nil``, you're probably committing a mistake. + +tables +------ + +Tables can be manipulated using accessor-syntax. Note that :doc:`sol::state<../api/state>` is a table and all the methods shown here work with ``sol::state``, too. + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp + :linenos: + :lines: 1-34 + +If you're going deep, be safe: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp + :linenos: + :lines: 35- + +make tables +----------- + +There are many ways to make a table. Here's an easy way for simple ones: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/make_tables.cpp + :linenos: + :lines: 1-21 + +Equivalent Lua code, and check that they're equivalent: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/make_tables.cpp + :linenos: + :lines: 22- + +You can put anything you want in tables as values or keys, including strings, numbers, functions, other tables. + +Note that this idea that things can be nested is important and will help later when you get into :ref:`namespacing<namespacing>`. + + +functions +--------- + +They're easy to use, from Lua and from C++: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/functions_easy.cpp + :linenos: + :lines: 1- + +If you need to protect against errors and parser problems and you're not ready to deal with Lua's ``longjmp`` problems (if you compiled with C), use :doc:`sol::protected_function<../api/protected_function>`. + +You can bind member variables as functions too, as well as all KINDS of function-like things: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/functions_all.cpp + :linenos: + :lines: 1-50 + +The lua code to call these things is: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/functions_all.cpp + :linenos: + :lines: 51- + +You can use ``sol::readonly( &some_class::variable )`` to make a variable readonly and error if someone tries to write to it. + + +self call +--------- + +You can pass the ``self`` argument through C++ to emulate 'member function' calls in Lua. + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/self_call.cpp + :linenos: + :lines: 1- + + +multiple returns from lua +------------------------- + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/multiple_returns_from_lua.cpp + :linenos: + :lines: 1- + + +multiple returns to lua +----------------------- + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/multiple_returns_to_lua.cpp + :linenos: + :lines: 1- + + +C++ classes from C++ +-------------------- + +Everything that is not a: + + * primitive type: ``bool``, ``char/short/int/long/long long``, ``float/double`` + * string type: ``std::string``, ``const char*`` + * function type: function pointers, ``lua_CFunction``, ``std::function``, :doc:`sol::function/sol::protected_function<../api/function>`, :doc:`sol::coroutine<../api/coroutine>`, member variable, member function + * designated sol type: :doc:`sol::table<../api/table>`, :doc:`sol::thread<../api/thread>`, :doc:`sol::error<../api/error>`, :doc:`sol::object<../api/object>` + * transparent argument type: :doc:`sol::variadic_arg<../api/variadic_args>`, :doc:`sol::this_state<../api/this_state>`, :doc:`sol::this_environment<../api/this_environment>` + * usertype<T> class: :doc:`sol::usertype<../api/usertype>` + +Is set as a :doc:`userdata + usertype<../api/usertype>`. + + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/userdata.cpp + :linenos: + :lines: 1-57,97- + +``std::unique_ptr``/``std::shared_ptr``'s reference counts / deleters will :doc:`be respected<../api/unique_usertype_traits>`. + +If you want it to refer to something, whose memory you know won't die in C++ while it is used/exists in Lua, do the following: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp + :linenos: + :lines: 1-45 + +You can retrieve the userdata in the same way as everything else. Importantly, note that you can change the data of usertype variables and it will affect things in lua if you get a pointer or a reference: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp + :linenos: + :lines: 46- + + +C++ classes put into Lua +------------------------ + +See this :doc:`section here<cxx-in-lua>`. Also check out a `basic example`_, `special functions example`_ and `initializers example`_! There are many more examples that show off the usage of classes in C++, so please peruse them all carefully as it can be as simple or as complex as your needs are. + + +.. _namespacing: + +namespacing +----------- + +You can emulate namespacing by having a table and giving it the namespace names you want before registering enums or usertypes: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/namespacing.cpp + :linenos: + :lines: 1- + + +This technique can be used to register namespace-like functions and classes. It can be as deep as you want. Just make a table and name it appropriately, in either Lua script or using the equivalent sol code. As long as the table FIRST exists (e.g., make it using a script or with one of sol's methods or whatever you like), you can put anything you want specifically into that table using :doc:`sol::table's<../api/table>` abstractions. + +there is a LOT more +------------------- + +Some more things you can do/read about: + * :doc:`the usertypes page<../usertypes>` lists the huge amount of features for functions + - :doc:`unique usertype traits<../api/unique_usertype_traits>` allows you to specialize handle/RAII types from other libraries frameworks, like boost and Unreal, to work with sol. Allows custom smart pointers, custom handles and others + * :doc:`the containers page<../containers>` gives full information about handling everything about container-like usertypes + * :doc:`the functions page<../functions>` lists a myriad of features for functions + - :doc:`variadic arguments<../api/variadic_args>` in functions with ``sol::variadic_args``. + - also comes with :doc:`variadic_results<../api/variadic_results>` for returning multiple differently-typed arguments + - :doc:`this_state<../api/this_state>` to get the current ``lua_State*``, alongside other transparent argument types + * :doc:`metatable manipulations<../api/metatable_key>` allow a user to change how indexing, function calls, and other things work on a single type. + * :doc:`ownership semantics<ownership>` are described for how Lua deals with its own internal references and (raw) pointers. + * :doc:`stack manipulation<../api/stack>` to safely play with the stack. You can also define customization points for ``stack::get``/``stack::check``/``stack::push`` for your type. + * :doc:`make_reference/make_object convenience function<../api/make_reference>` to get the same benefits and conveniences as the low-level stack API but put into objects you can specify. + * :doc:`stack references<../api/stack_reference>` to have zero-overhead sol abstractions while not copying to the Lua registry. + * :doc:`resolve<../api/resolve>` overloads in case you have overloaded functions; a cleaner casting utility. You must use this to emulate default parameters. + +.. _.safe_script: https://github.com/ThePhD/sol2/tree/develop/examples/source/tutorials/quick_n_dirty/running_lua_code_safely.cpp +.. _develop custom loaders: https://github.com/ThePhD/sol2/blob/develop/examples/source/custom_reader.cpp +.. _basic example: https://github.com/ThePhD/sol2/blob/develop/examples/source/usertype.cpp +.. _special functions example: https://github.com/ThePhD/sol2/blob/develop/examples/source/usertype_special_functions.cpp +.. _initializers example: https://github.com/ThePhD/sol2/blob/develop/examples/source/usertype_initializers.cpp +.. _sol3 tutorial examples: https://github.com/ThePhD/sol2/tree/develop/examples/source/tutorials/quick_n_dirty diff --git a/deps/sol2/docs/source/tutorial/customization.rst b/deps/sol2/docs/source/tutorial/customization.rst new file mode 100644 index 0000000..30bf6e2 --- /dev/null +++ b/deps/sol2/docs/source/tutorial/customization.rst @@ -0,0 +1,34 @@ +adding your own types +===================== + +Sometimes, overriding sol to make it handle certain ``struct``'s and ``class``'es as something other than just userdata is desirable. The way to do this is to take advantage of the 4 customization points for sol. These are ``sol_lua_check``, ``sol_lua_get``, ``sol_lua_push``, and ``sol_lua_check_get``. + +These are template class/structs, so you'll override them using a technique C++ calls *class/struct specialization*. Below is an example of a struct that gets broken apart into 2 pieces when going in the C++ --> Lua direction, and then pulled back into a struct when going in the Lua --> C++: + +.. literalinclude:: ../../../examples/source/customization_multiple.cpp + :name: customization-overriding + :caption: main.cpp + :linenos: + :lines: 1-52 + +This is the base formula that you can follow to extend to your own classes. Using it in the rest of the library should then be seamless: + +.. literalinclude:: ../../../examples/source/customization_multiple.cpp + :name: customization-overriding-use + :caption: main.cpp + :linenos: + :lines: 52- + +And that's it! + +A few things of note about the implementation: First, there's an auxiliary parameter of type :doc:`sol::stack::record<../api/stack>` for the getters and checkers. This keeps track of what the last complete operation performed. Since we retrieved 2 members, we use ``tracking.use(2);`` to indicate that we used 2 stack positions (one for ``bool``, one for ``int``). The second thing to note here is that we made sure to use the ``index`` parameter, and then proceeded to add 1 to it for the next one. + +You can make something pushable into Lua, but not get-able in the same way if you only specialize one part of the system. If you need to retrieve it (as a return using one or multiple values from Lua), you should specialize the ``sol::stack::getter`` template class and the ``sol::stack::checker`` template class. If you need to push it into Lua at some point, then you'll want to specialize the ``sol::stack::pusher`` template class. The ``sol::lua_size`` template class trait needs to be specialized for both cases, unless it only pushes 1 item, in which case the default implementation will assume 1. + +.. note:: + + It is important to note here that the ``gett``, ``push`` and ``check`` differentiate between a type ``T`` and a pointer to a type ``T*``. This means that if you want to work purely with, say, a ``T*`` handle that does not have the same semantics as just ``T``, you may need to specify checkers/getters/pushers for both ``T*`` and ``T``. The checkers for ``T*`` forward to the checkers for ``T``, but the getter for ``T*`` does not forward to the getter for ``T`` (e.g., because of ``int*`` not being quite the same as ``int``). + +In general, this is fine since most getters/checkers only use 1 stack point. But, if you're doing more complex nested classes, it would be useful to use ``tracking.last`` to understand how many stack indices the last gett/check operation did and increment it by ``index + tracking.last`` after using a ``stack::check<..>( L, index, tracking)`` call. + +You can read more about the extension points themselves :ref:`over on the API page for stack<extension_points>`, and if there's something that goes wrong or you have anymore questions, please feel free to drop a line on the Github Issues page or send an e-mail! diff --git a/deps/sol2/docs/source/tutorial/cxx-in-lua.rst b/deps/sol2/docs/source/tutorial/cxx-in-lua.rst new file mode 100644 index 0000000..7f792c0 --- /dev/null +++ b/deps/sol2/docs/source/tutorial/cxx-in-lua.rst @@ -0,0 +1,47 @@ +C++ in Lua +========== + +Using user defined types ("usertype"s, or just "udt"s) is simple with sol. If you don't call any member variables or functions, then you don't even have to 'register' the usertype at all: just pass it through. But if you want variables and functions on your usertype inside of Lua, you need to register it. We're going to give a short example here that includes a bunch of information on how to work with things. + +Take this ``player`` struct in C++ in a header file: + +.. literalinclude:: ../../../examples/source/usertype_advanced.cpp + :caption: player.hpp + :name: tutorial-player-class + :linenos: + :lines: 8-51 + +It's a fairly minimal class, but we don't want to have to rewrite this with metatables in Lua. We want this to be part of Lua easily. The following is the Lua code that we'd like to have work properly: + +.. literalinclude:: ../../../examples/source/usertype_advanced.cpp + :caption: player_script.lua + :name: tutorial-player-script + :language: lua + :linenos: + :lines: 97-127 + +To do this, you bind things using the ``new_usertype`` and method as shown below. These methods are on both :doc:`table<../api/table>` and :doc:`state(_view)<../api/state>`, but we're going to just use it on ``state``: + +.. literalinclude:: ../../../examples/source/usertype_advanced.cpp + :caption: main.cpp + :name: tutorial-player-usertype + :language: cpp + :linenos: + :lines: 1-3,5,7-9,53,55-85,135-136,143- + +There is one more method used in the script that is not in C++ or defined on the C++ code to bind a usertype, called ``brake``. Even if a method does not exist in C++, you can add methods to the *class table* in Lua: + +.. literalinclude:: ../../../examples/source/usertype_advanced.cpp + :caption: prelude_script.lua + :name: tutorial-prelude-script + :language: lua + :linenos: + :lines: 89-92 + +That script should run fine now, and you can observe and play around with the values. Even more stuff :doc:`you can do<../api/usertype>` is described elsewhere, like initializer functions (private constructors / destructors support), "static" functions callable with ``name.my_function( ... )``, and overloaded member functions. You can even bind global variables (even by reference with ``std::ref``) with ``sol::var``. There's a lot to try out! + +This is a powerful way to allow reuse of C++ code from Lua beyond just registering functions, and should get you on your way to having more complex classes and data structures! In the case that you need more customization than just usertypes, however, you can customize sol to behave more fit to your desires by using the desired :doc:`customization and extension structures<customization>`. + +You can check out this code and more complicated code at the `examples directory`_ by looking at the ``usertype_``-prefixed examples. + +.. _examples directory: https://github.com/ThePhD/sol2/tree/develop/examples
\ No newline at end of file diff --git a/deps/sol2/docs/source/tutorial/existing.rst b/deps/sol2/docs/source/tutorial/existing.rst new file mode 100644 index 0000000..a78d046 --- /dev/null +++ b/deps/sol2/docs/source/tutorial/existing.rst @@ -0,0 +1,39 @@ +integrating into existing code +============================== + +If you're already using lua and you just want to use ``sol`` in some places, you can use ``state_view``: + +.. code-block:: cpp + :linenos: + :caption: using state_view + :name: state-view-snippet + + int something_in_my_system (lua_State* L) { + // start using sol with a pre-existing system + sol::state_view lua(L); // non-owning + + lua.script("print('bark bark bark!')"); + + // get the table off the top of the stack + sol::table expected_table(L, -1); + // start using it... + + return 0; // or whatever you require of working with a raw function + } + +:doc:`sol::state_view<../api/state>` is exactly like ``sol::state``, but it doesn't manage the lifetime of a ``lua_State*``. Therefore, you get all the goodies that come with a ``sol::state`` without any of the ownership implications. sol has no initialization components that need to deliberately remain alive for the duration of the program. It's entirely self-containing and uses lua's garbage collectors and various implementation techniques to require no state C++-side. After you do that, all of the power of `sol` is available to you, and then some! + +``sol::state_view`` is also helpful when you want to `create a DLL that loads some Lua module`_ via requires. + +You may also want to call ``require`` and supply a string of a script file or something that returns an object that you set equal to something in C++. For that, you can use the :ref:`require functionality<state-require-function>`. + +Remember that sol can be as lightweight as you want it: almost all of sol's Lua types take the ``lua_State*`` argument and then a second ``int index`` stack index argument, meaning you can use :doc:`tables<../api/table>`, :doc:`lua functions<../api/function>`, :doc:`coroutines<../api/coroutine>`, and other reference-derived objects that expose the proper constructor for your use. You can also set :doc:`usertypes<../api/usertype>` and other things you need without changing your entire architecture in one go. + +You can even customize it to `work with an external Lua wrapper/framework/library`_. + +Note that you can also make non-standard pointer and reference types with custom reference counting and such also play nice with the system. See :doc:`unique_usertype_traits\<T><../api/unique_usertype_traits>` to see how! Custom types is also mentioned in the :doc:`customization tutorial<customization>`. + +There are a few things that creating a ``sol::state`` does for you. You can read about it :ref:`in the sol::state docs<state-automatic-handlers>` and call those functions directly if you need them. + +.. _create a DLL that loads some Lua module: https://github.com/ThePhD/sol2/tree/develop/examples/require_dll_example +.. _work with an external Lua wrapper/framework/library: https://github.com/ThePhD/sol2/tree/develop/examples/interop diff --git a/deps/sol2/docs/source/tutorial/functions.rst b/deps/sol2/docs/source/tutorial/functions.rst new file mode 100644 index 0000000..7536ff8 --- /dev/null +++ b/deps/sol2/docs/source/tutorial/functions.rst @@ -0,0 +1,341 @@ +functions and You +================= + +sol can register all kinds of functions. Many are shown in the :doc:`quick 'n' dirty<all-the-things>`, but here we will discuss many of the additional ways you can register functions into a sol-wrapped Lua system. + +Setting a new function +---------------------- + +Given a C++ function, you can drop it into sol in several equivalent ways, working similar to how :ref:`setting variables<writing-variables-demo>` works: + +.. code-block:: cpp + :linenos: + :caption: Registering C++ functions + :name: writing-functions + + #include <sol/sol.hpp> + + std::string my_function( int a, std::string b ) { + // Create a string with the letter 'D' "a" times, + // append it to 'b' + return b + std::string( 'D', a ); + } + + int main () { + + sol::state lua; + + lua["my_func"] = my_function; // way 1 + lua.set("my_func", my_function); // way 2 + lua.set_function("my_func", my_function); // way 3 + + // This function is now accessible as 'my_func' in + // lua scripts / code run on this state: + lua.script("some_str = my_func(1, 'Da')"); + + // Read out the global variable we stored in 'some_str' in the + // quick lua code we just executed + std::string some_str = lua["some_str"]; + // some_str == "DaD" + } + +The same code works with all sorts of functions, from member function/variable pointers you have on a class as well as lambdas: + +.. code-block:: cpp + :linenos: + :caption: Registering C++ member functions + :name: writing-member-functions + + struct my_class { + int a = 0; + + my_class(int x) : a(x) { + + } + + int func() { + ++a; // increment a by 1 + return a; + } + }; + + int main () { + + sol::state lua; + + // Here, we are binding the member function and a class instance: it will call the function on + // the given class instance + lua.set_function("my_class_func", &my_class::func, my_class()); + + // We do not pass a class instance here: + // the function will need you to pass an instance of "my_class" to it + // in lua to work, as shown below + lua.set_function("my_class_func_2", &my_class::func); + + // With a pre-bound instance: + lua.script(R"( + first_value = my_class_func() + second_value = my_class_func() + )"); + // first_value == 1 + // second_value == 2 + + // With no bound instance: + lua.set("obj", my_class(24)); + // Calls "func" on the class instance + // referenced by "obj" in Lua + lua.script(R"( + third_value = my_class_func_2(obj) + fourth_value = my_class_func_2(obj) + )"); + // first_value == 25 + // second_value == 26 + } + +Member class functions and member class variables will both be turned into functions when set in this manner. You can get intuitive variable with the ``obj.a = value`` access after this section when you learn about :doc:`usertypes to have C++ in Lua<cxx-in-lua>`, but for now we're just dealing with functions! + + +Another question a lot of people have is about function templates. Function templates -- member functions or free functions -- cannot be registered because they do not exist until you instantiate them in C++. Therefore, given a templated function such as: + +.. code-block:: cpp + :linenos: + :caption: A C++ templated function + :name: writing-templated-functions-the-func + + template <typename A, typename B> + auto my_add( A a, B b ) { + return a + b; + } + + +You must specify all the template arguments in order to bind and use it, like so: + +.. code-block:: cpp + :linenos: + :caption: Registering function template instantiations + :name: writing-templated-functions + + + int main () { + + sol::state lua; + + // adds 2 integers + lua["my_int_add"] = my_add<int, int>; + + // concatenates 2 strings + lua["my_string_combine"] = my_add<std::string, std::string>; + + lua.script("my_num = my_int_add(1, 2)"); + int my_num = lua["my_num"]; + // my_num == 3 + + lua.script("my_str = my_string_combine('bark bark', ' woof woof')"); + std::string my_str = lua["my_str"]; + // my_str == "bark bark woof woof" + } + +Notice here that we bind two separate functions. What if we wanted to bind only one function, but have it behave differently based on what arguments it is called with? This is called Overloading, and it can be done with :doc:`sol::overload<../api/overload>` like so: + +.. code-block:: cpp + :linenos: + :caption: Registering C++ function template instantiations + :name: writing-templated-functions-overloaded + + + int main () { + + sol::state lua; + + // adds 2 integers + lua["my_combine"] = sol::overload( my_add<int, int>, my_add<std::string, std::string> ); + + lua.script("my_num = my_combine(1, 2)"); + lua.script("my_str = my_combine('bark bark', ' woof woof')"); + int my_num = lua["my_num"]; + std::string my_str = lua["my_str"]; + // my_num == 3 + // my_str == "bark bark woof woof" + } + +This is useful for functions which can take multiple types and need to behave differently based on those types. You can set as many overloads as you want, and they can be of many different types. + +As a side note, binding functions with default parameters does not magically bind multiple versions of the function to be called with the default parameters. You must instead use :doc:`sol::overload<../api/overload>`. + +As a side note, please make sure to understand Make sure you understand the :ref:`implications of binding a lambda/callable struct in the various ways<binding-callable-objects>` and what it means for your code! + + +Getting a function from Lua +--------------------------- + +There are 2 ways to get a function from Lua. One is with :doc:`sol::function<../api/function>` and the other is a more advanced wrapper with :doc:`sol::protected_function<../api/protected_function>`. Use them to retrieve callables from Lua and call the underlying function, in two ways: + +.. code-block:: cpp + :linenos: + :caption: Retrieving a sol::function + :name: reading-functions + + int main () { + + sol::state lua; + + lua.script(R"( + function f (a) + return a + 5 + end + )"); + + // Get and immediately call + int x = lua["f"](30); + // x == 35 + + // Store it into a variable first, then call + sol::function f = lua["f"]; + int y = f(20); + // y == 25 + } + +You can get anything that's a callable in Lua, including C++ functions you bind using ``set_function`` or similar. ``sol::protected_function`` behaves similarly to ``sol::function``, but has a :ref:`error_handler<protected-function-error-handler>` variable you can set to a Lua function. This catches all errors and runs them through the error-handling function: + + +.. code-block:: cpp + :linenos: + :caption: Retrieving a sol::protected_function + :name: reading-protected-functions + + int main () { + sol::state lua; + + lua.script(R"( + function handler (message) + return "Handled this message: " .. message + end + + function f (a) + if a < 0 then + error("negative number detected") + end + return a + 5 + end + )"); + + sol::protected_function f = lua["f"]; + f.error_handler = lua["handler"]; + + sol::protected_function_result result = f(-500); + if (result.valid()) { + // Call succeeded + int x = result; + } + else { + // Call failed + sol::error err = result; + std::string what = err.what(); + // 'what' Should read + // "Handled this message: negative number detected" + } + } + + +Multiple returns to and from Lua +-------------------------------- + +You can return multiple items to and from Lua using ``std::tuple``/``std::pair`` classes provided by C++. These enable you to also use :doc:`sol::tie<../api/tie>` to set return values into pre-declared items. To recieve multiple returns, just ask for a ``std::tuple`` type from the result of a function's computation, or ``sol::tie`` a bunch of pre-declared variables together and set the result equal to that: + +.. code-block:: cpp + :linenos: + :caption: Multiple returns from Lua + :name: multi-return-lua-functions + + int main () { + sol::state lua; + + lua.script("function f (a, b, c) return a, b, c end"); + + std::tuple<int, int, int> result; + result = lua["f"](1, 2, 3); + // result == { 1, 2, 3 } + int a, int b; + std::string c; + sol::tie( a, b, c ) = lua["f"](1, 2, "bark"); + // a == 1 + // b == 2 + // c == "bark" + } + +You can also return mutiple items yourself from a C++-bound function. Here, we're going to bind a C++ lambda into Lua, and then call it through Lua and get a ``std::tuple`` out on the other side: + +.. code-block:: cpp + :linenos: + :caption: Multiple returns into Lua + :name: multi-return-cxx-functions + + int main () { + sol::state lua; + + lua["f"] = [](int a, int b, sol::object c) { + // sol::object can be anything here: just pass it through + return std::make_tuple( a, b, c ); + }; + + std::tuple<int, int, int> result = lua["f"](1, 2, 3); + // result == { 1, 2, 3 } + + std::tuple<int, int, std::string> result2; + result2 = lua["f"](1, 2, "Arf?") + // result2 == { 1, 2, "Arf?" } + + int a, int b; + std::string c; + sol::tie( a, b, c ) = lua["f"](1, 2, "meow"); + // a == 1 + // b == 2 + // c == "meow" + } + + +Note here that we use :doc:`sol::object<../api/object>` to transport through "any value" that can come from Lua. You can also use ``sol::make_object`` to create an object from some value, so that it can be returned into Lua as well. + + +Any return to and from Lua +-------------------------- + +It was hinted at in the previous code example, but ``sol::object`` is a good way to pass "any type" back into Lua (while we all wait for ``std::variant<...>`` to get implemented and shipped by C++ compiler/library implementers). + +It can be used like so, inconjunction with ``sol::this_state``: + +.. code-block:: cpp + :linenos: + :caption: Return anything into Lua + :name: object-return-cxx-functions + + sol::object fancy_func (sol::object a, sol::object b, sol::this_state s) { + sol::state_view lua(s); + if (a.is<int>() && b.is<int>()) { + return sol::make_object(lua, a.as<int>() + b.as<int>()); + } + else if (a.is<bool>()) { + bool do_triple = a.as<bool>(); + return sol::make_object(lua, b.as<double>() * ( do_triple ? 3 : 1 ) ); + } + return sol::make_object(lua, sol::lua_nil); + } + + int main () { + sol::state lua; + + lua["f"] = fancy_func; + + int result = lua["f"](1, 2); + // result == 3 + double result2 = lua["f"](false, 2.5); + // result2 == 2.5 + + // call in Lua, get result + lua.script("result3 = f(true, 5.5)"); + double result3 = lua["result3"]; + // result3 == 16.5 + } + + +This covers almost everything you need to know about Functions and how they interact with sol. For some advanced tricks and neat things, check out :doc:`sol::this_state<../api/this_state>` and :doc:`sol::variadic_args<../api/variadic_args>`. The next stop in this tutorial is about :doc:`C++ types (usertypes) in Lua<cxx-in-lua>`! If you need a bit more information about functions in the C++ side and how to best utilize arguments from C++, see :ref:`this note<function-argument-handling>`. diff --git a/deps/sol2/docs/source/tutorial/getting-started.rst b/deps/sol2/docs/source/tutorial/getting-started.rst new file mode 100644 index 0000000..8f19bf2 --- /dev/null +++ b/deps/sol2/docs/source/tutorial/getting-started.rst @@ -0,0 +1,59 @@ +getting started +=============== + +Let's get you going with sol! To start, you'll need to use a lua distribution of some sort. sol doesn't provide that: it only wraps the API that comes with it, so you can pick whatever distribution you like for your application. There are lots, but the two popular ones are `vanilla Lua`_ and speedy `LuaJIT`_ . We recommend vanilla Lua if you're getting started, LuaJIT if you need speed and can handle some caveats: the interface for sol doesn't change no matter what Lua version you're using. + +If you need help getting or building Lua, check out the `Lua page on getting started`_. Note that for Visual Studio, one can simply download the sources, include all the Lua library files in that project, and then build for debug/release, x86/x64/ARM rather easily and with minimal interference. Just make sure to adjust the Project Property page to build as a static library (or a DLL with the proper define set in the ``Preprocessor`` page, eg. `LUA_BUILD_AS_DLL=1`). + +After that, make sure you grab either the `single header file release`_, or just perform a clone of the `github repository here`_ and set your include paths up so that you can get at ``sol.hpp`` somehow. Note that we also have the latest version of the single header file with all dependencies included kept in the `repository as well`_. We recommend the single-header-file release, since it's easier to move around, manage and update if you commit it with some form of version control. You can also clone/submodule the repository and then point at the `single/sol/sol.hpp`_ on your include files path. Clone with: + +>>> git clone https://github.com/ThePhD/sol2.git + +When you're ready, try compiling this short snippet: + +.. literalinclude:: ../../../examples/source/tutorials/first_snippet.cpp + :linenos: + :caption: hello_lua.cpp + :name: hello-lua + +Using this simple command line: + +>>> g++ -std=c++17 test.cpp -I"path/to/sol/include" -I"path/to/lua/include" -L"path/to/lua/lib" -llua + +Or using your favorite IDE / tool after setting up your include paths and library paths to Lua according to the documentation of the Lua distribution you got. Remember your linked lua library (``-llua``) and include / library paths will depend on your OS, file system, Lua distribution and your installation / compilation method of your Lua distribution. + +.. note:: + + If you get an avalanche of errors (particularly referring to ``auto``), you may not have enabled C++14 / C++17 mode for your compiler. Add one of ``std=c++17``, ``std=c++1z`` OR ``std=c++1y`` to your compiler options. By default, this is always-on for VC++ compilers in Visual Studio and friends, but g++ and clang++ require a flag (unless you're on `GCC 6.0`_ or better). + +If this works, you're ready to start! The first line creates the ``lua_State`` and will hold onto it for the duration of the scope its declared in (e.g., from the opening ``{`` to the closing ``}``). It will automatically close / cleanup that lua state when it gets destructed. + +The second line opens a single lua-provided library, "base". There are several other libraries that come with lua that you can open by default, and those are included in the :ref:`sol::lib<lib-enum>` enumeration. You can open multiple base libraries by specifying multiple ``sol::lib`` arguments: + +.. literalinclude:: ../../../examples/source/tutorials/open_multiple_libraries.cpp + :linenos: + :caption: multiple_libraries.cpp + :name: open-multiple-libraries + +If you're interested in integrating sol with a project that already uses some other library or Lua in the codebase, check out the :doc:`existing example<existing>` to see how to work with sol when you add it to a project (the existing example covers ``require`` as well)! + +.. note:: + + After you learn the basics of sol, it is usually advised that if you think something can work, you should TRY IT. It will probably work! + + +Some more ways of loading scripts and handling errors is shown `in this example`_! There is also a full, cross-platform `example of loading a DLL`_. + +Next, let's start :doc:`reading/writing some variables<variables>` from Lua into C++, and vice-versa! + + +.. _vanilla Lua: https://www.lua.org/ +.. _LuaJIT: http://luajit.org/ +.. _GCC 6.0: https://gcc.gnu.org/gcc-6/changes.html +.. _single header file release: https://github.com/ThePhD/sol2/releases +.. _repository as well: https://github.com/ThePhD/sol2/blob/develop/single/include/sol/sol.hpp +.. _single/sol/sol.hpp: https://github.com/ThePhD/sol2/blob/develop/single/include/sol/sol.hpp +.. _github repository here: https://github.com/ThePhD/sol2 +.. _Lua page on getting started: https://www.lua.org/start.html +.. _in this example: https://github.com/ThePhD/sol2/blob/develop/examples/source/basic.cpp +.. _example of loading a DLL: https://github.com/ThePhD/sol2/tree/develop/examples/require_dll_example diff --git a/deps/sol2/docs/source/tutorial/ownership.rst b/deps/sol2/docs/source/tutorial/ownership.rst new file mode 100644 index 0000000..78027ae --- /dev/null +++ b/deps/sol2/docs/source/tutorial/ownership.rst @@ -0,0 +1,62 @@ +ownership +========= + +Ownership is important when managing resources in C++. sol has many ownership semantics which are generally safe by default. Below are the rules. + +object ownership +---------------- + +You can take a reference to something that exists in Lua by pulling out a :doc:`sol::reference<../api/reference>` or a :doc:`sol::object<../api/object>`: + +.. literalinclude:: ../../../examples/source/tutorials/object_lifetime.cpp + :linenos: + :caption: object_lifetime.cpp + +All objects must be destroyed before the `sol::state` is destroyed, otherwise you will end up with dangling references to the Lua State and things will explode in horrible, terrible fashion. + +This applies to more than just `sol::object`: all types derived from `sol::reference` and `sol::object` (:doc:`sol::table<../api/table>` :doc:`sol::userdata<../api/userdata>`, etc.) must be cleaned up before the state goes out of scope. + + +pointer ownership +----------------- + +sol will not take ownership of raw pointers: raw pointers do not own anything. sol will not delete raw pointers, because they do not (and are not supposed to) own anything: + +.. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp + :linenos: + :caption: pointer_lifetime.cpp + :name: pointer-lifetime-raw-ptr + :lines: 1-11,14-22, 74- + +Use/return a ``unique_ptr`` or ``shared_ptr`` instead or just return a value: + +.. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp + :linenos: + :caption: (smart pointers) pointer_lifetime.cpp + :name: pointer-lifetime-smart-ptr + :lines: 1-11,14-22, 74- + +If you have something you know is going to last and you just want to give it to Lua as a reference, then it's fine too: + +.. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp + :linenos: + :caption: (static) pointer_lifetime.cpp + :name: pointer-lifetime-static + :lines: 1-11,46-49,74- + + +sol can detect ``nullptr``, so if you happen to return it there won't be any dangling because a ``sol::lua_nil`` will be pushed. But if you know it's ``nil`` beforehand, please return ``std::nullptr_t`` or ``sol::lua_nil``: + +.. literalinclude:: ../../../examples/source/tutorials/pointer_lifetime.cpp + :linenos: + :caption: (nil/nullptr) pointer_lifetime.cpp + :name: pointer-lifetime-nil + :lines: 1-11,51- + + +ephermeal (proxy) objects +------------------------- + +:doc:`Proxy<../api/proxy>` and result types are ephermeal. They rely on the Lua stack and their constructors / destructors interact with the Lua stack. This means they are entirely unsafe to return from functions in C++, without very careful attention paid to how they are used that often requires relying on implementation-defined behaviors. + +Please be careful when using `(protected_)function_result`, `load_result` (especially multiple load/function results in a single C++ function!) `stack_reference`, and similar stack-based things. If you want to return these things, consider diff --git a/deps/sol2/docs/source/tutorial/tutorial-top.rst b/deps/sol2/docs/source/tutorial/tutorial-top.rst new file mode 100644 index 0000000..ee152b6 --- /dev/null +++ b/deps/sol2/docs/source/tutorial/tutorial-top.rst @@ -0,0 +1,21 @@ +tutorial +======== + +Take some time to learn the framework with these tutorials. But, if you need to get going FAST, try using the :doc:`quick 'n' dirty<all-the-things>` approach and your browser's / editors search function. It will also serve you well to look at all the `examples`_, which have recently gotten a bit of an overhaul to contain more relevant working examples and other advanced tricks that you can leverage to have a good time! + + +.. toctree:: + :caption: sol Tutorial + :name: tutorialtoc + :maxdepth: 2 + + all-the-things + getting-started + existing + variables + functions + cxx-in-lua + ownership + customization + +.. _examples: https://github.com/ThePhD/sol2/tree/develop/examples diff --git a/deps/sol2/docs/source/tutorial/variables.rst b/deps/sol2/docs/source/tutorial/variables.rst new file mode 100644 index 0000000..d2b7d3b --- /dev/null +++ b/deps/sol2/docs/source/tutorial/variables.rst @@ -0,0 +1,70 @@ +variables +========= + +Working with variables is easy with sol, and behaves pretty much like any associative array / map structure you might have dealt with previously. + +reading +------- + +Given this lua file that gets loaded into sol: + +.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp + :linenos: + :lines: 15-18 + +You can interact with the Lua Virtual Machine like so: + + +.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp + :linenos: + :lines: 1-10, 12-12, 20-24, 70- + +From this example, you can see that there's many ways to pull out the varaibles you want. For example, to determine if a nested variable exists or not, you can use ``auto`` to capture the value of a ``table[key]`` lookup, and then use the ``.valid()`` method: + + +.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp + :linenos: + :lines: 1-10, 12-12, 34-43, 70- + + +This comes in handy when you want to check if a nested variable exists. You can also check if a toplevel variable is present or not by using ``sol::optional``, which also checks if A) the keys you're going into exist and B) the type you're trying to get is of a specific type: + +.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp + :linenos: + :caption: optional lookup + :lines: 1-10, 12-12, 43-58, 70- + + +This can come in handy when, even in optimized or release modes, you still want the safety of checking. You can also use the `get_or` methods to, if a certain value may be present but you just want to default the value to something else: + +.. literalinclude:: ../../../examples/source/tutorials/variables_demo.cpp + :linenos: + :caption: optional lookup + :lines: 1-10, 12-12, 60- + + +That's all it takes to read variables! + + +writing +------- + +Writing gets a lot simpler. Even without scripting a file or a string, you can read and write variables into lua as you please: + +.. literalinclude:: ../../../examples/source/tutorials/write_variables_demo.cpp + :linenos: + :name: writing-variables-demo + +This example pretty much sums up what can be done. Note that the syntax ``lua["non_existing_key_1"] = 1`` will make that variable, but if you tunnel too deep without first creating a table, the Lua API will panic (e.g., ``lua["does_not_exist"]["b"] = 20`` will trigger a panic). You can also be lazy with reading / writing values: + +.. literalinclude:: ../../../examples/source/tutorials/lazy_demo.cpp + :linenos: + + +Finally, it's possible to erase a reference/variable by setting it to ``nil``, using the constant ``sol::lua_nil`` in C++: + +.. literalinclude:: ../../../examples/source/tutorials/erase_demo.cpp + :linenos: + + +It's easy to see that there's a lot of options to do what you want here. But, these are just traditional numbers and strings. What if we want more power, more capabilities than what these limited types can offer us? Let's throw some :doc:`functions in there<functions>` :doc:`C++ classes into the mix<cxx-in-lua>`! |