IUP

Converting Lua 5.1 Plugins to Lua 5.3

Description

Since Version 7, Family Historian has used Lua 5.3. This means some plugins written for Version 5 or 6 of Family Historian will need to be changed to work on Version 7 or later. Care is needed if you wish to make these changes in a way that is backwardly compatible with Lua 5.1 (that is, if you want your plugin to be able to run under Family Historian 7 or later, but also be able to run under version 5 or 6 of Family Historian).

The guidance given here is not exhaustive. For more information, please see the sections on ‘Incompatiblities with the Previous Version’ of the Lua 5.2 Reference Manual and the Lua 5.3 Reference Manual (at https://www.lua.org/manual/5.2/manual.html#8 and https://www.lua.org/manual/5.3/manual.html#8 respectively).

Checking Your Version

Within a plugin, you can check which version of Lua is running by using the _VERSION value.

if _VERSION == 'Lua 5.1' then
   fhMessageBox('Lua 5.1 in use')
end

Modules

User-written modules need to be created using tables. See Modules in the Lua Quick Guide for more information.

Lua Patterns

Previously, both % and the slash character were permitted as escape characters. Lua patterns can now only use % as the escape character; so all plugins using patterns will need to be checked to ensure that the correct escape character is used.

IUP

Plugins that use IUP must now explicitly 'require' it (this was optional in V6 and earlier) and the IUP CUSTOMQUIT flag must be set. See Using IUP for details.

TABLE.GETN and unpack

The getn option to count the number of items in a table has been removed. This can be worked around by defining getn in your plugin. In 5.1 you could use unpack to unpack a table. This has been replaced with table.unpack. You can get around this by defining it or by replacing unpack with table.unpack. The former option is backwardly compatible with 5.1.

if not(table.getn) then
  function table.getn(t)
      local count = 0
      for _, __ in pairs(t) do
          count = count + 1
      end
      return count
   end
end
if _VERSION == "Lua 5.3" then
     unpack = table.unpack
end

arg

The arg table which was automatically created in 5.1, is no longer created in 5.3. You can workaround this, and retain backwards compatibility with 5.1, by inserting the following code into functions which use the ... argument:

arg = {...}
arg['n'] = #arg

The following example illustrates this:

function test(...)
   arg = {...}
   arg['n'] = #arg
   for i,v in ipairs(arg) do
      print(i,v)
   end
end
 
print(_VERSION)
test(1,2,3,4,5,6,7,8)

os.tmpname

The os.temp variable now returns the full file name with the path. The following will make the call backwardly compatible with 5.1:

local filename = os.tmpname()..'.html'
if _VERSION ~= 'Lua 5.1' then
    filename = os.getenv('TEMP')..filename
end

string.gfind

string.gfind has been renamed string.gmatch.

-- Either
string.gfind = string.gmatch
 
-- or replace string.gfind with string.gmatch then use

if _VERSION == 'Lua 5.1' then
    string.gmatch = string.gfind 
end

IUP