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