LibrarySupport Module

Lua allows the execution of external script files with the global function dofile. However, in order to use this function, the full access path of that file must be known - either in its "absolute" form (i.e. starting with the root directory of a given file system) or relative to the current working directory of the actual Lua script. Assuming, that frequently used auxiliary scripts ("modules") usually reside in a fixed location which is independent of a concrete Lua application, the LibrarySupport module provides a facility to look up such scripts by successively scanning a number of directories (specified in form of a "search path") for a given script file. If the requested script can be found, it is loaded and executed as usual (by means of dofile), otherwise, an error is generated which aborts the application.

Technical Description

In order to be as platform-independent as possible, the module first tries to determine the actual platform (or, more precise, the characters used to separate individual folder names within the access path of a file or individual entries within a search path). If TkLua appears to be present, its Tcl environment will be used to query the platform directly. Otherwise, the module tries to retrieve any required information either directly from related environment variables (LuaPathSeparator and LuaListSeparator) or by analyzing potentially available file access paths (found in environment variables LuaHome and LuaLibList).

Within the actual import function, this information is used to split the given search path (LuaLibList) into a sequence of directory access paths, and to convert the platform-independent (relative) access path of a given script file into a platform-specific form.

Usage Notes

Usually, it should be possible to dofile the LibrarySupport script from within a Lua application, although that approach raises exactly those issues the module aims to solve. To circumvent this problem, the LibrarySupport script file should be copied to a fixed location relative to the directory of the application - provided that the initial working directory of the application is the same as its program directory (i.e. the one that contains the script files which make up the application). If this condition cannot be guaranteed, the contents of the LibrarySupport module should be inserted into the application's source code.

As a third alternative, the LibrarySupport script file could be copied to a fixed absolute location (on a fixed file system). However, since this location would have to be "hard-wired" into the application, such a solution is not recommended.

Thus, a "typical" approach is to copy the LibrarySupport script file into the same directory where the application resides, and to insert the following statements into the program's source code:

  if (type(import) ~= "function") then
    dofile("LibrarySupport.lua");  -- provides a simple library import mechanism
  end;

From now on, further modules may be "imported" as follows:

  import(<module file name>);

assuming, that the modules handle attempts to "import" them more often than once themselves. Multiple module file names may be given as arguments for import. If any "module file name" actually contains a file access path, its directories should be separated by the platform-independent separator "/" (without quotes) rather than any platform-specific character. If the trailing ".lua" is missing from a "module file name", it is appended automatically by import.

Environment Variables

The LibrarySupport module makes use of the following environment variables (in alphabetical order):

LuaHome

should be set to the access path of the Lua installation directory. For the time being, this variable is only used to determine the LuaPathSeparator in the absence of TkLua - but this may change in the future;

LuaLibList

should be set to an ordered list of (access paths of) directories containing Lua "module" script files. The given list is scanned from left to right, and each directory from that list is searched for the requested script file - either until that file is found or no more list entries are left. Subdirectories of a given list entry are not automatically considered (as Lua lacks appropriate file system functions);

LuaListSeparator

may be set to the character used to separate the individual entries of a search path (the only supported setting - for all platforms - is ";");

LuaPathSeparator

may be set to the character used to separate the directory names within a file access path (typical settings are "/" (UNIX), "\" (Windows) or ":" (MacOS), always without quotes);

Source Code

The source code of this module is available for download:

• LibrarySupport.lua (ASCII file, 6183 bytes)

References