Introduction

The change from Lua 5.1 to 5.3 in ƒh7, from Gedcom 5.5 to Gedcom 5.5.1, and the updating of many of the Lua libraries available for writing plugins poses some challenges to plugin authors who wish to write plugins for use across ƒh versions 5, 6 and 7. This article explores those challenges and offers advice on overcoming them.

General Guidance on Software Versions

It might be obvious, but just in case, check that any facilities you’re using in Lua, Library Modules or the ƒh API are available in all the versions of ƒh that you intend to support.

To test for the version of ƒh in use, for example:

if fhGetAppVersion () > 5 then
  --do something here
end

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:

if _VERSION == "Lua 5.3" then --FH 7
  --do something
else -- FH 5 or 6
 --do something else
end

Some but not all libraries will allow you to check their version, for example:

luasql = require "luasql"
ver = luasql._VERSION
print (ver)

If necessary, these checks will let you include coding for different versions of ƒh, Lua, and the libraries, should you (for example) want to make basic functionality available to all users but enhance the functionality where you can.

Lua 5.1/5.3 Compatibility

Some functions in Lua 5.1 have been renamed or deprecated in 5.3. This code block is needed 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.

if _VERSION == "Lua 5.3" then
  -- handle changes to table library
  unpack = table.unpack --function moved in 5.3
  function table.getn(t) --function removed in 5.3
    local count = 0
    for _, __ in ipairs(t) do
      count = count + 1
    end
    return count
  end
  function table.maxn(t) --function removed in 5.3
    local max = 0
    for j,k in pairs (t) do
      if type(j) == "number" then
        max = j
      end
    end
    return max
  end
  --handle changes to string library
  loadstring   = load -- function removed in 5.3
  string.gfind = string.gmatch --function renamed in 5.3
end

local temp = os.tmpname()..".html" -- Includes path in Lua 5.3
if _VERSION == "Lua 5.1"
or fhGetAppVersion() <= 6 then
  temp = os.getenv("TEMP")..temp -- Prefix path in Lua 5.1
end

There are also changes that need to be made wherever particular Lua features have been used. The most common include:

--[[Byte zero pattern %z was deprecated in Lua 5.2 and removed in Lua 5.3 to be replaced by \0
The workaround is to specify byte0 and use it with this code in patterns instead of %z or \0 .
Patterns will need to be edited manually to include byte0 instead of %z or \0
--]]
local byte0 = "%z" --Byte zero pattern %z was deprecated in Lua 5.2 and removed in Lua 5.3 to be replaced by \0
if _VERSION == "Lua 5.3" then			 
  byte0 = "\0"
end

--[[in Family Historian 5 and 6 both % and the slash character were permitted as escape characters. Now only % is allowed]]--

--[[handle changes to OS.TMPNAME
--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
--]]
local temp = os.tmpname()..'.html'
if _VERSION ~= 'Lua 5.1' then
  temp = os.getenv('TEMP')..filename
end

--[[Pseudo-argument arg
Pseudo-argument arg was deprecated in Lua 5.1 and removed in Lua 5.2.
Insert the following code into functions which use the ... argument
arg = {...}
arg['n'] = #arg
--]]

-- Example 
local function test(...)
  local arg = {...}
  arg['n'] = #arg
  for i,v in ipairs(arg) do
    print(i,v)
  end
end

--[[String formatting for numbers

string.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.

]]--

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:

• Changes between Lua 5.1 and Lua 5.2 and Incompatibilities between 5.1 and 5.2
• Changes between Lua 5.2 and Lua 5.3 and Incompatibilities between 5.2 and 5.3

Library Changes

IUP

IUP is the most commonly used library, and the following code block should be including before IUP is used to make a plugin compatible with the changing versions of IUP.

require ("iuplua") -- this was optional before Family Historian 7
if tonumber(iup._VERSION) >= 3.28 then
  iup.SetGlobal("CUSTOMQUITMESSAGE","YES") --if you don't include this, FH will exit when the plugin exits
end

A popular simple dialogue involves iup.GetParam(..) but a bug prevents the button labels being changed from OK and Cancel. The workaround is:

function paramAction(iupDialog,intIndex)
  if intIndex == iup.GETPARAM_MAP then		-- Correct button labels needed for IUP 3.28 bug
    iupDialog.Button1.Title = "Edit"	-- Otherwise remain as OK and Cancel
    iupDialog.Button2.Title = "Exit"
  end
  return 1
end
local isAns,strAns = iup.GetParam("Test",paramAction,"%u[Edit,Exit]")	-- Displays dialogue with buttons Edit and Exit

function paramAction(iupDialog,intIndex)
  if intIndex == iup.GETPARAM_MAP then		-- Correct button labels needed for IUP 3.28 bug
    iupDialog.Button1.Title = "Apply Rules"
    iupDialog.Button2.Title = "Cancel Plugin"
  elseif intIndex == (iup.GETPARAM_HELP or -4) then	-- FH V5 needs -4
    fhShellExecute("https://pluginstore.family-historian.co.uk/page/help/main-help-page","","","open")
  end
  return 1
end -- function paramAction

Again, there are more changes than can be addressed here, and different plugin authors will have used different facilities. Consult the IUP History to understand what has changed and when.

Require and Loadrequire

In ƒh5 and 6, some library modules had to be downloaded before they could re required for the first time, via the Module Require with Load function; in ƒh7 these libraries are installed with [FH] and can simple be required.  See Lua References and Library Modules for details of the modules affected.  If writing for versions 5, 6, and 7 you should include the loadrequire snippet and code like:

if fhGetAppVersion () >= 7 then 
  socket = require ("socket")
else
  socket = loadrequire("socket")
end

User Written Modules

In Lua 5.3, user-written modules need to be created using tables (this was optional in Lua 5.1). For example,

function myModule()
  local x = 0 --private module constant
  local function myFunc1 (a,b)
    x = a+b
  end
  local function myGetX()
    return x
  end
  return{
    myFunc1 = myFunc1,
    myGetX = myGetX
  }
end

local M = myModule()
M.myFunc1(1,2)
print (M.myGetX()) -- '3'

Note: it is a requirement of the Plugin that each plugin can be run independently, without dependencies, so any modules must be included inline within the plugin.

Gedcom Data Format Changes

The change from Gedcom 5.5 to 5.1.1 brings with it some data format changes, including:

• The structure for Media objects
• Potential rich text in [FH7] note fields
• Changes to the Gedcom tags for EMAIL (was _EMAIL), and WWW (was _WEB)

There’s a useful comparison of the two formats at GEDCOM Grammars : 5.5 vs 5.5.1

Whether these changes affect a plugin is highly dependent on what the plugin does, but if your plugin is affected you will need to write code for ‘old’ (versions 5 &6) and ‘new’ (version 7) and test the version of FH to determine which one applies.