{"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":"2025-05-24T15:48:47","modified_gmt":"2025-05-24T15:48:47","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
<\/td>\n\u0192h<\/span><\/span> versions 5 & 6<\/strong><\/td>\n\u0192h<\/span><\/span> version 7<\/strong><\/td>\nNotes<\/strong><\/td>\n<\/tr>\n
Lua version<\/td>\n5.1<\/td>\n5.3.5<\/td>\n5.4 was released on 29 Jun 2020<\/td>\n<\/tr>\n
Lua reference and programming manuals<\/td>\nFree online: Lua 5.1 Reference Manual<\/a><\/p>\n

Free online: Programming in Lua (first edition)<\/a> for Lua 5.0<\/p>\n

Programming in Lua 2nd edition<\/a> at Amazon<\/td>\n

Free online: Lua 5.3 Reference Manual<\/a><\/p>\n

Free online: Programming in Lua (first edition)<\/a> for Lua 5.0<\/p>\n

Programming in Lua 4th edition<\/a> at via Amazon<\/td>\n

Lua version history<\/a> has links to free online Reference Manuals for all versions<\/p>\n

Programming in Lua<\/a> paperbacks (editions 2 to 4) are all available via Amazon in the country of your choice<\/td>\n<\/tr>\n

Lua Wiki
\n(programming language information & resources)<\/td>\n		Lua Wiki ~ Main Page<\/span><\/a>\u00a0and Lua 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.\u00a0 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.<\/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.\u00a0 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>\nMake available by:<\/strong><\/td>\n<\/tr>\n
IUP version<\/td>\nV5: 3.5<\/p>\n

V6: 3.11.2<\/td>\n

3.28<\/td>\nrequire (\"iuplua\")<\/code><\/td>\n<\/tr>\n
IUP reference manual and programming guides<\/td>\nFree online: IUP Portable User Interface\u00a0<\/a><\/p>\n

Read carefully to identify features that are not available in the version you are using.<\/p>\n

A Basic Guide to using IupLua<\/a><\/p>\n

IUP GUI Builder Hints and Tips<\/a><\/td>\n<\/tr>\n

Additional IUP Libraries<\/td>\nIupControls<\/a>
\nIupGLCanvas<\/a>
\nIupGLControls<\/a>
\nIupMglPlot<\/a>
\nIupOleControl<\/a>
\nIupScintilla<\/a>
\nIupWebBrowser<\/a><\/td>\n		require( \"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 Module Require With Load (code snippet)<\/a> to use them within your plugin.\u00a0 Most of them are<\/strong> pre-installed in [fh]7 and you do not need to use loadrequire.<\/p>\n

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
<\/td>\n\u0192h<\/span><\/span> versions 5 & 6<\/strong><\/td>\n\u0192h<\/span><\/span> version 7<\/strong><\/td>\nNotes<\/strong><\/td>\n<\/tr>\n
Lua File System<\/td>\nV6: 1.5<\/td>\n1.7<\/td>\nrequire( \"lfs\" )<\/code><\/td>\n<\/tr>\n
Free online: Lua File System Library Manual<\/a><\/p>\n

Note: lfs will not work with file names and paths that include UTF8 characters.<\/td>\n<\/tr>\n

LuaCOM<\/td>\nV6, V7: 1.3<\/p>\n

Free online: LuaCOM User Manual Version 1.3<\/a><\/td>\n

require (\"luacom\")<\/code><\/td>\n<\/tr>\n
IM: Digital Imaging Toolkit<\/td>\nV5: 3.4.2<\/p>\n

V6: 3.8.2<\/td>\n

3.13<\/p>\n

 <\/td>\n

require( \"imlua\" ,<\/code>
\n\"imlua_process\" )<\/code><\/td>\n<\/tr>\n
Free online: IM – Digital Imaging Tool Version<\/a><\/td>\n<\/tr>\n
CD: 2-D Graphics library<\/td>\nV5 and 6: Version tba<\/td>\n5.12<\/td>\nrequire (\"cdlua\")<\/code><\/td>\n<\/tr>\n
Free online: CD – A 2D Graphics Library<\/a><\/td>\n<\/tr>\n
MD5: Cryptographic library<\/td>\nV6, V7: 1.2<\/p>\n

Free online: MD5: Cryptographic Library for Lua<\/a><\/td>\n

\u0192h<\/span><\/span>5 and 6: loadrequire ( \"md5\" )<\/code><\/p>\n\u0192h<\/span><\/span>7: md5 = require (\"md5\")<\/code><\/td>\n<\/tr>\n
LuaSocket: Network support<\/td>\nV5 and 6:\u00a0 tba<\/td>\n2.0.2<\/td>\n\u0192h<\/span><\/span>5 and 6: loadrequire ( \"socket\" )<\/code><\/p>\n\u0192h<\/span><\/span>7: socket = require (\"socket\")<\/code><\/td>\n<\/tr>\n
Free online: LuaSocket: Network support for Lua<\/a><\/td>\n<\/td>\n<\/tr>\n
LuaZip: Reading files inside zip files<\/td>\nFree online: LuaZip: Reading files inside zip files<\/a><\/td>\nNot supported in \u0192h<\/span><\/span>7.0.0<\/p>\n

On Windows 10 above build 17063, you can use Tar (to create compressed archives) and uncompress both gz and\u00a0zip<\/span> ones<\/p>\n

require 'luacom'<\/code>
\n-- Unzip<\/code>
\nsCmd = 'tar -xf \"L:\\\\fh_set_living.zip<\/span>\" -C D:\\\\temp\\\\ '<\/code>
\n--\u00a0Zip<\/span><\/code>
\nsCmd = 'tar -cvzf \"d:\\\\temp\\\\doc.gz\" \"D:\\\\temp\\\\Doc\"'<\/code><\/p>\n

Shell = luacom.CreateObject(\"WScript.Shell\")<\/code>
\nShell:Run (sCmd, 0, true)<\/code><\/p>\n

Note: this does not work in Crossover.<\/td>\n

\u0192h<\/span><\/span>5 and 6: loadrequire( \"zip\" )<\/code><\/p>\n\u0192h<\/span><\/span>7: N\/A<\/td>\n<\/tr>\n
LuaSQL: DMBS interface<\/td>\nV5 and 6: Version tba<\/td>\nLuaSQl does not work in \u0192h<\/span><\/span>7 and the fhSQL library should be used instead.<\/td>\n\u0192h<\/span><\/span>6:\u00a0loadrequire( \"luasql\", \"luasql.sqlite3\" )<\/code><\/td>\n<\/tr>\n
Free online: LuaSql: DBMS interface for Lua<\/a><\/td>\n<\/td>\n<\/tr>\n
<\/a>Penlight Lua Library Modules<\/td>\nV5 and V6: 1.5.4<\/p>\n

Free online: Penlight Lua Library version 1.5.4<\/a><\/td>\n

1.8<\/p>\n

Free documentation online: Penlight Lua Libraries<\/a><\/p>\n

Changes from 1.8 to the current versions are documented here <\/a>(mostly bugfixes)<\/td>\n

\u0192h<\/span><\/span>5 and 6: loadrequire( \"pl\", \"pl.init\" )<\/code><\/p>\n\u0192h<\/span><\/span>7: require (\"pl.init\")<\/code><\/td>\n<\/tr>\n
<\/a>utf8: UTF-8 aware string functions<\/td>\n\u0192h<\/span><\/span>6: dated 2021-08-11<\/p>\n

 <\/td>\n

\u0192h<\/span><\/span>7: dated 2021-08-11<\/p>\n

 <\/td>\n

\u0192h<\/span><\/span>6:<\/p>\n

loadrequire( \"utf8\" )<\/code>
\nloadrequire( \"compat53\" )<\/code><\/code><\/code><\/p>\n

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()\u00a0 of UTF-8 characters.<\/p>\n\u0192h<\/span><\/span>6 and 7:<\/p>\n

a) If lower\/upper() support of UTF-8 characters is NOT needed:<\/p>\n

utf8 = require ( \".utf8\" ):init()<\/code><\/p>\n

b) If lower\/upper() support of UTF-8 characters IS needed:<\/p>\n

require ( \"utf8data\" )<\/code>
\nutf8 = require ( \".utf8\" )<\/code>
\nutf8.config[\"conversion\"] = { uc_lc = utf8_uc_lc; lc_uc = utf8_lc_uc; }<\/code>
\nutf8:init()<\/code><\/p>\n

Note: if you wish to overlay the standard string library with this utf8 library, follow the initialisation call with<\/p>\n

for k,v in pairs(utf8) do\u00a0<\/code>
\n\u00a0 string[k] = v<\/code>
\nend<\/code><\/td>\n<\/tr>\n

Online documentation<\/a><\/p>\n

Note 1: in \u0192h<\/span><\/span>6 the library compat53 is a prerequisite for this library.<\/p>\n

Note 2: in \u0192h<\/span><\/span>6 you must loadrequire this library using the ‘multiple sub-directories’ version of loadrequire here.<\/a><\/p>\n

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:<\/p>\n

require ( \"lfs\" )<\/code>
\nlocal path = fhGetContextInfo(\"CI_APP_DATA_FOLDER\")..\"\\\\Plugins\\\\\"<\/code>
\nif lfs.attributes(path..\"utf8data.lua\",\"mode\") ~= \"file\"<\/code>
\nand lfs.attributes(path..\"utf8.lua\",\"mode\") == \"file\" then<\/code>
\n\u00a0 \u00a0os.remove(path..\"utf8.lua\")<\/code>
\nend<\/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<\/p>\n

Online Documentation<\/a><\/td>\n

\u0192h<\/span><\/span>6: Not available<\/p>\n\u0192h<\/span><\/span>7:<\/p>\n

require (\"fhUtils\")<\/code><\/td>\n<\/tr>\n

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<\/p>\n

Online Documentation<\/a><\/td>\n

\u0192h<\/span><\/span>6: Not available<\/p>\n\u0192h<\/span><\/span>7:<\/p>\n

require(\"fhFileUtils\")<\/code><\/td>\n<\/tr>\n

fhSQL: An \u0192h<\/span><\/span> specific library to handle database access<\/td>\n<\/td>\n1.0<\/p>\n

Online Documentation<\/a><\/td>\n

\u0192h<\/span><\/span>7:<\/p>\n

require(\"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 not<\/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<\/p>\n

Online documentation<\/a><\/td>\n

N\/A<\/td>\n\u0192h<\/span><\/span>6: loadrequire (\"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

<\/h2>\n","protected":false},"template":"","fh_version":[14,15,739],"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","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"}],"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}]}}