Some Considerations on Lua

The embedded Lua interpreter in whenever is surely a powerful feature, that can efficiently replace OS commands and scripts for many purposes, sometimes also in a way that is

  • more portable across systems, as the Lua interpreter is the same on all systems, as well as its standard library that provides many actions usually available via different commands on different operating systems,

  • significantly faster, because the interpreter is already in memory when it is instantiated by whenever and there are no shells and no external commands to be launched.

The current version of When supports a tool to install a script or a library, so that it can be required from the embedded interpreter in whenever: the --install-lua (or --upgrade-lua for upgrades) command, followed by a file name can be used and, if the file type is supported, it will be copied to an appropriate directory in APPDATA which is in the searched paths. The supported file types are:

  • .lua (Lua scripts): obviously Lua source files that can define functions, initialize or update tables, and so on,

  • .zip (ZIP archives): the zip contents, which are expected to be a tree of Lua source files and possibly binary modules, are extracted in a directory with the same name of the ZIP file in the Lua subdirectory of APPDATA.

There is no support for Lua C (binary) modules: the reason is that the interpreter embedded in whenever only operates in safe mode, which in turn disables dynamic loading of extenal binary libraries, which in fact Lua C modules are. Attempts to require a binary module, even if available in the correct directory, will result in a module not found runtime error for the embedded interpreter.

The syntax for the --install-lua tool is the following:

when tool --install-lua path/to/module.lua      # for single Lua files
when tool --install-lua path/to/module.zip      # for ZIP packed modules

and for --upgrade-lua is absolutely identical. path/to/module.lua and path/to/module.zip can be either relative or absolute.

At the moment no real package management is available, mainly because the most popular Lua package managers rely on development tools which are not always expected to be available on the host platform.

Note: the Lua library installation tool is in its very early development stage, and for the moment does not support removal for installed modules. To remove a module, it has to be manually deleted from the Lua subdirectory in APPDATA. For updates, the --upgrade-lua tool is available, which removes the destination prior to installing the module: this only works if the module to upgrade already exists and fails otherwise. This is intentional, because some modules might be required by tasks or conditions used by When, and the upgrade tool will refuse anyways to overwrite them.

If a pure Lua module is available as a directory structure, it is easy to produce a ZIP file that can be used with the --install-lua tool: most modern file managers offer a “Archive/Compress to ZIP” option using a mouse click on a folder, which can be used with the folder containing the desired module. The resulting ZIP file is suitable for installation using the tool.

See Also

◀ Main