Simple Lua
A Simple C++ Lua Wrapper
|
The goal is simple-lua is to provide an easy and quick interface for using Lua scripts in C++.
To build the library, first clone from the repository with
Then, in your CMakeLists.txt
add
You can expose your project to the library with
There are three important options: 1) -DSL_BUILD_LIB=ON
is on by default, but you can choose not to build the library (for example if you only want documentation) 2) -DSL_UNIT_TESTS=ON
will build the unit tests (requires the library), which includes pulling the googletest repository, run ctest
to actually run the tests 3) -DSL_BUILD_DOCS=ON
will build the documentation, which includes pulling doxygen-awesome which is used for basic formatting
To learn the Lua scripting language, check out this page. Once you have a script you're ready to integrate into your C++ program (and have set up the subdirectory with cmake), all you need to do is include #include <SL/Lua.hpp>
at the top of your file.
The lifetime of a Lua script is SL::Runtime
, which can be created by
You can also create a runtime, specifying SL::Lib::Base
libraries with (more on this here)
All types returned from SL::Runtime
methods are SL::Results
of some kind. These objects can be casted to bool (or called good()
) to determine if an error occured. If it does return false you can print the error message. Utilizing the SL_ASSERT
macro, we can check with
It is advised that when getting values from an SL::Runtime
or SL::Table
that you only use the types described in TypeMap.hpp
, that is
SL::String
is std::string
SL::Number
is float
SL::Boolean
is bool
SL::Function
is int (*)(SL::State)
void*
pointer is also technically supported, but not super well. It is not meant to be used in a way that involves accessing data from Lua, but instead for the case of serializing the an object an retaining its identity by storing its location in memory so that you can deserialize it and access it from C++. More about this workflow is talked about laterGlobals are values in the global scope in a Lua script like
You can access the value with
prints 4
.
struct
s and namespace
s, so it's common to simply do We can call functions in the global scope like
by calling the SL::Runtime::runFunction
method. This method returns an std::tuple
of the types specified in the call to runFunction
which are the return types of the Lua function. The types have to match in type and count, otherwise you'll get errors. The return of this function is itself a result, so you can capture the errors and do what you need with them. To execute this Lua function we'd write
This prints 42
.
We can easily put C++ functions in the global scope of a Lua script easily using the SL::Runtime::registerFunction
method. Functions implemented in C++ must have a specific signature: that of SL::Function
(and must be static). We can create one of these functions
Lua works using a stack, when a function is called the arguments are pushed to the stack. So, to get the arguments passed from Lua, we simply pop the expected types off the top of the stack. The SL::Lib::Base::extractArgs
method is helpful for this reason (to avoid the verbosity, we can have our method be a static one inside a struct inheriting from SL::Lib::Base). Then, we run our function. Finally, we push onto the stack the returns and return from the C++ function the count of returned types.
We can put this in the global scope of a Lua runtime with
SL::Lib::Base
handles, which is talked about later.Then, in a Lua function:
Finally, we run the Lua function:
The only other type missing from the supported types is SL::Table
which will more than likely be the most commonly used type.