1state 2===== 3owning and non-owning state holders for registry and globals 4------------------------------------------------------------ 5 6.. code-block:: cpp 7 8 class state_view; 9 10 class state : state_view, std::unique_ptr<lua_State*, deleter>; 11 12The 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. 13 14The majority of the members between ``state_view`` and :doc:`sol::table<table>` are identical, with added for this higher-level type. Therefore, all of the examples and notes in :doc:`sol::table<table>` apply here as well. 15 16enumerations 17------------ 18 19.. code-block:: cpp 20 :caption: in-lua libraries 21 :name: lib-enum 22 23 enum class lib : char { 24 base, 25 package, 26 coroutine, 27 string, 28 os, 29 math, 30 table, 31 debug, 32 bit32, 33 io, 34 ffi, 35 jit, 36 count // do not use 37 }; 38 39This enumeration details the various base libraries that come with Lua. See the `standard lua libraries`_ for details about the various standard libraries. 40 41 42members 43------- 44 45.. code-block:: cpp 46 :caption: function: open standard libraries/modules 47 :name: open-libraries 48 49 template<typename... Args> 50 void open_libraries(Args&&... args); 51 52This function takes a number of :ref:`sol::lib<lib-enum>` as arguments and opens up the associated Lua core libraries. 53 54.. code-block:: cpp 55 :caption: function: script / script_file 56 :name: state-script-function 57 58 sol::function_result script(const std::string& code); 59 sol::function_result script_file(const std::string& filename); 60 61These functions run the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It will not run isolated: any scripts or code run will affect code in the ``lua_State*`` the object uses as well (unless ``local`` is applied to a variable declaration, as specified by the Lua language). Code ran in this fashion is not isolated. If you need isolation, consider creating a new state or traditional Lua sandboxing techniques. 62 63If your script returns a value, you can capture it from the returned :ref:`function_result<function-result>`. 64 65.. code-block:: cpp 66 :caption: function: require / require_file 67 :name: state-require-function 68 69 sol::object require(const std::string& key, lua_CFunction open_function, bool create_global = true); 70 sol::object require_script(const std::string& key, const std::string& code, bool create_global = true); 71 sol::object require_file(const std::string& key, const std::string& file, bool create_global = true); 72 73These functions play a role similar to `luaL_requiref`_ except that they make this functionality available for loading a one-time script or a single file. The code here checks if a module has already been loaded, and if it has not, will either load / execute the file or execute the string of code passed in. If ``create_global`` is set to true, it will also link the name ``key`` to the result returned from the open function, the code or the file. Regardless or whether a fresh load happens or not, the returned module is given as a single :doc:`sol::object<object>` for you to use as you see fit. 74 75Thanks to `Eric (EToreo) for the suggestion on this one`_! 76 77.. code-block:: cpp 78 :caption: function: load / load_file 79 :name: state-load-code 80 81 sol::load_result load(const std::string& code); 82 sol::load_result load_file(const std::string& filename); 83 84These functions *load* the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It will not run: it returns a ``load_result`` proxy that can be called to actually run the code, turned into a ``sol::function``, a ``sol::protected_function``, or some other abstraction. If it is called, it will run on the object's current ``lua_State*``: it is not isolated. If you need isolation, consider creating a new state or traditional Lua sandboxing techniques. 85 86.. code-block:: cpp 87 :caption: function: do_string / do_file 88 :name: state-do-code 89 90 sol::protected_function_result do_string(const std::string& code); 91 sol::protected_function_result do_file(const std::string& filename); 92 93These functions *loads and performs* the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It *will* run, and then return a ``protected_function_result`` proxy that can be examined for either an error or the return value. 94 95.. code-block:: cpp 96 :caption: function: global table / registry table 97 98 sol::global_table globals() const; 99 sol::table registry() const; 100 101Get either the global table or the Lua registry as a :doc:`sol::table<table>`, which allows you to modify either of them directly. Note that getting the global table from a ``state``/``state_view`` is usually unnecessary as it has all the exact same functions as a :doc:`sol::table<table>` anyhow. 102 103 104.. code-block:: cpp 105 :caption: function: set_panic 106 :name: set-panic 107 108 void set_panic(lua_CFunction panic); 109 110Overrides the panic function Lua calls when something unrecoverable or unexpected happens in the Lua VM. Must be a function of the that matches the ``int(lua_State*)`` function signature. 111 112 113.. code-block:: cpp 114 :caption: function: memory_used 115 :name: memory-used 116 117 std::size_t memory_used() const; 118 119Returns the amount of memory used *in bytes* by the Lua State. 120 121 122.. code-block:: cpp 123 :caption: function: collect_garbage 124 :name: collect-garbage 125 126 void collect_garbage(); 127 128Attempts to run the garbage collector. Note that this is subject to the same rules as the Lua API's collect_garbage function: memory may or may not be freed, depending on dangling references or other things, so make sure you don't have tables or other stack-referencing items currently alive or referenced that you want to be collected. 129 130 131.. code-block:: cpp 132 :caption: function: make a table 133 134 sol::table create_table(int narr = 0, int nrec = 0); 135 template <typename Key, typename Value, typename... Args> 136 sol::table create_table(int narr, int nrec, Key&& key, Value&& value, Args&&... args); 137 138 139 template <typename... Args> 140 sol::table create_table_with(Args&&... args); 141 142 static sol::table create_table(lua_State* L, int narr = 0, int nrec = 0); 143 template <typename Key, typename Value, typename... Args> 144 static sol::table create_table(lua_State* L, int narr, int nrec, Key&& key, Value&& value, Args&&... args); 145 146Creates a table. Forwards its arguments to :ref:`table::create<table-create>`. 147 148.. _standard lua libraries: http://www.lua.org/manual/5.3/manual.html#6 149.. _luaL_requiref: https://www.lua.org/manual/5.3/manual.html#luaL_requiref 150.. _Eric (EToreo) for the suggestion on this one: https://github.com/ThePhD/sol2/issues/90