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

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