types¶
nil, lua_primitive type traits, and other fundamentals
The types.hpp
header contains various fundamentals and utilities of sol.
enumerations¶
enum class call_syntax {
dot = 0,
colon = 1
};
This 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 constructor/initializer was called with a :
or a .
, and not misalign the arguments.
enum class call_status : int {
ok = LUA_OK,
yielded = LUA_YIELD,
runtime = LUA_ERRRUN,
memory = LUA_ERRMEM,
handler = LUA_ERRERR,
gc = LUA_ERRGCMM
};
This strongly-typed enumeration contains the errors potentially generated by a call to a protected function or a coroutine.
enum class thread_status : int {
ok = LUA_OK,
yielded = LUA_YIELD,
runtime = LUA_ERRRUN,
memory = LUA_ERRMEM,
gc = LUA_ERRGCMM,
handler = LUA_ERRERR,
dead,
};
This 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.
enum class load_status : int {
ok = LUA_OK,
runtime = LUA_ERRSYNTAX,
memory = LUA_ERRMEM,
gc = LUA_ERRGCMM,
file = LUA_ERRFILE,
};
This enumeration contains the status of a load operation from state::load(_file).
enum class type : int {
none = LUA_TNONE,
lua_nil = LUA_TNIL,
string = LUA_TSTRING,
number = LUA_TNUMBER,
thread = LUA_TTHREAD,
boolean = LUA_TBOOLEAN,
function = LUA_TFUNCTION,
userdata = LUA_TUSERDATA,
lightuserdata = LUA_TLIGHTUSERDATA,
table = LUA_TTABLE,
poly = none | nil | string | number | thread |
table | boolean | function | userdata | lightuserdata,
// if not in Objective C land...
nil = LUA_TNIL
};
The 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).
type traits¶
template <typename T>
struct lua_type_of;
This type trait maps a C++ type to a type enumeration value. The default value is type::userdata
.
template <typename T>
struct is_lua_primitive;
template <typename T>
struct is_proxy_primitive;
This trait is used by 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, references). std::reference_wrapper
, std::tuple<...>
are returned as values, but their contents can be references. The default value is false.
special types¶
struct lua_nil_t {};
constexpr lua_nil_t lua_nil {};
bool operator==(lua_nil_t, lua_nil_t);
bool operator!=(lua_nil_t, lua_nil_t);
// if not in Objective-C land
using nil_t = lua_nil_t;
constexpr nil_t nil {};
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, sol::object and proxy values.
template <typename T>
struct non_null {};
A tag type that, when used with stack::get<non_null<T*>>, does not perform a nil
check when attempting to retrieve the userdata pointer.
template <typename... Args>
struct types;
A type list that, unlike std::tuple<Args...>
, does not actually contain anything. Used to indicate types and groups of types all over sol.
functions¶
template<typename T>
type type_of();
type type_of(lua_State* L, int index);
These functions get the type of a C++ type T
; or the type at the specified index on the Lua stack.
int type_panic_string(lua_State* L, int index, type expected, type actual, const std::string& message);
int type_panic_c_str(lua_State* L, int index, type expected, type actual, const char* message);
int no_panic(lua_State*, int, type, type, const char*) noexcept;
void type_error(lua_State* L, int expected, int actual);
void type_error(lua_State* L, type expected, type actual);
void type_assert(lua_State* L, int index, type expected, type actual);
void type_assert(lua_State* L, int index, type expected);
The 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.
std::string type_name(lua_State*L, type t);
Gets the Lua-specified name of the type.
structs¶
struct userdata_value {
void* value;
};
struct light_userdata_value {
void* value;
};
struct upvalue_index {
int index;
};
struct raw_index {
int index;
};
struct absolute_index {
int index;
};
struct ref_index {
int index;
};
Types 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 stack namespace and the push
/get
/pop
/check
functions.
The raw_index
type is used to tell a sol::reference type or similar that the desired index – negative or not – should be passed through directly to the API.
The absolute_index
type is used to tell a sol::reference type or similar that the desired index – negative or not – should be passed through Lua’s lua_absindex function first to adjust where it is, and then given to the underlying API.
The ref_index
type is used to tell a sol::reference type or similar that it should look into the Lua C Registry for its type.