1types 2===== 3nil, lua_primitive type traits, and other fundamentals 4------------------------------------------------------ 5 6The ``types.hpp`` header contains various fundamentals and utilities of Sol. 7 8 9enumerations 10------------ 11 12.. code-block:: cpp 13 :caption: syntax of a function called by Lua 14 :name: call-syntax 15 16 enum class call_syntax { 17 dot = 0, 18 colon = 1 19 }; 20 21This 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. 22 23.. code-block:: cpp 24 :caption: status of a Lua function call 25 :name: call-status 26 27 enum class call_status : int { 28 ok = LUA_OK, 29 yielded = LUA_YIELD, 30 runtime = LUA_ERRRUN, 31 memory = LUA_ERRMEM, 32 handler = LUA_ERRERR, 33 gc = LUA_ERRGCMM 34 }; 35 36This strongly-typed enumeration contains the errors potentially generated by a call to a :doc:`protected function<protected_function>` or a :doc:`coroutine<coroutine>`. 37 38.. code-block:: cpp 39 :caption: status of a Lua thread 40 :name: thread-status 41 42 enum class thread_status : int { 43 ok = LUA_OK, 44 yielded = LUA_YIELD, 45 runtime = LUA_ERRRUN, 46 memory = LUA_ERRMEM, 47 gc = LUA_ERRGCMM, 48 handler = LUA_ERRERR, 49 dead, 50 }; 51 52This 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. 53 54.. code-block:: cpp 55 :caption: status of a Lua load operation 56 :name: load-status 57 58 enum class load_status : int { 59 ok = LUA_OK, 60 runtime = LUA_ERRSYNTAX, 61 memory = LUA_ERRMEM, 62 gc = LUA_ERRGCMM, 63 file = LUA_ERRFILE, 64 }; 65 66This enumeration contains the status of a load operation from :ref:`state::load(_file)<state-load-code>`. 67 68.. code-block:: cpp 69 :caption: type enumeration 70 :name: type-enum 71 72 enum class type : int { 73 none = LUA_TNONE, 74 nil = LUA_TNIL, 75 string = LUA_TSTRING, 76 number = LUA_TNUMBER, 77 thread = LUA_TTHREAD, 78 boolean = LUA_TBOOLEAN, 79 function = LUA_TFUNCTION, 80 userdata = LUA_TUSERDATA, 81 lightuserdata = LUA_TLIGHTUSERDATA, 82 table = LUA_TTABLE, 83 poly = none | nil | string | number | thread | 84 table | boolean | function | userdata | lightuserdata 85 }; 86 87The base types that Lua natively communicates in and understands. Note that "poly" isn't really a true type, it's just a symbol used in Sol for something whose type hasn't been checked (and you should almost never see it). 88 89 90type traits 91----------- 92 93.. code-block:: cpp 94 :caption: lua_type_of trait 95 :name: lua-type-of 96 97 template <typename T> 98 struct lua_type_of; 99 100This type trait maps a C++ type to a :ref:`type enumeration<type-enum>` value. The default value is ``type::userdata``. 101 102.. code-block:: cpp 103 :caption: primitive checking traits 104 :name: is-primitive 105 106 template <typename T> 107 struct is_lua_primitive; 108 109 template <typename T> 110 struct is_proxy_primitive; 111 112 113This trait is used by :doc:`proxy<proxy>` to know which types should be returned as references to internal Lua memory (e.g., ``userdata`` types) and which ones to return as values (strings, numbers, :doc:`references<reference>`). ``std::reference_wrapper``, ``std::tuple<...>`` are returned as values, but their contents can be references. The default value is false. 114 115special types 116------------- 117 118.. code-block:: cpp 119 :caption: nil 120 :name: nil 121 122 strunil_t {}; 123 const nil_t nil {}; 124 bool operator==(nil_t, nil_t); 125 bool operator!=(nil_t, nil_t); 126 127``nil`` is a constant used to signify Lua's ``nil``, which is a type and object that something does not exist. It is comparable to itself, :doc:`sol::object<object>` and :doc:`proxy values<proxy>`. 128 129 130.. code-block:: cpp 131 :caption: non_null 132 133 template <typename T> 134 struct non_null {}; 135 136A tag type that, when used with :doc:`stack::get\<non_null\<T*>><stack>`, does not perform a ``nil`` check when attempting to retrieve the userdata pointer. 137 138 139.. code-block:: cpp 140 :caption: type list 141 :name: type-list 142 143 template <typename... Args> 144 struct types; 145 146A type list that, unlike ``std::tuple<Args...>``, does not actually contain anything. Used to indicate types and groups of types all over Sol. 147 148 149functions 150--------- 151 152.. code-block:: cpp 153 :caption: type_of 154 155 template<typename T> 156 type type_of(); 157 158 type type_of(lua_State* L, int index); 159 160 161These functions get the type of a C++ type ``T``; or the type at the specified index on the Lua stack. 162 163.. code-block:: cpp 164 :caption: type checking convenience functions 165 166 int type_panic(lua_State* L, int index, type expected, type actual); 167 168 int no_panic(lua_State*, int, type, type) noexcept; 169 170 void type_error(lua_State* L, int expected, int actual); 171 172 void type_error(lua_State* L, type expected, type actual); 173 174 void type_assert(lua_State* L, int index, type expected, type actual); 175 176 void type_assert(lua_State* L, int index, type expected); 177 178The purpose of these functions is to assert / throw / crash / error (or do nothing, as is the case with ``no_panic``). They're mostly used internally in the framework, but they're provided here if you should need them. 179 180.. code-block:: cpp 181 :caption: type name retrieval 182 183 std::string type_name(lua_State*L, type t); 184 185Gets the Lua-specified name of the :ref:`type<type-enum>`. 186 187structs 188------- 189 190.. code-block:: cpp 191 192 struct userdata_value { 193 void* value; 194 }; 195 196 struct light_userdata_value { 197 void* value; 198 }; 199 200 struct up_value_index { 201 int index; 202 }; 203 204 205Types that differentiate between the two kinds of ``void*`` Lua hands back from its API: full userdata and light userdata, as well as a type that modifies the index passed to ``get`` to refer to `up values`_ These types can be used to trigger different underlying API calls to Lua when working with :doc:`stack<stack>` namespace and the ``push``/``get``/``pop``/``check`` functions. 206 207.. _up values: http://www.Lua.org/manual/5.3/manual.html#4.4