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 functionsA 'function' is an expression which returns values based on computations. Typically, functions require data to be supplied to them as 'parameters'. A function in Family Historian is similar to a 'function' as used in spreadsheet applications (such as MS 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 MediaWhen you add a picture, video, sound recording, document file etc into a Family Historian project, a Media record is created to represent that media item within the project; the Media record includes a link to the actual Media file. objects has tag FILE (was _FILE) and the level for FORM & TITL tags has changed
• Custom attributesUsers of Family Historian can customize fact definitions, or create their own fact definitions to more closely match they way they want to work. now use FACTFacts are one of the key concepts at the heart of Family Historian; they are how you record the things that happened to, or described, each ancestor (Individual). 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 textRich text can be applied to most long text fields such as Notes and Text From Source, and offers a word-processing style of formatting. in Note (NOTE2) and Text From SourceBoth Source records and Citations have a Text From Source field intended to hold transcripts of source documents. (TEXT) fields that have new data type ‘richtext’ and tags _FMT, _LINK_? & _LNK plus many new API functions
• Research NotesFamily Historian version 6 and below supports two types of Notes: Local notes (associated with a single person, record, or fact); and Note Records (sometimes called Shared Notes), that can be linked to multiple records and/or facts. Version 7 introduced with new tag _RNOT that support rich text formats
• Templated sourceSource: "where information was found". This could be anything from an archive in a county records office, a book, or even a relative's recorded recollection. Citing your Sources helps to show how you reached a particular conclusion about an Individual. citationA link between a source and a fact, documenting Where within the source you find information being "cited" to support the fact/conclusion. 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.