LuaPP

LuaPP is a C++17 Lua engine built around an embedded Lua runtime. It provides a higher-level C++ API for creating Lua values, manipulating tables, registering C++ functions, executing Lua code, managing userdata, and interacting with the Lua runtime.

Features

• RAII-style Lua state management
• C++ wrappers for Lua values through LTValue
• Support for numbers, integers, booleans, strings, nil, userdata, tables, functions, and threads
• Create and manipulate Lua tables
• Global and registry access
• Register C++ functions callable from Lua
• Function arguments and return values represented with VLTValue
• Upvalue support
• pairs and ipairs table iteration
• Load and execute Lua strings or files
• Custom Lua readers and writers
• Lua bytecode dumping
• Metatable support
• C++ object userdata with automatic __gc destruction
• Error handling, warnings, and traceback generation
• Lua version information

Requirements

• CMake 3.16 or newer
• A C++17-compatible compiler
• Lua 5.3 or newer

LuaPP currently builds with Lua 5.5. Lua versions older than 5.3 are not supported.

Building

LuaPP uses CMake and includes the Lua runtime directly in the project, so no separate Lua installation is required.

cmake -B build
cmake --build build

By default, LuaPP is built as a static library. To build LuaPP as a shared library:

cmake -B build -DLUAPP_SHARED=ON
cmake --build build

The LUAPP_EXECS CMake option can also be used to build the optional command-line executables.

Basic Usage

#include "luapp.hpp"

LuaPP::State lua;

lua.loadlibs();

auto result = lua.dostring("return 1 + 2");

if (!result.empty()) {
    auto& value = result[0];

    if (value.isint()) {
        std::cout << value.getint() << '\n';
    }
}

Values

LTValue represents a Lua value owned and managed by a LuaPP::State.

Common type checks include:

value.isnum();
value.isint();
value.isbool();
value.isstring();
value.isnil();
value.istable();
value.isfunction();
value.isthread();
value.isud();

Values can then be retrieved with methods such as:

value.getnum();
value.getint();
value.getbool();
value.getstring();
value.getud<T>();

The corresponding check* functions perform type validation and report an error when the value has the wrong type.

Tables

Tables can be created and accessed directly:

auto table = lua.newtable();

lua.setField(table, "name", lua.mkvalue("LuaPP"));
lua.setField(table, 1, lua.mkvalue(123));

auto name = lua.getField(table, "name");

Iteration is supported through pairs and ipairs:

for (auto it : lua.pairs(table)) {
    auto& key = it.key();
    auto& value = it.value();
    // iterate
}

raw variants are available on several table operations to bypass metamethod behavior.

C++ Functions

C++ functions can be exposed to Lua using mkfunction:

LuaPP::CFunction fn =
    [](LuaPP::State& state,
       const LuaPP::VLTValue& args,
       const LuaPP::VUpValue& upvalues) -> LuaPP::VLTValue {
        return state.mkvec(state.mkvalue(42));
    };

auto function = lua.mkfunction(fn);

Functions can also capture Lua upvalues through VUpValue.

Executing Lua

Lua code can be loaded or executed directly:

lua.dostring("print('Hello from Lua')");

You can also:

lua.loadstring(...);
lua.loadfile(...);
lua.dofile(...);

load* functions produce a callable Lua function, while do* functions load and execute the chunk.

Userdata

LuaPP provides helpers for raw userdata as well as C++ objects:

MyObject* object = nullptr;

auto userdata = lua.mkobj(object, constructorArg);

mkobj constructs the C++ object in Lua userdata storage and installs a __gc metamethod that calls its destructor when Lua collects the userdata.

Metatables

Metatables can be assigned and retrieved with:

lua.setMetatable(value, metatable);

auto mt = lua.getMetatable(value);

This allows normal Lua metamethod functionality to be used from C++.

Error Handling

Lua calls can optionally receive an error handler:

auto results = lua.call(
    function,
    args,
    [](LuaPP::State&, std::string message) {
        std::cerr << message << '\n';
    }
);

Tracebacks can be generated with:

auto traceback = lua.getTraceback("Something went wrong");

Lua Version

LuaPP exposes information about the linked Lua implementation:

LuaPP::State::getLuaVersionStr();
LuaPP::State::getLuaVersion();
LuaPP::State::getLuaRelease();
LuaPP::State::getLuaCopyright();

Building

LuaPP depends on the Lua C API and is designed to optionally build as a shared library.

When building as a shared library, define:

LUAPP_SHARED

The LUAPP_EXPORT macro handles symbol visibility on MSVC and GCC/Clang-style platforms.

API Overview

Component	Purpose
State	Owns and interacts with a Lua state
LTValue	Represents a Lua value
VLTValue	Vector of Lua values
VUpValue	Function upvalues
CFunction	C++ function callable by Lua
TableIterator	Iterates Lua tables
IterValue	Holds an iterator key/value pair
Reader	Custom Lua chunk reader
Writer	Custom Lua bytecode writer
fReg	Function registration descriptor