Introduction
The changes from Lua 5.1 to 5.3 in ƒh7 and from Gedcom 5.5 to Gedcom 5.5.1, the introduction of new features in ƒh7 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 ƒh versions 5, 6 and 7. This article explores those challenges and offers advice on overcoming them.
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 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.
General Guidance on Software Versions
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
Plugins that Originated in Version 5 or 6
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.
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.
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
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 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.
A 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 .
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 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
Plugins Created in FH7
If you are writing a new plugin and want it to run in ƒh5, 6 and 7, you should investigate the compat53 module for Lua 5.1:
This is a small module that aims to make it easier to write code in a Lua-5.3-style that is compatible with Lua 5.1, Lua 5.2, and Lua 5.3. This does not make Lua 5.2 (or even Lua 5.1) entirely compatible with Lua 5.3, but it brings the API closer to that of Lua 5.3.
Instructions for loading the module are at Lua References and Library Modules.
Library Changes
There are numerous changes in the libraries available between ƒh6 and [ƒh7. See Lua References and Library Modules for details of the library versions supported in each version.
IUP
IUP is the most commonly used library, and the following code block must be included before IUP is used to make a plugin compatible with the changing versions of IUP. It tests for the version of IUP and enables some special handling for later versions.
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 and you may get other unpredictable behaviour
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 be 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 (which was updated when ƒh7 was released, so make sure you are using the latest version) and code like:
if fhGetAppVersion () >= 7 then
socket = require ("socket")
else
socket = loadrequire("socket")
end
Note: the utf8 library for ƒh6 needs special handling and you should follow the instructions in Lua References and Library Modules exactly.
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.
Character Encoding
ƒh5 only supports ANSI whereas ƒh6+ supports Unicode UTF-8, and there are three options…1. Use plugin File > Encoding > UTF-8 and only support ƒh6+
2. Use plugin File > Encoding > ANSI for all versions where Unicode UTF-8 fields are not involved
3. Use plugin File > Encoding > ANSI for all versions but with the code block below to support Unicode UTF-8 in ƒh6+
if fhGetAppVersion() > 5 then -- Cater for Unicode UTF-8 for FH v6+
fhSetStringEncoding("UTF-8")
iup.SetGlobal("UTF8MODE","YES") -- These two only needed with require "iuplua"
iup.SetGlobal("UTF8MODE_FILE","NO")
end
Gedcom Data Format Changes
The change from Gedcom 5.5 to 5.5.1 brings with it some data format changes, including:
- The structure for Media objects has tag FILE (was _FILE) and the level for FORM & TITL tags has changed
- Custom attributes now use FACT tag although the API still uses _ATTR
- Changes to the GEDCOM tags for EMAIL (was _EMAIL), and WWW (was _WEB)
- New GEDCOM tags FAX, FONE, ROMN, et
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.
New Family Historian Features
The changes due to new features in ƒh include:
- The structure for Media objects for _KEYS, _AREA, _CAPT, _NOTA, _SEQ instead of _ASID, etc
- Rich text in Note (NOTE2) and Text From Source (TEXT) fields that have new data type ‘richtext’ and tags _FMT, _LINK_? & _LNK plus many new API functions
- Research Notes with new tag _RNOT that support rich text formats
- Templated source citation meta-fields that require shortcuts and new tag _SRCT
- Updates to some Plugin Code Snippets
If your plugin interacts with these new features, you will have to decide whether to restrict it to ƒh version 7 only, or include alternative code for earlier versions.
