Lua Language References
| ƒh versions 5 & 6 | ƒh version 7 | 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 | |
| Lua version | 5.1 | 5.3.5 | 5.4 was released on 29 Jun 2020 |
| 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 at 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.
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 | Make available by: | |
| IUP version | V5: 3.5
V6: 3.11.2 |
3.28 | 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. |
||
| Additional IUP Libraries | IupControls IupGLCanvas IupGLControls IupMglPlot IupOleControl IupScintilla IupWebBrowser |
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 [fh]7 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 | Notes | |
| Lua File System | V6: 1.5 | 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. |
|||
| LuaCOM | V6, V7: 1.3
Free online: LuaCOM User Manual Version 1.3 |
require ("luacom") |
|
| IM: Digital Imaging Toolkit | V5: 3.4.2
V6: 3.8.2 |
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 | require ("cdlua") |
| Free online: CD – A 2D Graphics Library | |||
| MD5: Cryptographic library | V6, V7: 1.2
Free online: MD5: Cryptographic Library for Lua |
ƒh5 and 6: loadrequire ( "md5" )
ƒh7: md5 = require ("md5") |
|
| LuaSocket: Network support | V5 and 6: tba | 2.0.2 | ƒh5 and 6: loadrequire ( "socket" )
ƒh7: socket = require ("socket") |
| Free online: LuaSocket: Network support for Lua | |||
| LuaZip: Reading files inside zip files | Free online: LuaZip: Reading files inside zip files | Not supported in ƒh7.0.0
On Windows 10 above build 17063, you can use Tar (to create compressed archives) and uncompress both gz and zip ones
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: N/A |
| LuaSQL: DMBS interface | V5 and 6: Version tba | LuaSQl does not work in ƒh7 and the fhSQL library should be used instead. | ƒ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 |
1.8
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: require ("pl.init") |
| 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
|
ƒh6:
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 and 7:a) If lower/upper() support of UTF-8 characters is NOT needed:
b) If lower/upper() support of UTF-8 characters IS needed:
Note: if you wish to overlay the standard string library with this utf8 library, follow the initialisation call with
|
| 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:
|
|||
| fhUtils: An ƒh specific library module that provides utility functions for building ƒh plugins. | N/A | 1.9 | ƒh6: Not available
ƒh7:
|
| 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 | ƒh6: Not available
ƒh7:
|
| fhSQL: An ƒh specific library to handle database access | 1.0 | ƒh7:
|
|
| 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 | N/A | ƒh6: loadrequire ("compat53")
|