integrating into existing code¶

If you’re already using lua and you just want to use sol in some places, you can use state_view:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

int something_in_my_system (lua_State* L) {
        // start using sol with a pre-existing system
        sol::state_view lua(L); // non-owning

        lua.script("print('bark bark bark!')");

        // get the table off the top of the stack
        sol::table expected_table(L, -1);
        // start using it...

        return 0; // or whatever you require of working with a raw function
}

sol::state_view is exactly like sol::state, but it doesn’t manage the lifetime of a lua_State*. Therefore, you get all the goodies that come with a sol::state without any of the ownership implications. sol has no initialization components that need to deliberately remain alive for the duration of the program. It’s entirely self-containing and uses lua’s garbage collectors and various implementation techniques to require no state C++-side. After you do that, all of the power of sol is available to you, and then some!

sol::state_view is also helpful when you want to create a DLL that loads some Lua module via requires.

You may also want to call require and supply a string of a script file or something that returns an object that you set equal to something in C++. For that, you can use the require functionality.

Remember that sol can be as lightweight as you want it: almost all of sol’s Lua types take the lua_State* argument and then a second int index stack index argument, meaning you can use tables, lua functions, coroutines, and other reference-derived objects that expose the proper constructor for your use. You can also set usertypes and other things you need without changing your entire architecture in one go.

You can even customize it to work with an external Lua wrapper/framework/library.

Note that you can also make non-standard pointer and reference types with custom reference counting and such also play nice with the system. See unique_usertype_traits<T> to see how! Custom types is also mentioned in the customization tutorial.

There are a few things that creating a sol::state does for you. You can read about it in the sol::state docs and call those functions directly if you need them.