luwra/docs/output/mkdocs/search_index.json

{
    "docs": [
        {
            "location": "/",
            "text": "Installation\n\n\nLuwra is a header-only library, which means that nothing has to be compiled in order to use it.\nSimply clone the \nrepository\n or\n\ndownload\n and extract it to a directory of\nyour preference.\n\n\nFor your application to be able to reach the \nlib/luwra.hpp\n header file, you must add\n\n/path/to/luwra/lib\n to the list of include paths. With Clang and GCC that is done using the\n\n-I/path/to/luwra/lib\n command-line parameter.\n\n\nNow you can simply \n#include <luwra.hpp>\n in your C++ files and start using Luwra.\n\n\nReference Manual\n\n\nA reference manual exists \nhere\n.",
            "title": "Home"
        },
        {
            "location": "/#installation",
            "text": "Luwra is a header-only library, which means that nothing has to be compiled in order to use it.\nSimply clone the  repository  or download  and extract it to a directory of\nyour preference.  For your application to be able to reach the  lib/luwra.hpp  header file, you must add /path/to/luwra/lib  to the list of include paths. With Clang and GCC that is done using the -I/path/to/luwra/lib  command-line parameter.  Now you can simply  #include <luwra.hpp>  in your C++ files and start using Luwra.",
            "title": "Installation"
        },
        {
            "location": "/#reference-manual",
            "text": "A reference manual exists  here .",
            "title": "Reference Manual"
        },
        {
            "location": "/basics/",
            "text": "Integration\n\n\nLuwra does not provide a standalone version of Lua nor does it isolate its features. This means that\nall functions and classes operate on\n\nlua_State\n (or the alias\n\nState\n). Doing this allows you to\nintegrate Luwra however you like.\n\n\nStack Interaction\n\n\nAlthough Luwra provides a variety of features, its main concern is efficient and safe interaction\nwith the Lua stack.\n\n\nA fundamental aspect of this is the abstract template \nValue\n.\nEvery type which can be pushed onto or read from the stack has a specialization of it.\nUseful implementations are provided out of the box:\n\n\n\n\n\n\n\n\nC++ type\n\n\nPushable\n\n\nReadable\n\n\nLua type\n\n\n\n\n\n\n\n\n\n\nbool\n\n\nyes\n\n\nyes\n\n\nboolean\n\n\n\n\n\n\nsigned char\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nsigned short\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nsigned int\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nsigned long int\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nsigned long long int\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nunsigned char\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nunsigned short\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nunsigned int\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nunsigned long int\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nunsigned long long int\n\n\nyes\n\n\nyes\n\n\nnumber (integer since 5.3)\n\n\n\n\n\n\nfloat\n\n\nyes\n\n\nyes\n\n\nnumber\n\n\n\n\n\n\ndouble\n\n\nyes\n\n\nyes\n\n\nnumber\n\n\n\n\n\n\nlong double\n\n\nyes\n\n\nyes\n\n\nnumber\n\n\n\n\n\n\nconst char*\n\n\nyes\n\n\nyes\n\n\nstring\n\n\n\n\n\n\nstd::string\n\n\nyes\n\n\nyes\n\n\nstring\n\n\n\n\n\n\nstd::nullptr_t\n\n\nyes\n\n\nyes\n\n\nnil\n\n\n\n\n\n\nstd::tuple<T>\n\n\nyes\n\n\nno\n\n\ndepends on the tuple contents\n\n\n\n\n\n\nlua_CFunction\n\n\nyes\n\n\nno\n\n\nfunction\n\n\n\n\n\n\nNativeFunction<R(A...)>\n\n\nno\n\n\nyes\n\n\nfunction\n\n\n\n\n\n\nFieldVector\n\n\nyes\n\n\nno\n\n\ntable\n\n\n\n\n\n\n\n\nNote:\n Some numeric types have a different size than their matching Lua type - they will be\ntruncated during push or read operations.\n\n\nPushing C++ values\n\n\nWhen pushing values onto the stack you can either use\n\nValue<T>::push\n or the more\nconvenient \npush\n.\n\n\n// Push an integer\nluwra::push(lua, 1338);\n\n// Push a number\nluwra::push(lua, 13.37);\n\n// Push a boolean\nluwra::push(lua, false);\n\n// Push a string\nluwra::push(lua, \"Hello World\");\n\n\n\n\nThis produces the following stack layout:\n\n\n\n\n\n\n\n\nAbsolute Position\n\n\nRelative Position\n\n\nValue\n\n\n\n\n\n\n\n\n\n\n1\n\n\n-4\n\n\n1338\n\n\n\n\n\n\n2\n\n\n-3\n\n\n13.37\n\n\n\n\n\n\n3\n\n\n-2\n\n\nfalse\n\n\n\n\n\n\n4\n\n\n-1\n\n\n\"Hello World\"\n\n\n\n\n\n\n\n\nIt is possible to provide a template parameter to \npush\n to enforce pushing a specific type.\nIn most cases you are probably better off by letting the compiler infer the template parameter.\n\n\nReading Lua values\n\n\nSimple retrieval of Lua values is done using\n\nread<T>\n. Consider the\nstack layout from the previous example. This is how you would retrieve a value from the stack.\n\n\n// Retrieve the integer at position 1\nint value = luwra::read<int>(lua, 1);\n\n// Similiar with a relative index\nint value = luwra::read<int>(lua, -4);\n\n\n\n\nRead and type errors\n\n\nWhat happens when a value which you are trying to read mismatches the expected type or cannot be\nconverted to it? Most \nValue<T>\n specializations use Lua's \nluaL_check*\n functions to retrieve\nthe values from the stack. This means that no exceptions will be thrown - instead the error handling\nis delegated to the Lua VM. Have a look at the\n\nerror handling documentation\n for more information.",
            "title": "Basic Stack Interaction"
        },
        {
            "location": "/basics/#integration",
            "text": "Luwra does not provide a standalone version of Lua nor does it isolate its features. This means that\nall functions and classes operate on lua_State  (or the alias State ). Doing this allows you to\nintegrate Luwra however you like.",
            "title": "Integration"
        },
        {
            "location": "/basics/#stack-interaction",
            "text": "Although Luwra provides a variety of features, its main concern is efficient and safe interaction\nwith the Lua stack.  A fundamental aspect of this is the abstract template  Value .\nEvery type which can be pushed onto or read from the stack has a specialization of it.\nUseful implementations are provided out of the box:     C++ type  Pushable  Readable  Lua type      bool  yes  yes  boolean    signed char  yes  yes  number (integer since 5.3)    signed short  yes  yes  number (integer since 5.3)    signed int  yes  yes  number (integer since 5.3)    signed long int  yes  yes  number (integer since 5.3)    signed long long int  yes  yes  number (integer since 5.3)    unsigned char  yes  yes  number (integer since 5.3)    unsigned short  yes  yes  number (integer since 5.3)    unsigned int  yes  yes  number (integer since 5.3)    unsigned long int  yes  yes  number (integer since 5.3)    unsigned long long int  yes  yes  number (integer since 5.3)    float  yes  yes  number    double  yes  yes  number    long double  yes  yes  number    const char*  yes  yes  string    std::string  yes  yes  string    std::nullptr_t  yes  yes  nil    std::tuple<T>  yes  no  depends on the tuple contents    lua_CFunction  yes  no  function    NativeFunction<R(A...)>  no  yes  function    FieldVector  yes  no  table     Note:  Some numeric types have a different size than their matching Lua type - they will be\ntruncated during push or read operations.",
            "title": "Stack Interaction"
        },
        {
            "location": "/basics/#pushing-c-values",
            "text": "When pushing values onto the stack you can either use Value<T>::push  or the more\nconvenient  push .  // Push an integer\nluwra::push(lua, 1338);\n\n// Push a number\nluwra::push(lua, 13.37);\n\n// Push a boolean\nluwra::push(lua, false);\n\n// Push a string\nluwra::push(lua, \"Hello World\");  This produces the following stack layout:     Absolute Position  Relative Position  Value      1  -4  1338    2  -3  13.37    3  -2  false    4  -1  \"Hello World\"     It is possible to provide a template parameter to  push  to enforce pushing a specific type.\nIn most cases you are probably better off by letting the compiler infer the template parameter.",
            "title": "Pushing C++ values"
        },
        {
            "location": "/basics/#reading-lua-values",
            "text": "Simple retrieval of Lua values is done using read<T> . Consider the\nstack layout from the previous example. This is how you would retrieve a value from the stack.  // Retrieve the integer at position 1\nint value = luwra::read<int>(lua, 1);\n\n// Similiar with a relative index\nint value = luwra::read<int>(lua, -4);",
            "title": "Reading Lua values"
        },
        {
            "location": "/basics/#read-and-type-errors",
            "text": "What happens when a value which you are trying to read mismatches the expected type or cannot be\nconverted to it? Most  Value<T>  specializations use Lua's  luaL_check*  functions to retrieve\nthe values from the stack. This means that no exceptions will be thrown - instead the error handling\nis delegated to the Lua VM. Have a look at the error handling documentation  for more information.",
            "title": "Read and type errors"
        },
        {
            "location": "/advanced/",
            "text": "Operating on Lua values with C++ functions\n\n\nInstead of extracting every Lua value seperately and pushing the result of your C++ function back\nonto the stack again, you can use one of the following functions to make this process easier for you.\n\n\nInvoke a Callable with Lua values\n\n\nThe function \ndirect<S>\n\nlets you specify a \nstack signature\n in order to extract the values and invoke a \nCallable\n with\nthem.\n\n\nConsider the following:\n\n\nstring result = foo(luwra::read<string>(lua, n), luwra::read<int>(lua, n + 1));\n\n\n\n\nIt could be rewritting like this:\n\n\nstring result = luwra::direct<string(string, int)>(lua, n, foo);\n\n\n\n\nNote:\n The result of \nfoo\n is not pushed onto the stack. Except for the extraction of Lua values,\neverything happens on the C++ side.\n\n\nInvoke a function with Lua values\n\n\napply\n is similiar to\n\ndirect\n. The function \napply\n\nprovides specific overloads for function pointers and function objects. Although \ndirect\n works\nwith function pointers and function objects, it is often more convenient to use \napply\n since it\nallows the compiler to infer the \nstack signature\n without providing a template parameter.\n\n\nProvided a function \nfoo\n which has been declared as used in the example above:\n\n\nstring foo(string bar, int baz);\n\n// ... or with a function object\nfunction<string(string, int)> foo = /* magic */;\n\n\n\n\nOne would use \nfoo\n like this:\n\n\nstring result = luwra::apply(lua, n, foo);",
            "title": "Advanced Stack Interaction"
        },
        {
            "location": "/advanced/#operating-on-lua-values-with-c-functions",
            "text": "Instead of extracting every Lua value seperately and pushing the result of your C++ function back\nonto the stack again, you can use one of the following functions to make this process easier for you.",
            "title": "Operating on Lua values with C++ functions"
        },
        {
            "location": "/advanced/#invoke-a-callable-with-lua-values",
            "text": "The function  direct<S> \nlets you specify a  stack signature  in order to extract the values and invoke a  Callable  with\nthem.  Consider the following:  string result = foo(luwra::read<string>(lua, n), luwra::read<int>(lua, n + 1));  It could be rewritting like this:  string result = luwra::direct<string(string, int)>(lua, n, foo);  Note:  The result of  foo  is not pushed onto the stack. Except for the extraction of Lua values,\neverything happens on the C++ side.",
            "title": "Invoke a Callable with Lua values"
        },
        {
            "location": "/advanced/#invoke-a-function-with-lua-values",
            "text": "apply  is similiar to direct . The function  apply \nprovides specific overloads for function pointers and function objects. Although  direct  works\nwith function pointers and function objects, it is often more convenient to use  apply  since it\nallows the compiler to infer the  stack signature  without providing a template parameter.  Provided a function  foo  which has been declared as used in the example above:  string foo(string bar, int baz);\n\n// ... or with a function object\nfunction<string(string, int)> foo = /* magic */;  One would use  foo  like this:  string result = luwra::apply(lua, n, foo);",
            "title": "Invoke a function with Lua values"
        },
        {
            "location": "/wrapping/",
            "text": "General\n\n\nLuwra provides an easy way to turn any C or C++ function into a\n\nlua_CFunction\n which can be used by the\nLua VM. Note, all parameter types must be readable from the stack (\nValue<T>::read\n exists for all)\nand the return type must be pushable (\nValue<T>::push\n exists).\n\n\nWrap functions\n\n\nAssuming you have a function similiar to this:\n\n\nint my_function(const char* a, int b) {\n    return /* magic */;\n}\n\n\n\n\nYou can easily wrap it using the \nLUWRA_WRAP\n macro:\n\n\n// Convert to lua_CFunction\nlua_CFunction cfun = LUWRA_WRAP(my_function);\n\n// Do something with it, for example set it as a Lua global function\nluwra::setGlobal(lua, \"my_function\", cfun);\n\n\n\n\nNote:\n Do not provide the address of your function (e.g. \n&my_function\n) to any wrapping macro.\nThe macros will take care of this themselves. You must provide only the name of the function.\n\n\nCalling the function from Lua is fairly straightforward:\n\n\nlocal my_result = my_function(\"Hello World\", 1337)\nprint(my_result)\n\n\n\n\nWrap methods and fields\n\n\nIt is also possible to turn C++ field accessors and methods into \nlua_CFunction\ns. It is a little\ntrickier than wrapping normal functions. The resulting Lua functions expect the first (or \nself\n)\nparameter to be a user type instance of the type which the wrapped field or method belongs to.\n\n\nNote:\n Before you wrap fields and methods manually, you might want to take a look at the\n\nUser Types\n section.\n\n\nThe next examples will operate on the following structure:\n\n\nstruct Point {\n    double x, y;\n\n    // ...\n\n    void scale(double f) {\n        x *= f;\n        y *= f;\n    }\n};\n\n\n\n\nIn order to wrap \nx\n, \ny\n and \nscale\n we utilize the \nLUWRA_WRAP\n macro again:\n\n\nlua_CFunction cfun_x     = LUWRA_WRAP(Point::x),\n              cfun_y     = LUWRA_WRAP(Point::y),\n              cfun_scale = LUWRA_WRAP(Point::scale);\n\n// Register as globals\nluwra::setGlobal(lua, \"x\", cfun_x);\nluwra::setGlobal(lua, \"y\", cfun_y);\nluwra::setGlobal(lua, \"scale\", cfun_scale);\n\n\n\n\nUsage looks like this:\n\n\nlocal my_point = -- Magic\n\n-- Access 'x' and 'y' field\nprint(x(my_point), y(my_point))\n\n-- Set 'x' and 'y' field\nx(my_point, 13.37)\ny(my_point, 73.31)\n\n-- Invoke 'scale' method\nscale(my_point, 2)",
            "title": "Function Wrapping"
        },
        {
            "location": "/wrapping/#general",
            "text": "Luwra provides an easy way to turn any C or C++ function into a lua_CFunction  which can be used by the\nLua VM. Note, all parameter types must be readable from the stack ( Value<T>::read  exists for all)\nand the return type must be pushable ( Value<T>::push  exists).",
            "title": "General"
        },
        {
            "location": "/wrapping/#wrap-functions",
            "text": "Assuming you have a function similiar to this:  int my_function(const char* a, int b) {\n    return /* magic */;\n}  You can easily wrap it using the  LUWRA_WRAP  macro:  // Convert to lua_CFunction\nlua_CFunction cfun = LUWRA_WRAP(my_function);\n\n// Do something with it, for example set it as a Lua global function\nluwra::setGlobal(lua, \"my_function\", cfun);  Note:  Do not provide the address of your function (e.g.  &my_function ) to any wrapping macro.\nThe macros will take care of this themselves. You must provide only the name of the function.  Calling the function from Lua is fairly straightforward:  local my_result = my_function(\"Hello World\", 1337)\nprint(my_result)",
            "title": "Wrap functions"
        },
        {
            "location": "/wrapping/#wrap-methods-and-fields",
            "text": "It is also possible to turn C++ field accessors and methods into  lua_CFunction s. It is a little\ntrickier than wrapping normal functions. The resulting Lua functions expect the first (or  self )\nparameter to be a user type instance of the type which the wrapped field or method belongs to.  Note:  Before you wrap fields and methods manually, you might want to take a look at the User Types  section.  The next examples will operate on the following structure:  struct Point {\n    double x, y;\n\n    // ...\n\n    void scale(double f) {\n        x *= f;\n        y *= f;\n    }\n};  In order to wrap  x ,  y  and  scale  we utilize the  LUWRA_WRAP  macro again:  lua_CFunction cfun_x     = LUWRA_WRAP(Point::x),\n              cfun_y     = LUWRA_WRAP(Point::y),\n              cfun_scale = LUWRA_WRAP(Point::scale);\n\n// Register as globals\nluwra::setGlobal(lua, \"x\", cfun_x);\nluwra::setGlobal(lua, \"y\", cfun_y);\nluwra::setGlobal(lua, \"scale\", cfun_scale);  Usage looks like this:  local my_point = -- Magic\n\n-- Access 'x' and 'y' field\nprint(x(my_point), y(my_point))\n\n-- Set 'x' and 'y' field\nx(my_point, 13.37)\ny(my_point, 73.31)\n\n-- Invoke 'scale' method\nscale(my_point, 2)",
            "title": "Wrap methods and fields"
        },
        {
            "location": "/user-types/",
            "text": "User Types",
            "title": "User Types"
        },
        {
            "location": "/user-types/#user-types",
            "text": "",
            "title": "User Types"
        }
    ]
}