## Lua Binding

### Overview

All the IUP functions are available in Lua, with a few exceptions. We call it IUPLua. To use them the general application will do require"iuplua", and require"iupluaxxxx" to all other secondary libraries that are needed. The functions and definitions will be available under the table "iup" using the following name rules:

    iupXxx  -> iup.Xxx    (for functions)
    IUP_XXX -> iup.XXX    (for definitions)

All the metatables have the "tostring" metamethod implemented to help debugging.

Also the functions which receive values by reference in C were modified. Generally, the values of parameters that would have their values modified are now returned by the function in the same order.

Notice that, as opposed to C, in which enumeration flags are combined with the bitwise operator OR, in Lua the flags are added arithmetically.

In Lua all parameters are checked and a Lua error is emitted when the check fails.

All the objects are NOT garbage collected by the Lua garbage collector, you must manually call iup.Destroy or elem:destroy, if you would like to destroy an element.

In Iup additional features were created for the Lua Binding using the metamethods. Attributes and callbacks can be set and get in a much more natural way:

    IupSetAttribute(label, "TITLE", "test")   >>   label.title = "test"             (names are in lower case)
    title = IupGetAttribute(label, "TITLE")   >>   title = label.title

    IupSetCallback(button, "ACTION", button_action_cb);   >>    function button:action() ... end

Also the element constructors were changed so you can use tables to initialize their parameters and attributes:

    IupButton("test")         >>    iup.button{title = "test", alignment="acenter"}
    IupHbox(bt1, bt2, NULL)   >>    iup.hbox{bt1, bt2, margin="10x10"}

Lua was created after LED, so that's why LED exists. Since we have many application still using LED, its support will continue in IUP. Today IupLua completely replaces the LED functionality and adds much more.>

The distribution files include an executable called iuplua51, that you can use to test your Lua code. It has support for all the additional controls, for IM, CD and OpenGL calls. It is available at the Download.

### IupLua Initialization

Lua 5.1 "require" can be used for all the IupLua libraries. You can use require"iuplua" and so on, but the LUA_CPATH must also contains at least the following:

    "./lib?51.so;"    [in UNIX]

    ".\\?51.dll;"     [in Windows]

Also compatible with Lua 5.2 and 5.3, just replace the "51" suffix by "52" or "53".

The LuaBinaries distribution already includes these modifications on the default search path.

If you are using another Lua distribution you can use the environment:

    export LUA_CPATH=./\?.so\;./lib\?.so\;./lib\?51.so\;   [in UNIX]

Or you can set it in Lua before loading iup modules:

    package.cpath = package.cpath .. "./lib?51.so;"    [in UNIX]

    package.cpath = package.cpath .. ".\\?51.dll;"     [in Windows]

The simplest form require"iup" and so on, can not be used because there are IUP dynamic libraries with names that will conflict with the names used by require during search.

Additionally you can statically link the IupLua libraries, but you must call the initialization functions manually. The iuplua_open function is declared in the header file iuplua.h, see the example below:

    #include <lua.h>
    #include <lualib.h>
    #include <lauxlib.h>
    #include <iuplua.h>
    void main(void)
    {
      lua_State *L = lua_open();

      luaopen_string(L);
      luaopen_math(L);
      luaopen_io(L);

      iuplua_open(L);
      lua_dofile("myprog.lua");

      lua_close(L);
    }

When using Lua the Iup initialization functions, IupOpen, IupControlsOpen and others, are not necessary. The initialization is automatically done inside the respective IupLua initialization function.

To use IUP inside coroutines, define the global attribute "IUPLUA_THREADED".

### Embedding Lua files in the Application Executable

The Lua files are dynamically loaded and must be sent together with the application’s executable. However, this often becomes an inconvenience. To deal with it, there is the LuaC compiler that creates a C module from the Lua contents. For example:

    luac -o myfile.lo myfile.lua
    lua bin2c.lua myfile.lo > myfile.loh

In C, you can use a define to interchanged the use of .LOH files:

    #ifdef _DEBUG
      ret_val = iuplua_dofile("myfile.lua");
    #else
    #include "myfile.loh"
    #endif

This does not work when using LuaJIT. To be able to do that, use Lua files directly as strings:

    lua bin2c.lua myfile.lua > myfile.lh

In C, simply include the .LH files:

    #include "myfile.lh"

### LuaJIT

LuaJIT is a Just-In-Time Compiler for Lua that can be found at http://luajit.org/. IUP can be used with LuaJIT but there are a few remarks.

First, LuaJIT is for Lua 5.1 ONLY (as of May 2019), but can be built for 32 or 64 bits.

In Windows, It builds a modified "lua51.dll", so the Lua DLL in IUP Tools packages must be ignored. But in IUP we use a "lua5.1.dll", notice the difference in the name. To use it with IUP there two options, rebuild LuaJIT using the same suffix, or use a DLL proxy that will map calls for "lua5.1.dll" into "lua51.dll". The DLL proxy can be found here lua5.1_proxy.zip (notice that the IUP Tools packages includes a proxy in the other way, mapping "lua51.dll" calls into "lua5.1.dll", this is NOT the case).

In Linux this can be easily fixed with links in the file system.

### More Information

Steve Donovan wrote a very nice "A Basic Guide to using IupLua" that was included in Lua for Windows. It is now available as part of the IUP documentation.

The slides for "Tecgraf Development Tools: IUP, CD and IM" presented at the Lua Workshop 2009 are also available for Download [iupcdim_wlua2009_en.pdf].