{"id":11787,"date":"2020-12-14T10:36:24","date_gmt":"2020-12-14T10:36:24","guid":{"rendered":"https:\/\/fhug.org.uk\/kb\/?post_type=kb_article&p=11787"},"modified":"2022-11-06T17:45:29","modified_gmt":"2022-11-06T17:45:29","slug":"writing-plugins-compatible-with-versions-5-6-7","status":"publish","type":"kb_article","link":"https:\/\/www.fhug.org.uk\/kb\/kb-article\/writing-plugins-compatible-with-versions-5-6-7\/","title":{"rendered":"Writing and Maintaining Plugins Compatible with Versions 5, 6 & 7"},"content":{"rendered":"

Introduction<\/h2>\n

The changes from Lua 5.1 to 5.3 in \u0192h<\/span><\/span>7 and from Gedcom 5.5 to Gedcom 5.5.1, the introduction of new features in \u0192h<\/span><\/span>7 and the updating of many of the Lua libraries available for writing plugins poses some challenges to plugin authors who wish to write or update plugins for use across \u0192h<\/span><\/span> versions 5, 6 and 7. This article explores those challenges and offers advice on overcoming them.<\/p>\n

If you’re a plugin author who wishes to migrate a plugin from V6 to V7 and are not concerned with backward compatibility, first consult Converting Lua 5.1 Plugins to Lua 5.3<\/code> within the Family Historian Plugin Help. This article may also be useful to identify other considerations to take into account during the migration, depending on how complex your plugin is.<\/p>\n

General Guidance on Software Versions<\/h2>\n

Check that any facilities you’re using in Lua, Library Modules <\/a>or the \u0192h<\/span><\/span> API are available in all the versions of \u0192h<\/span><\/span> that you intend to support.<\/p>\n

To test for the version of \u0192h<\/span><\/span> in use, for example:<\/p>\n

if fhGetAppVersion () > 5 then\r\n  --do something here\r\nend<\/pre>\n
This should usually be sufficient to determine what version of Lua and Lua libraries are available to you, but you can also check the Lua version using:<\/p>\n
if _VERSION == \"Lua 5.3\" then --FH 7\r\n  --do something\r\nelse -- FH 5 or 6\r\n --do something else\r\nend\r\n<\/pre>\n
Some but not all libraries will allow you to check their version, for example:<\/p>\n
luasql = require \"luasql\"\r\nver = luasql._VERSION\r\nprint (ver)<\/pre>\n
If necessary, these checks will let you include coding for different versions of \u0192h<\/span><\/span>, Lua, and the libraries, should you (for example) want to make basic functionality available to all users but enhance the functionality where you can.<\/p>\n
Lua 5.1\/5.3 Compatibility<\/h2>\n
Plugins that Originated in Version 5 or 6<\/h3>\n
Some functions in Lua 5.1 have been renamed or deprecated in 5.3., and some additional functions have been added in Lua 5.3.<\/p>\n
If relevant, this code block must be positioned near the beginning of any plugin written originally in Lua 5.1 to enable it to run in Lua 5.3 with the minimum of changes.<\/p>\n
if _VERSION == \"Lua 5.3\" then\r\n  -- handle changes to table library\r\n  unpack = table.unpack --function moved in 5.3\r\n  function table.getn(t) --function removed in 5.3\r\n    local count = 0\r\n    for _, __ in ipairs(t) do\r\n      count = count + 1\r\n    end\r\n    return count\r\n  end\r\n  function table.maxn(t) --function removed in 5.3\r\n    local max = 0\r\n    for j,k in pairs (t) do\r\n      if type(j) == \"number\" then\r\n        max = j\r\n      end\r\n    end\r\n    return max\r\n  end\r\n  --handle changes to string library\r\n  loadstring   = load -- function removed in 5.3\r\n  string.gfind = string.gmatch --function renamed in 5.3\r\nend\r\n<\/pre>\n
There are also changes that need to be made wherever particular Lua features have been used. The most common include:<\/p>\n
--[[Byte zero pattern %z was deprecated in Lua 5.2 to be replaced by \\0. %z still works in Lua 5.3 as well as 5.1, but there is no guarantee it will work in future versions of Lua.\r\nA alternative for those who are concerned about future compatibility is to specify byte0 and use it with this code in patterns instead of %z or \\0 .\r\nPatterns will need to be edited manually to include byte0 instead of %z or \\0\r\n--]]\r\nlocal byte0 = \"%z\" --Byte zero pattern %z was deprecated in Lua 5.2 to be replaced by \\0\r\nif _VERSION == \"Lua 5.3\" then\t\t\t \r\n  byte0 = \"\\0\"\r\nend\r\n\r\n--[[in Family Historian 5 and 6 both % and the slash character were permitted as escape characters. Now only % is allowed]]--\r\n\r\n--[[handle changes to OS.TMPNAME\r\n--In 5.3 the os.temp variable now returns the full file name with thepath.  The following will make the call backwardly compatible with 5.1\r\n--]]\r\nlocal temp = os.tmpname()..'.html'\r\nif _VERSION ~= 'Lua 5.1' then\r\n  temp = os.getenv('TEMP')..filename\r\nend\r\n\r\n--[[Pseudo-argument arg\r\nPseudo-argument arg was deprecated in Lua 5.1 and removed in Lua 5.2.\r\nInsert the following code into functions which use the ... argument\r\narg = {...}\r\narg['n'] = #arg\r\n--]]\r\n\r\n-- Example \r\nlocal function test(...)\r\n  local arg = {...}\r\n  arg['n'] = #arg\r\n  for i,v in ipairs(arg) do\r\n    print(i,v)\r\n  end\r\nend\r\n\r\n--[[String formatting for numbers\r\n\r\nstring.format(\"%d\",number) won't work if number is not an integer. It needs string.format(\"%d\",math.floor(number)) or similar to ensure the parameter is an integer. That solution works for all Lua versions.\r\n\r\n]]--\r\n\r\n<\/pre>\n
There are also changes in areas that are less commonly used. See the relevant Lua documentation to understand the cumulative changes from 5.1 to 5.3:<\/p>\n