Manual of LuaFAR 3

Manual of LuaFAR 3

Brief description of LuaFAR package

This package’s purpose is to facilitate writing plugins for FAR in Lua programming language. The package provides source code for luafar3.dll (main product) and a luaplug.dll (“generic” plugin).

luafar3.dll allows:

• To program functions exported by the plugin in Lua: e.g., the function OpenW should be named export.Open in the Lua program, the same goes for all functions exported by the plugin.

• To call FAR service functions from a Lua program. The service functions are placed in the far, editor, viewer, panel and regex tables, and their names aren’t identical to the names of the respective FAR API functions. For instance, function EditorControl with parameter ECTL_GETINFO will be named editor.GetInfo in Lua programs.

• Note: the functions of the Unicode LuaFAR library assume string arguments and string return values to be in the UTF-8 encoding. (There are a few exceptions from this rule, mostly when strings are used to exchange binary data).

Currently, the documentation on LuaFAR API is incomplete and may be somewhat inaccurate. When in doubt, consult the source code. The API may change in the future.

As luafar3.dll itself is not a plugin, it should not be placed in the %FARHOME%\Plugins subtree (instead, place it in any directory listed in PATH). The usual way of using luafar3.dll is to create a wrapper plugin that redirects FAR’s calls of the exported functions to luafar3.dll, that in turn calls the functions written in Lua. This way, one instance of luafar3.dll can “serve” arbitrary number of plugins at the same time. An example of “wrapper plugin” is luaplug.dll (its source code is part of this package).

There are two Lua files that must be present in plugin’s DLL directory:

1. _globalinfo.lua (it should only contain the function export.GetGlobalInfo).
   This script must not call functions from far library (e.g., far.Message), as they are not yet available to LuaFAR when Far calls GetGlobalInfoW.

2. The starting (or “default”) Lua script, that is searched in the following order (see LF_RunDefaultScript for details):

   1. The plugin name with the extension .lua is looked for, e.g.: luaplug.dll -> luaplug.lua
   2. If the plugin name contains a hyphen, then its part preceding the last hyphen is looked for, e.g.: luaplug-x64.dll -> luaplug.lua.

When the starting script is run it receives one boolean argument:

• true – on its first run and after Lua state was recreated
• false – on subsequent runs caused by setting far.ReloadDefaultScript = true.