types

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 <typename T>
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 <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

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

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

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.