Lua Language References
| ƒh versions 5 & 6 | ƒh version 7 | ƒh version 8 | 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 | |
| LuaThe language in which Family Historian plugins are written. version | 5.1 | 5.3.5 | 5.3 | 5.4 was released on 29 Jun 2020 but ƒh8 stays on 5.3, so plugin code written for ƒh7 runs unchanged. |
| Lua build | 32-bit | 32-bit | 64-bit | ƒh8 is a 64-bit application, so the Lua library DLLs it loads are all 64-bit builds. This only matters if you have used loadrequire or similar to pull in a DLL from outside the ƒh installation: a 32-bit DLL will not load in ƒh8. Pure-Lua modules are unaffected. Note also that in ƒh8 fhGetAppVersion() returns a number, not a string; use tostring() before concatenating it. |
| Lua reference and programming manuals | Free online: Lua 5.1 Reference Manual Free online: Programming in Lua (first edition) for Lua 5.0 Programming in Lua 2nd edition at Amazon | Free online: Lua 5.3 Reference Manual Free online: Programming in Lua (first edition) for Lua 5.0 Programming in Lua 4th edition via Amazon | Lua version history has links to free online Reference Manuals for all versions Programming in Lua paperbacks (editions 2 to 4) are all available via Amazon in the country of your choice | |
| Lua Wiki (programming language information & resources) | Lua Wiki ~ Main Page and Lua Wiki ~ Sample Code. Note: There will be elements of the advice and sample code that apply only to the later versions of Lua, not 5.1. | |||
Lua Library Modules
Although Lua is deliberately written to be a small and simple language, it is extremely extensible by means of Library Modules that provide additional functionality. A number of such libraries are available for use (if wanted) within ƒh pluginsPlugins are small programs that allow new features to be added without upgrading Family Historian itself; some plugins are written by Calico Pie and others are written by users.. We recommend that you ‘require’ the libraries you’re going to use at the global level in your code, so they are all together and used just once. There is a marginal performance hit from doing this, but in most cases, the increase in code simplicity outweighs the disadvantages. ƒh8 ships the same set of libraries as ƒh7, rebuilt as 64-bit DLLs, plus two new ones: LPeg and its re module. Several libraries are at a different version from ƒh7 (and from the version stated in the ƒh8 Plugin Help); the ƒh8 column below shows the version actually reported by the library when loaded. The require lines shown for ƒh7 all work unchanged in ƒh8.
IUP GUI Builder
This is a pre-installed library used by ƒh plugins when they need to present a user interface more complex than the simple message box and prompts provided by the ƒh API. The version supported by ƒh is often not the latest available, and can be hard to determine; where we’re uncertain we haven’t specified a version but you would be wise to remember this when debugging. You should also be careful to check which version of a library the online Documentation refers to, and consult the associated History page to understand the changes between the version provided in ƒh and the current version.
| ƒh versions 5 & 6 | ƒh version 7 | ƒh version 8 | Make available by: | |
| IUP version | V5: 3.5 V6: 3.11.2 | 3.28 | 3.28 (64-bit) | require ("iuplua") |
| IUP reference manual and programming guides | Free online: IUP Portable User Interface Read carefully to identify features that are not available in the version you are using. A Basic Guide to using IupLua IUP GUI Builder Hints and Tips | |||
| Additional IUP Libraries | IupControls IupGLCanvas IupGLControls IupMglPlot IupOleControl IupScintilla IupWebBrowser All are present in ƒh7 and ƒh8. | require( "iupluacontrols" ) |
||
require( "iupluagl" ) |
||||
require( "iupluaglcontrols" ) |
||||
require( "iuplua_mglplot" ) |
||||
require( "iupluaole" ) |
||||
require( "iuplua_scintilla" ) |
||||
require( "iupluaweb" ) |
||||
Other Lua Library Modules
Not all these libraries are pre-installed in ƒh Versions 5 or 6; you may need to use the Module Require With Load (code snippet) to use them within your plugin. Most of them are pre-installed in ƒh7 and ƒh8 and you do not need to use loadrequire. The versions supported by ƒh are often not the latest available, and can be hard to determine; where we’re uncertain we haven’t specified a version but you would be wise to remember this when debugging. You should also be careful to check which version of a library the online Documentation refers to, and consult the associated History page to understand the changes between the version provided in ƒh and the current version.
| ƒh versions 5 & 6 | ƒh version 7 | ƒh version 8 | Notes | |
| Lua File System | V6: 1.5 | 1.7 | 1.6.3 (the ƒh8 Plugin Help says 1.7) | require( "lfs" ) |
| Free online: Lua File System Library Manual Note: lfs will not work with file names and paths that include UTF8 characters; use fhFileUtils for those. | ||||
| LuaCOM | V6, V7, V8: 1.3 Free online: LuaCOM User Manual Version 1.3 Note: in ƒh8 LuaCOM is a 64-bit build, so it can only create 64-bit COM objects. Most Windows components (WScript.Shell, Excel, Word, Outlook, ADODB) have 64-bit versions; a plugin that relies on a 32-bit-only COM component will not work in ƒh8. | require ("luacom") |
||
| IM: Digital Imaging Toolkit | V5: 3.4.2 V6: 3.8.2 | 3.13 | 3.13 | require( "imlua" , "imlua_process" ) |
| Free online: IM – Digital Imaging Tool Version | ||||
| CD: 2-D Graphics library | V5 and 6: Version tba | 5.12 | 5.12 | require ("cdlua") |
| Free online: CD – A 2D Graphics Library | ||||
| MD5: Cryptographic library | V6, V7: 1.2 Free online: MD5: Cryptographic Library for Lua | 1.3 (the ƒh8 Plugin Help says 1.2) The companion des56 module is also present. |
ƒh5 and 6: loadrequire ( "md5" ) ƒh7 and 8: md5 = require ("md5") |
|
| LuaSocket: Network support | V5 and 6: tba | 2.0.2 | 3.0.0 (the ƒh8 Plugin Help says 2.0.2) | ƒh5 and 6: loadrequire ( "socket" ) ƒh7 and 8: socket = require ("socket") |
Free online: LuaSocket: Network support for Lua (3.0 reference; the older 2.0.2 manual is at w3.impa.br) Note: LuaSocket provides plain HTTP only. Neither ƒh7 nor ƒh8 includes LuaSec (ssl), so HTTPS requests must be made another way, e.g. via LuaCOM and MSXML2.ServerXMLHTTP or WinHttp.WinHttpRequest.5.1. |
||||
| LuaZip: Reading files inside zip files | Free online: LuaZip: Reading files inside zip files | Not supported in ƒh7 or ƒh8 On Windows 10 above build 17063, you can use Tar (to create compressed archives) and uncompress both gz and zip ones require 'luacom' -- Unzip sCmd = 'tar -xf "L:\\fh_set_living.zip" -C D:\\temp\\ ' -- Zip sCmd = 'tar -cvzf "d:\\temp\\doc.gz" "D:\\temp\\Doc"' Shell = luacom.CreateObject("WScript.Shell") Shell:Run (sCmd, 0, true) Note: this does not work in CrossoverCrossOver is a Microsoft Windows compatibility layer available for Linux, macOS, and Chrome OS. It enables many Windows-based applications to run on Linux, macOS, or Chrome OS operating systems. CrossOver is a retail product developed by CodeWeavers and based on. |
ƒh5 and 6: loadrequire( "zip" ) ƒh7 and 8: N/A |
|
| LuaSQL: DBMS interface | V5 and 6: Version tba | LuaSQL does not work in ƒh7 or ƒh8 and the fhSQL library should be used instead. Note: ƒh8 ships an lsqlite3.dll but require("lsqlite3") fails to load it; use fhSQL. |
ƒh6: loadrequire( "luasql", "luasql.sqlite3" ) |
|
| Free online: LuaSql: DBMS interface for Lua | ||||
| Penlight Lua Library Modules | V5 and V6: 1.5.4 Free online: Penlight Lua Library version 1.5.4 | V7, V8: 1.8.0 Free documentation online: Penlight Lua Libraries Changes from 1.8 to the current versions are documented here (mostly bugfixes) | ƒh5 and 6: loadrequire( "pl", "pl.init" ) ƒh7 and 8: require ("pl.init") |
|
| LPeg: Parsing ExpressionExpressions are composed from two technical features: Data References and Functions; they also often involve Operators to compare values. Grammars for Lua | N/A | N/A | 1.1.0 Free online: LPeg reference manual New in ƒh8 (not mentioned in the ƒh8 Plugin Help). A pattern-matching library that is far more capable than Lua’s built-in string.find/string.match: it can parse structured text such as GEDCOMGEDCOM, an acronym for GEnealogical Data COMmunication, is a specification for exchanging genealogical data between different genealogy software. It is a file format that most genealogical programs and online trees recognise. lines, CSV, datesWhen an Event happened, or an Attrribute was true. in mixed formats or citationA link between a source and a fact, documenting Where within the source you find information being "cited" to support the fact/conclusion. strings with a proper grammar. |
ƒh8: lpeg = require ("lpeg") |
| re: regex-like syntax for LPeg | N/A | N/A | Supplied with LPeg 1.1.0 Free online: LPeg re module manual New in ƒh8. A pure-Lua module (part of LPeg) that lets you write LPeg grammars in a compact, regular-expression-like notation, e.g. re.match("15 Mar 1852", "{%d+} ' ' {%a+} ' ' {%d+}"). It requires the lpeg module. |
ƒh8: re = require ("re") |
| utf8: UTF-8 aware string 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 | ƒh6: dated 2021-08-11 | ƒh7: dated 2021-08-11 | Present; the module reports no version | ƒh6: loadrequire( "utf8" ) loadrequire( "compat53" ) Note: this order of requiring the modules is important. Additional code (see below) must be appended, depending on whether support is required for upper/lower() of UTF-8 characters. ƒh6, 7 and 8: a) If lower/upper() support of UTF-8 characters is NOT needed: utf8 = require ( ".utf8" ):init() b) If lower/upper() support of UTF-8 characters IS needed: require ( "utf8data" ) utf8 = require ( ".utf8" ) utf8.config["conversion"] = { uc_lc = utf8_uc_lc; lc_uc = utf8_lc_uc; } utf8:init() Note: if you wish to overlay the standard string library with this utf8 library, follow the initialisation call with for k,v in pairs(utf8) do string[k] = v end |
Online documentation Note 1: in ƒh6 the library compat53 is a prerequisite for this library. Note 2: in ƒh6 you must loadrequire this library using the ‘multiple sub-directories’ version of loadrequire here. In addition, if you have written a plugin that requires upper/lower support for UTF-8 characters, you need to check for and remove an earlier version of the library before you loadrequire it, with the following code: require ( "lfs" ) local path = fhGetContextInfo("CI_APP_DATA_FOLDER").."\\Plugins\\" if lfs.attributes(path.."utf8data.lua","mode") ~= "file" and lfs.attributes(path.."utf8.lua","mode") == "file" then os.remove(path.."utf8.lua") end |
||||
| fhUtils: An ƒh specific library module that provides utility functions for building ƒh plugins. | N/A | 1.9 Online Documentation | 1.16 Online Documentation | ƒh6: Not available ƒh7 and 8: require ("fhUtils") |
| fhFileUtils: An ƒh specific library of modules to handle files with Unicode file names that are not supported by the standard Lua LFS and IO methods. | N/A | 1.0 Online Documentation | 1.9 Online Documentation | ƒh6: Not available ƒh7 and 8: require("fhFileUtils") |
| fhSQL: An ƒh specific library to handle database access | N/A | 1.0 Online Documentation | 1.3 Online Documentation | ƒh7 and 8: require("fhSQL") |
| compat53 : 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. | Version 0.9 Online documentation | N/A (not needed: ƒh7 and 8 are Lua 5.3) | ƒh6: loadrequire ("compat53")
|
|