# This fork isn't maintained
Please see https://github.com/ahupowerdns/luawrapper
## Tomaka's lua wrapper
[](https://travis-ci.org/Tomaka17/luawrapper)
### What is this library?
This lua wrapper for C++ is a library which allows you to easily manage lua code. It was designed to be as simple as possible to use.
### Why this library?
You may wonder why I chose to create my own library while there as so many other libraries available. Well, none of them 100 % satisfied me.
Some are just basic wrappers (with functions to directly manipulate the stack), some others use an external executable to compute the list of functions of a class, and some others are just too complicated to use.
This library was designed to be very simple to use: you can write Lua variables (with either a number, a string, a function, an array or any object), read Lua variables, and of course execute Lua code. That's all.
### How to use it?
This is a headers-only library.
Simply add the `include` directory to your include paths, and you can use the `LuaContext` class.
You can also just copy-paste the files into your own project if you don't want to modify your include paths.
The `include/misc/exception.hpp` file is required only for VC++.
All the files outside of the `include` directory are only for testing purposes and can be ignored.
### Why should I use it?
* very easy to use
* no macros (we are in the 21st century!)
* no external program to run on your source code
* not intrusive, you don't need to change the layout of your functions or classes
* you aren't forced to use object-oriented code
* portable (doesn't use anything that is compiler-specific or platform-specific)
* can do everything other libraries can do
### Why should I not use it?
* requires support for [C++11](http://en.wikipedia.org/wiki/C%2B%2B11), the latest C++ standard
* requires [Boost](http://boost.org) (headers only)
* inheritance not supported (and won't be supported until some reflection is added to the C++ language)
* uses exceptions and RTTI
### I have the old (2010) version of your library, what did change?
* you need an up-to-date compiler now
* you now need some headers-only libraries from [Boost](http://boost.org)
* breaking change: `LuaContext` is no longer in the `Lua` namespace
* breaking change: you can't pass directly lambdas to `writeVariable` anymore, use `writeFunction` instead or convert them to `std::function`
* breaking change: the functions `clearVariable`, `doesVariableExist`, `writeEmptyArray` and `callLuaFunction` no longer exist, but you can reproduce their effect with `writeVariable` and `readVariable`
* a lot of features have been added: lua arrays, polymorphic functions, etc.
* the implementation is really a lot cleaner, and probably faster and with less bugs
### Documentation
All the examples below are in C++, except the parameter passed to `executeCode` which is Lua code.
#### Reading and writing variables
LuaContext lua;
lua.writeVariable("x", 5);
lua.executeCode("x = x + 2;");
std::cout << lua.readVariable("x") << std::endl; // prints 7
Reading and writing global variables of the Lua context can be done with `writeVariable` and `readVariable`.
All basic language types (`int`, `float`, `bool`, `char`, ...), plus `std::string`, can be read or written. `enum`s can also be read or written but are turned into numbers.
`readVariable` requires a template parameter which tells the type of the variable that should be read. A `WrongTypeException` is thrown if Lua can't convert the variable to the type you requested, or if you try to read a non-existing variable.
If you don't know the type of a variable in advance, you can read a `boost::variant`. If you want to read a variable but don't know whether it exists, you can read a `boost::optional`. More informations about this below.
#### Writing functions
Writing a function is as easy as writing a value:
void show(int value) {
std::cout << value << std::endl;
}
LuaContext lua;
lua.writeVariable("show", &show);
lua.executeCode("show(5)"); // calls the show() function in C++, which prints 5
lua.executeCode("show(7)"); // prints 7
`writeVariable` also supports `std::function`s:
std::function f = [](int v) { std::cout << v << std::endl; };
LuaContext lua;
lua.writeVariable("show", f);
lua.executeCode("show(3)"); // prints 3
lua.executeCode("show(8)"); // prints 8
The function's parameters and return type are handled as if they were read and written by `readVariable` and `writeVariable`, which means that all types supported by these functions can also be used as function parameters or return type.
If some Lua code attempts to call a function with fewer parameters or with parameters of the wrong type, then a Lua error is triggered.
Converting a lambda function to a `std::function` is costly. Instead you can use `writeFunction`:
// note: this is C++14
const auto increment = [](auto v) { return v + 1; }
LuaContext lua;
lua.writeFunction("incrementInt", increment);
lua.writeFunction("incrementDouble", increment);
If you pass a function object with a single operator(), you can also skip the template parameter of `writeFunction`, in which case the type will be automatically detected.
This is the easiest way to write a lambda.
LuaContext lua;
lua.writeFunction("show", [](int v) { std::cout << v << std::endl; });
#### Executing code
Executing Lua code is done with the `executeCode` function.
By default it takes no template parameter, but if the code returns a value, you can pass one to request the specific type to be returned.
LuaContext lua;
std::cout << lua.executeCode("return 1 + 2") << std::endl; // prints 3
A `SyntaxErrorException` is thrown in case of a parse error in the code. An `ExecutionErrorException` is thrown in case of an unhandled Lua error during execution.
`executeCode` also accepts `std::istream` objects. You can easily read lua code (including pre-compiled) from a file like this:
LuaContext lua;
lua.executeCode(std::ifstream{"script.lua"});
If you write your own derivate of `std::istream` (for example a decompressor), you can of course also use it.
Note however that `executeCode` will block until it reaches eof. You should remember this if you use a custom derivate of `std::istream` which awaits for data.
#### Exception safety
You can safely throw exceptions from inside functions called by Lua and they will be turned automatically into Lua errors.
If the error is not handled by the Lua code, then it will propagate outside of `executeCode`. An `ExecutionErrorException` will be thrown by `executeCode` with the exception thrown by the callback attached as a nested exception.
lua.writeFunction("test", []() { throw std::runtime_error("Problem"); });
try {
lua.executeCode("test()");
} catch(const ExecutionErrorException& e) {
std::cout << e.what() << std::endl; // prints an error message
try {
std::rethrow_if_nested(e);
} catch(const std::runtime_error& e) {
// e is the exception that was thrown from inside the lambda
std::cout << e.what() << std::endl; // prints "Problem"
}
}
#### Writing custom types
class Object {
public:
Object() : value(10) {}
void increment() { std::cout << "incrementing" << std::endl; value++; }
int value;
};
LuaContext lua;
lua.registerFunction("increment", &Object::increment);
lua.writeVariable("obj", Object{});
lua.executeCode("obj:increment();");
std::cout << lua.readVariable