Lua scripting plugin for the Geany IDE

This is a plugin for the Geany IDE to provide Lua scripting.

To begin, you should install the plugin and the example scripts. Please read the INSTALL file for more information.

The next time you start Geany, the plugin will look for a directory named geanylua in the user's plugin directory.
On Linux, this would be:   ~/.geany/plugins/geanylua
( Unless you specify another config folder by the geany --config command line.)
Any scripts found in this /plugins/geanylua/ directory will appear in the Tools->Lua Scripts menu in Geany.

You can create additional scripts yourself, but all script files must have names that end with the .lua file extension.   The menu labels are generated from the filenames like this:

1. The  .lua  filename extension is removed.
2. If the filename begins with two decimal digits, followed by a dot, those three characters are stripped off. Since the list of filenames is scanned in alphanumeric order, this convention allows for arbitrary sorting.   For example if you wanted "Zebra" to appear before "Apple" you could name your files   "01.Zebra.lua"   and   "02.Apple.lua" .
3. If the resulting label ends with a trailing underscore, that underscore is removed, and replaced with an ellipsis (three dots). This notation is generally used to indicate to the user that the menu item invokes an additional dialog.
4. If the label contains any addtional underscores, the first (leftmost) underscore is removed, and the letter immediately following it will be marked as the underlined "accelerator" key for the menu item.
5. Finally, the first letter of the label is capitalized, and all hyphens are converted to spaces.

No effort is made by the plugin to resolve conflicting accelerators. While these collisions are generally harmless, you should take some effort to make sure you don't create inaccessible (duplicate) mnemonic keys.

Note that if you modify an existing script, the change will take effect immediately, but if you delete an existing script, or add a new script, you must reload the plugin in order for the change to completely take effect.   ( The plugin can be reloaded either by restarting Geany, or by toggling it OFF/ON via Geany's Plugin Manager, or by calling the rescan() function from inside a script. )

If there are any sub-directories that contain scripts, these will be recursed to create sub-menus, with two exceptions - folders named  events  or  support  will be ignored, these names are considered reserved. The events folder is described below, and the support folder can be used to store arbitrary user data files, modules, etc.

The special directory  ./plugins/geanylua/events/  can contain some scripts that will be invoked whenever the respective event is triggered by Geany.

Currently, there are nine valid filenames for the event scripts:

init.lua  

-- Runs when the plugin is loaded.

cleanup.lua  

-- Runs when the plugin is unloaded.

saved.lua  

-- Runs when an open document is saved.

created.lua  

-- Runs when a new document is created.

opened.lua  

-- Runs when an existing file is opened.

activated.lua

-- Runs when switching documents (notebook tabs).

proj-opened.lua  

-- Runs when a project is opened.

proj-saved.lua  

-- Runs when a project is saved.

proj-closed.lua  

-- Runs when a project is closed.

Note that if any of these nine files exists, it will be executed each time its corresponding event occurs, which will result in some increase in disk activity. In particular, you might notice a delay in startup time with the  opened.lua  script when you open a bunch of files at once from the commmand line, etc.

Consult the reference page for documentation of the Geany-specific Lua functions.

A complete discussion of the Lua language is way beyond the scope of this plugin package, but there is plenty of information available on the net, For starters, you can check out:

The manual:

http://www.lua.org/manual/5.1/

The wiki:

http://lua-users.org/wiki/TutorialDirectory

The book:

http://www.lua.org/pil/

Also, be warned that the plugin does not place any restrictions on what you can or can't do from inside a script. For example, if you decide to call  os.exit()  from a script, you will end your current Geany session immediately, and any unsaved changes will be lost!

You should also take some caution not to write a script that hangs indefinitely, if this happens, the only way out is to kill the editor.