new_usertype/set options¶

If the type is default_constructible, sol will generate a "new" member on the usertype for you. Otherwise, use my_table.new_usertype<MyType>("name", sol::no_constructor); to prevent the constructor or pass in a sol::automagic_enrollments enrollments; /* modify members here */; when calling .new_usertype<MyType>("name", enrollments);. Otherwise, the following are special ways to handle the construction of a usertype:

• "{name}", constructors<T(), T(arg-1-0), T(arg-2-0, arg-2-1), ...>

  • Specify the constructors to be bound under name: list constructors by specifying their function signature with class_type(arg0, arg1, ... argN)
  • If you pass the constructors<...> argument first when constructing the usertype, then it will automatically be given a "{name}" of "new"

• "{name}", constructors<Type-List-0, Type-List-1, ...>

  • This syntax is longer and provided for backwards-compatibility: the above argument syntax is shorter and cleaner
  • Type-List-N must be a sol::types<Args...>, where Args... is a list of types that a constructor takes. Supports overloading by default
  • If you pass the constructors<...> argument first when constructing the usertype, then it will automatically be given a "{name}" of "new"

• "{name}", sol::initializers( func1, func2, ... )

  • Used to handle initializer functions that need to initialize the memory itself (but not actually allocate the memory, since that comes as a userdata block from Lua)

  • Given one or more functions, provides an overloaded Lua function for creating the specified type

    • The function must have the argument signature func( T*, Arguments... ) or func( T&, Arguments... ), where the pointer or reference will point to a place of allocated memory that has an uninitialized T. Note that Lua controls the memory, so performing a new and setting it to the T* or T& is a bad idea: instead, use placement new to invoke a constructor, or deal with the memory exactly as you see fit

• {anything}, sol::factories( func1, func2, ... )

  • Used to indicate that a factory function (e.g., something that produces a std::unique_ptr<T, ...>, std::shared_ptr<T>, T, or similar) will be creating the object type

  • Given one or more functions, provides an overloaded function for invoking

    • The functions can take any form and return anything, since they’re just considered to be some plain function and no placement new or otherwise needs to be done. Results from this function will be pushed into Lua according to the same rules as everything else.
    • Can be used to stop the generation of a .new() default constructor since a sol::factories entry will be recognized as a constructor for the usertype
    • If this is not sufficient, see next 2 entries on how to specifically block a constructor

• {anything}, {some_factory_function}

  • Essentially binds whatever the function is to name {anything}
  • When used WITH the sol::no_constructor option below (e.g. "new", sol::no_constructor and after that having "create", &my_creation_func), one can remove typical constructor avenues and then only provide specific factory functions. Note that this combination is similar to using the sol::factories method mentioned earlier in this list. To control the destructor as well, see further below

• sol::call_constructor, {valid constructor / initializer / factory}

  • The purpose of this is to enable the syntax local v = my_class( 24 ) and have that call a constructor; it has no other purpose
  • This is compatible with luabind, kaguya and other Lua library syntaxes and looks similar to C++ syntax, but the general consensus in Programming with Lua and other places is to use a function named new
  • Note that with the sol::call_constructor key, a construct type above must be specified. A free function without it will pass in the metatable describing this object as the first argument without that distinction, which can cause strange runtime errors.

• {anything}, sol::no_constructor

  • Specifically tells sol not to create a .new() if one is not specified and the type is default-constructible
  • When the key {anything} is called on the table, it will result in an error. The error might be that the type is not-constructible.
  • Use this plus some of the above to allow a factory function for your function type but prevent other types of constructor idioms in Lua

usertype destructor options¶

If you don’t specify anything at all and the type is destructible, then a destructor will be bound to the garbage collection metamethod. Otherwise, the following are special ways to handle the destruction of a usertype:

• "__gc", sol::destructor( func ) or sol::meta_function::garbage_collect, sol::destructor( func )

  • Creates a custom destructor that takes an argument T* or T& and expects it to be destructed/destroyed. Note that lua controls the memory and thusly will deallocate the necessary space AFTER this function returns (e.g., do not call delete as that will attempt to deallocate memory you did not new)
  • If you just want the default constructor, you can replace the second argument with sol::default_destructor
  • The usertype will error / throw if you specify a destructor specifically but do not map it to sol::meta_function::gc or a string equivalent to "__gc"

usertype automatic (automagic) meta functions¶

If you don’t specify a sol::meta_function name (or equivalent string metamethod name) and the type T supports certain operations, sol3 will generate the following operations provided it can find a good default implementation:

• for to_string operations where std::ostream& operator<<( std::ostream&, const T& ), obj.to_string(), or to_string( const T& ) (in the namespace) exists on the C++ type

  • a sol::meta_function::to_string operator will be generated

  • writing is done into either

    • a std::ostringstream before the underlying string is serialized into Lua
    • directly serializing the return value of obj.to_string() or to_string( const T& )

  • order of preference is the std::ostream& operator<<, then the member function obj.to_string(), then the ADL-lookup based to_string( const T& )
  • if you need to turn this behavior off for a type (for example, to avoid compiler errors for ADL conflicts), specialize sol::is_to_stringable<T> for your type to be std::false_type, like so:

namespace sol {
        template <>
        struct is_to_stringable<my_type> : std::false_type {};
}

• for call operations where operator()( parameters ... ) exists on the C++ type

  • a sol::meta_function::call operator will be generated
  • the function call operator in C++ must not be overloaded, otherwise sol will be unable to bind it automagically
  • the function call operator in C++ must not be templated, otherwise sol will be unable to bind it automagically
  • if it is overloaded or templated, it is your responsibility to bind it properly

• for automatic iteration where begin() and end() functions exist on the C++ type

  • the type must have a value_type, iterator, and similar Container typedefs.
  • a sol::meta_function::pairs operator is generated for you
  • Allows you to iterate using for k, v in pairs( obj ) do ... end in Lua
  • Lua 5.2 and better only: LuaJIT does not allow this, Lua 5.1 does NOT allow this

• for cases where .size() exists on the C++ type

  • the length operator of Lua (#my_obj) operator is generated for you

• for comparison operations where operator < and operator <= exist on the C++ type

  • These two sol::meta_function::less_than(_or_equal_to) are generated for you
  • > and >= operators are generated in Lua based on < and <= operators

• for operator==

  • An equality operator will always be generated, doing pointer comparison if operator== on the two value types is not supported or doing a reference comparison and a value comparison if operator== is supported

• heterogenous operators cannot be supported for equality, as Lua specifically checks if they use the same function to do the comparison: if they do not, then the equality method is not invoked; one way around this would be to write one int super_equality_function(lua_State* L) { ... }, pull out arguments 1 and 2 from the stack for your type, and check all the types and then invoke operator== yourself after getting the types out of Lua (possibly using sol::stack::get and sol::stack::check_get)

usertype regular function options¶

Otherwise, the following is used to specify functions to bind on the specific usertype for T.

• "{name}", &free_function

  • Binds a free function / static class function / function object (lambda) to "{name}". If the first argument is T* or T&, then it will bind it as a member function. If it is not, it will be bound as a “static” function on the lua table

• "{name}", &type::function_name or "{name}", &type::member_variable

  • Binds a typical member function or variable to "{name}". In the case of a member variable or member function, type must be T or a base of T

• "{name}", sol::readonly( &type::member_variable )

  • Binds a typical variable to "{name}". Similar to the above, but the variable will be read-only, meaning an error will be generated if anything attemps to write to this variable

• "{name}", sol::as_function( &type::member_variable )

  • Binds a typical variable to "{name}" but forces the syntax to be callable like a function. This produces a getter and a setter accessible by obj:name() to get and obj:name(value) to set.

• "{name}", sol::property( getter_func, setter_func )

  • Binds a typical variable to "{name}", but gets and sets using the specified setter and getter functions. Not that if you do not pass a setter function, the variable will be read-only. Also not that if you do not pass a getter function, it will be write-only

• "{name}", sol::var( some_value ) or "{name}", sol::var( std::ref( some_value ) )

  • Binds a typical variable to "{name}", optionally by reference (e.g., refers to the same memory in C++). This is useful for global variables / static class variables and the like

• "{name}", sol::overload( Func1, Func2, ... )

  • Creates an oveloaded member function that discriminates on number of arguments and types
  • Dumping multiple functions out with the same name does not make an overload: you must use this syntax in order for it to work

• sol::base_classes, sol::bases<Bases...>

  • Tells a usertype what its base classes are. You need this to have derived-to-base conversions work properly. See inheritance