types — sol 3.2.3 documentation (original) (raw)

nil, lua_primitive type traits, and other fundamentals

The types.hpp header contains various fundamentals and utilities of sol.

enumerations¶

syntax of a function called by Lua¶

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.

status of a Lua function call¶

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.

status of a Lua thread¶

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.

status of a Lua load operation¶

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).

type enumeration¶

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¶

lua_type_of trait¶

template struct lua_type_of;

This type trait maps a C++ type to a type enumeration value. The default value is type::userdata.

primitive checking traits¶

template struct is_lua_primitive;

template 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¶

nil¶

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.

non_null¶

template 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.

type list¶

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¶

type_of¶

template 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.

type checking convenience functions¶

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.

type name retrieval¶

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.