{"id":10705,"date":"2020-07-07T13:28:46","date_gmt":"2020-07-07T13:28:46","guid":{"rendered":"https:\/\/fhug.org.uk\/kb\/?post_type=kb_article&p=10705"},"modified":"2026-09-23T11:19:46","modified_gmt":"2026-09-23T11:19:46","slug":"lua-references-and-library-modules","status":"publish","type":"kb_article","link":"https:\/\/www.fhug.org.uk\/kb\/kb-article\/lua-references-and-library-modules\/","title":{"rendered":"Lua References and Library Modules"},"content":{"rendered":"

Lua Language References<\/h2>\n\n\n\n\n\n\n\n
<\/td>\n\u0192h<\/span><\/span> versions 5 & 6<\/strong><\/td>\n\u0192h<\/span><\/span> version 7<\/strong><\/td>\n\u0192h<\/span><\/span> version 8<\/strong><\/td>\nNotes<\/strong><\/td>\n<\/tr>\n
Lua version<\/td>\n5.1<\/td>\n5.3.5<\/td>\n5.3<\/td>\n5.4 was released on 29 Jun 2020 but \u0192h<\/span><\/span>8 stays on 5.3, so plugin code written for \u0192h<\/span><\/span>7 runs unchanged.<\/td>\n<\/tr>\n
Lua build<\/td>\n32-bit<\/td>\n32-bit<\/td>\n64-bit<\/td>\n\u0192h<\/span><\/span>8 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 \u0192h<\/span><\/span> installation: a 32-bit DLL will not load in \u0192h<\/span><\/span>8. Pure-Lua modules are unaffected. Note also that in \u0192h<\/span><\/span>8\u00a0fhGetAppVersion()<\/code>\u00a0returns a number, not a string; use\u00a0tostring()<\/code>\u00a0before concatenating it.<\/td>\n<\/tr>\n
Lua reference and programming manuals<\/td>\nFree online:\u00a0Lua 5.1 Reference Manual<\/a>\u00a0Free online:\u00a0Programming in Lua (first edition)<\/a>\u00a0for Lua 5.0\u00a0Programming in Lua 2nd edition<\/a>\u00a0at Amazon<\/td>\nFree online:\u00a0Lua 5.3 Reference Manual<\/a>\u00a0Free online:\u00a0Programming in Lua (first edition)<\/a>\u00a0for Lua 5.0\u00a0Programming in Lua 4th edition<\/a>\u00a0via Amazon<\/td>\nLua version history<\/a>\u00a0has links to free online Reference Manuals for all versions\u00a0Programming in Lua<\/a>\u00a0paperbacks (editions 2 to 4) are all available via Amazon in the country of your choice<\/td>\n<\/tr>\n
Lua Wiki (programming language information & resources)<\/td>\nLua Wiki ~ Main Page<\/a>\u00a0and\u00a0Lua Wiki ~ Sample Code<\/a>. Note: There will be elements of the advice and sample code that apply only to the later versions of Lua, not 5.1.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Lua Library Modules<\/h2>\n

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 \u0192h<\/span><\/span> plugins. 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. \u0192h<\/span><\/span>8 ships the same set of libraries as \u0192h<\/span><\/span>7, rebuilt as 64-bit DLLs, plus two new ones:\u00a0LPeg<\/a>\u00a0and its\u00a0re<\/code>\u00a0module. Several libraries are at a different version from \u0192h<\/span><\/span>7 (and from the version stated in the \u0192h<\/span><\/span>8 Plugin Help); the \u0192h<\/span><\/span>8 column below shows the version actually reported by the library when loaded. The\u00a0require<\/code>\u00a0lines shown for \u0192h<\/span><\/span>7 all work unchanged in \u0192h<\/span><\/span>8.<\/p>\n

<\/a>IUP GUI Builder<\/h2>\n

This is a pre-installed library used by \u0192h<\/span><\/span> plugins when they need to present a user interface more complex than the simple message box and prompts provided by the \u0192h<\/span><\/span> API. The version supported by \u0192h<\/span><\/span> 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 \u0192h<\/span><\/span> and the current version.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n
<\/td>\n\u0192h<\/span><\/span> versions 5 & 6<\/strong><\/td>\n\u0192h<\/span><\/span> version 7<\/strong><\/td>\n\u0192h<\/span><\/span> version 8<\/strong><\/td>\nMake available by:<\/strong><\/td>\n<\/tr>\n
IUP version<\/td>\nV5: 3.5 V6: 3.11.2<\/td>\n3.28<\/td>\n3.28 (64-bit)<\/td>\nrequire (\"iuplua\")<\/code><\/td>\n<\/tr>\n
IUP reference manual and programming guides<\/td>\nFree online:\u00a0IUP Portable User Interface\u00a0<\/a>Read carefully to identify features that are not available in the version you are using.\u00a0A Basic Guide to using IupLua<\/a>\u00a0IUP GUI Builder Hints and Tips<\/a><\/td>\n<\/tr>\n
Additional IUP Libraries<\/td>\nIupControls<\/a>\u00a0IupGLCanvas<\/a>\u00a0IupGLControls<\/a>\u00a0IupMglPlot<\/a>\u00a0IupOleControl<\/a>\u00a0IupScintilla<\/a>\u00a0IupWebBrowser<\/a>\u00a0All are present in \u0192h<\/span><\/span>7 and \u0192h<\/span><\/span>8.<\/td>\nrequire( \"iupluacontrols\" )<\/code><\/td>\n<\/tr>\n
require( \"iupluagl\" )<\/code><\/td>\n<\/tr>\n
require( \"iupluaglcontrols\" )<\/code><\/td>\n<\/tr>\n
require( \"iuplua_mglplot\" )<\/code><\/td>\n<\/tr>\n
require( \"iupluaole\" )<\/code><\/td>\n<\/tr>\n
require( \"iuplua_scintilla\" )<\/code><\/td>\n<\/tr>\n
require( \"iupluaweb\" )<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Other Lua Library Modules<\/h2>\n

Not all these libraries are pre-installed in \u0192h<\/span><\/span> Versions 5 or 6; you may need to use the\u00a0Module Require With Load (code snippet)<\/a>\u00a0to use them within your plugin. Most of them\u00a0are<\/strong>\u00a0pre-installed in \u0192h<\/span><\/span>7 and \u0192h<\/span><\/span>8 and you do not need to use loadrequire. The versions supported by \u0192h<\/span><\/span> 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 \u0192h<\/span><\/span> and the current version.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
<\/td>\n\u0192h<\/span><\/span> versions 5 & 6<\/strong><\/td>\n\u0192h<\/span><\/span> version 7<\/strong><\/td>\n\u0192h<\/span><\/span> version 8<\/strong><\/td>\nNotes<\/strong><\/td>\n<\/tr>\n
Lua File System<\/td>\nV6: 1.5<\/td>\n1.7<\/td>\n1.6.3 (the \u0192h<\/span><\/span>8 Plugin Help says 1.7)<\/td>\nrequire( \"lfs\" )<\/code><\/td>\n<\/tr>\n
Free online:\u00a0Lua File System Library Manual<\/a>\u00a0Note: lfs will not work with file names and paths that include UTF8 characters; use\u00a0fhFileUtils<\/a>\u00a0for those.<\/td>\n<\/tr>\n
LuaCOM<\/td>\nV6, V7, V8: 1.3 Free online:\u00a0LuaCOM User Manual Version 1.3<\/a>\u00a0Note: in \u0192h<\/span><\/span>8 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 \u0192h<\/span><\/span>8.<\/td>\nrequire (\"luacom\")<\/code><\/td>\n<\/tr>\n
IM: Digital Imaging Toolkit<\/td>\nV5: 3.4.2 V6: 3.8.2<\/td>\n3.13<\/td>\n3.13<\/td>\nrequire( \"imlua\" ,<\/code>\u00a0\"imlua_process\" )<\/code><\/td>\n<\/tr>\n
Free online:\u00a0IM – Digital Imaging Tool Version<\/a><\/td>\n<\/tr>\n
CD: 2-D Graphics library<\/td>\nV5 and 6: Version tba<\/td>\n5.12<\/td>\n5.12<\/td>\nrequire (\"cdlua\")<\/code><\/td>\n<\/tr>\n
Free online:\u00a0CD – A 2D Graphics Library<\/a><\/td>\n<\/tr>\n
MD5: Cryptographic library<\/td>\nV6, V7: 1.2 Free online:\u00a0MD5: Cryptographic Library for Lua<\/a><\/td>\n1.3 (the \u0192h<\/span><\/span>8 Plugin Help says 1.2) The companion\u00a0des56<\/code>\u00a0module is also present.<\/td>\n\u0192h<\/span><\/span>5 and 6:\u00a0loadrequire ( \"md5\" )<\/code>\u00a0\u0192h<\/span><\/span>7 and 8:\u00a0md5 = require (\"md5\")<\/code><\/td>\n<\/tr>\n
LuaSocket: Network support<\/td>\nV5 and 6: tba<\/td>\n2.0.2<\/td>\n3.0.0 (the \u0192h<\/span><\/span>8 Plugin Help says 2.0.2)<\/td>\n\u0192h<\/span><\/span>5 and 6:\u00a0loadrequire ( \"socket\" )<\/code>\u00a0\u0192h<\/span><\/span>7 and 8:\u00a0socket = require (\"socket\")<\/code><\/td>\n<\/tr>\n
Free online:\u00a0LuaSocket: Network support for Lua<\/a>\u00a0(3.0 reference; the older 2.0.2 manual is at\u00a0w3.impa.br<\/a>) Note: LuaSocket provides plain HTTP only. Neither \u0192h<\/span><\/span>7 nor \u0192h<\/span><\/span>8 includes LuaSec (ssl<\/code>), so HTTPS requests must be made another way, e.g. via LuaCOM and\u00a0MSXML2.ServerXMLHTTP<\/code>\u00a0or\u00a0WinHttp.WinHttpRequest.5.1<\/code>.<\/td>\n<\/td>\n<\/tr>\n
LuaZip: Reading files inside zip files<\/td>\nFree online:\u00a0LuaZip: Reading files inside zip files<\/a><\/td>\nNot supported in \u0192h<\/span><\/span>7 or \u0192h<\/span><\/span>8 On Windows 10 above build 17063, you can use Tar (to create compressed archives) and uncompress both gz and zip ones\u00a0require 'luacom'<\/code>\u00a0-- Unzip<\/code>\u00a0sCmd = 'tar -xf \"L:\\\\fh_set_living.zip\" -C D:\\\\temp\\\\ '<\/code>\u00a0-- Zip<\/code>\u00a0sCmd = 'tar -cvzf \"d:\\\\temp\\\\doc.gz\" \"D:\\\\temp\\\\Doc\"'<\/code>\u00a0Shell = luacom.CreateObject(\"WScript.Shell\")<\/code>\u00a0Shell:Run (sCmd, 0, true)<\/code>\u00a0Note: this does not work in Crossover.<\/td>\n\u0192h<\/span><\/span>5 and 6:\u00a0loadrequire( \"zip\" )<\/code>\u00a0\u0192h<\/span><\/span>7 and 8: N\/A<\/td>\n<\/tr>\n
LuaSQL: DBMS interface<\/td>\nV5 and 6: Version tba<\/td>\nLuaSQL does not work in \u0192h<\/span><\/span>7 or \u0192h<\/span><\/span>8 and the\u00a0fhSQL<\/a>\u00a0library should be used instead. Note: \u0192h<\/span><\/span>8 ships an\u00a0lsqlite3.dll<\/code>\u00a0but\u00a0require(\"lsqlite3\")<\/code>\u00a0fails to load it; use fhSQL.<\/td>\n\u0192h<\/span><\/span>6:\u00a0loadrequire( \"luasql\", \"luasql.sqlite3\" )<\/code><\/td>\n<\/tr>\n
Free online:\u00a0LuaSql: DBMS interface for Lua<\/a><\/td>\n<\/td>\n<\/tr>\n
<\/a>Penlight Lua Library Modules<\/td>\nV5 and V6: 1.5.4 Free online:\u00a0Penlight Lua Library version 1.5.4<\/a><\/td>\nV7, V8: 1.8.0 Free documentation online:\u00a0Penlight Lua Libraries<\/a>\u00a0Changes from 1.8 to the current versions are documented\u00a0here\u00a0<\/a>(mostly bugfixes)<\/td>\n\u0192h<\/span><\/span>5 and 6:\u00a0loadrequire( \"pl\", \"pl.init\" )<\/code>\u00a0\u0192h<\/span><\/span>7 and 8:\u00a0require (\"pl.init\")<\/code><\/td>\n<\/tr>\n
<\/a>LPeg: Parsing Expression Grammars for Lua<\/td>\nN\/A<\/td>\nN\/A<\/td>\n1.1.0 Free online:\u00a0LPeg reference manual<\/a>\u00a0New in \u0192h<\/span><\/span>8 (not mentioned in the \u0192h<\/span><\/span>8 Plugin Help). A pattern-matching library that is far more capable than Lua’s built-in\u00a0string.find<\/code>\/string.match<\/code>: it can parse structured text such as GEDCOM lines, CSV, dates in mixed formats or citation strings with a proper grammar.<\/td>\n\u0192h<\/span><\/span>8:\u00a0lpeg = require (\"lpeg\")<\/code><\/td>\n<\/tr>\n
re: regex-like syntax for LPeg<\/td>\nN\/A<\/td>\nN\/A<\/td>\nSupplied with LPeg 1.1.0 Free online:\u00a0LPeg re module manual<\/a>\u00a0New in \u0192h<\/span><\/span>8. A pure-Lua module (part of LPeg) that lets you write LPeg grammars in a compact, regular-expression-like notation, e.g.\u00a0re.match(\"15 Mar 1852\", \"{%d+} ' ' {%a+} ' ' {%d+}\")<\/code>. It requires the\u00a0lpeg<\/code>\u00a0module.<\/td>\n\u0192h<\/span><\/span>8:\u00a0re = require (\"re\")<\/code><\/td>\n<\/tr>\n
<\/a>utf8: UTF-8 aware string functions<\/td>\n\u0192h<\/span><\/span>6: dated 2021-08-11<\/td>\n\u0192h<\/span><\/span>7: dated 2021-08-11<\/td>\nPresent; the module reports no version<\/td>\n\u0192h<\/span><\/span>6:\u00a0loadrequire( \"utf8\" )<\/code>\u00a0loadrequire( \"compat53\" )<\/code>\u00a0Note: 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. \u0192h<\/span><\/span>6, 7 and 8: a) If lower\/upper() support of UTF-8 characters is NOT needed:\u00a0utf8 = require ( \".utf8\" ):init()<\/code>\u00a0b) If lower\/upper() support of UTF-8 characters IS needed:\u00a0require ( \"utf8data\" )<\/code>\u00a0utf8 = require ( \".utf8\" )<\/code>\u00a0utf8.config[\"conversion\"] = { uc_lc = utf8_uc_lc; lc_uc = utf8_lc_uc; }<\/code>\u00a0utf8:init()<\/code>\u00a0Note: if you wish to overlay the standard string library with this utf8 library, follow the initialisation call with\u00a0for k,v in pairs(utf8) do\u00a0<\/code>string[k] = v<\/code>\u00a0end<\/code><\/td>\n<\/tr>\n
Online documentation<\/a>\u00a0Note 1: in \u0192h<\/span><\/span>6 the library compat53 is a prerequisite for this library. Note 2: in \u0192h<\/span><\/span>6 you must loadrequire this library using the ‘multiple sub-directories’ version of loadrequire\u00a0here.<\/a>\u00a0In 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:\u00a0require ( \"lfs\" )<\/code>\u00a0local path = fhGetContextInfo(\"CI_APP_DATA_FOLDER\")..\"\\\\Plugins\\\\\"<\/code>\u00a0if lfs.attributes(path..\"utf8data.lua\",\"mode\") ~= \"file\"<\/code>\u00a0and lfs.attributes(path..\"utf8.lua\",\"mode\") == \"file\" then<\/code>\u00a0os.remove(path..\"utf8.lua\")<\/code>\u00a0end<\/code><\/td>\n<\/tr>\n
<\/a>fhUtils: An \u0192h<\/span><\/span> specific library module that provides utility functions for building \u0192h<\/span><\/span> plugins.<\/td>\nN\/A<\/td>\n1.9\u00a0Online Documentation<\/a><\/td>\n1.16\u00a0Online Documentation<\/a><\/td>\n\u0192h<\/span><\/span>6: Not available \u0192h<\/span><\/span>7 and 8:\u00a0require (\"fhUtils\")<\/code><\/td>\n<\/tr>\n
<\/a>fhFileUtils: An \u0192h<\/span><\/span> specific library of modules to handle files with Unicode file names that are not supported by the standard Lua LFS and IO methods.<\/td>\nN\/A<\/td>\n1.0\u00a0Online Documentation<\/a><\/td>\n1.9\u00a0Online Documentation<\/a><\/td>\n\u0192h<\/span><\/span>6: Not available \u0192h<\/span><\/span>7 and 8:\u00a0require(\"fhFileUtils\")<\/code><\/td>\n<\/tr>\n
<\/a>fhSQL: An \u0192h<\/span><\/span> specific library to handle database access<\/td>\nN\/A<\/td>\n1.0\u00a0Online Documentation<\/a><\/td>\n1.3\u00a0Online Documentation<\/a><\/td>\n\u0192h<\/span><\/span>7 and 8:\u00a0require(\"fhSQL\")<\/code><\/td>\n<\/tr>\n
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\u00a0not<\/em>\u00a0make 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.<\/td>\nVersion 0.9\u00a0Online documentation<\/a><\/td>\nN\/A (not needed: \u0192h<\/span><\/span>7 and 8 are Lua 5.3)<\/td>\n\u0192h<\/span><\/span>6:\u00a0loadrequire (\"compat53\")<\/code><\/p>\n

compat53<\/code>\u00a0makes changes to your global environment and does not return a meaningful return value, so the usual idiom of storing the return of\u00a0require<\/code>\u00a0in a local variable makes no sense.<\/p><\/blockquote>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n","protected":false},"template":"","fh_version":[14,15,739,826],"skill_level":[18,17],"topic":[73],"class_list":["post-10705","kb_article","type-kb_article","status-publish","hentry","fh_version-v5","fh_version-v6","fh_version-v7","fh_version-v8","search_term-cdlua","search_term-imlua","search_term-iuplua","search_term-lfs","search_term-pl-init","search_term-utf8","search_term-utf8data","skill_level-advanced","skill_level-intermediate","topic-writing-plugins"],"_links":{"self":[{"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/kb_article\/10705","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/kb_article"}],"about":[{"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/types\/kb_article"}],"version-history":[{"count":3,"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/kb_article\/10705\/revisions"}],"predecessor-version":[{"id":12032,"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/kb_article\/10705\/revisions\/12032"}],"wp:attachment":[{"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/media?parent=10705"}],"wp:term":[{"taxonomy":"fh_version","embeddable":true,"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/fh_version?post=10705"},{"taxonomy":"skill_level","embeddable":true,"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/skill_level?post=10705"},{"taxonomy":"topic","embeddable":true,"href":"https:\/\/www.fhug.org.uk\/kb\/wp-json\/wp\/v2\/topic?post=10705"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}