| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> |
| 2 |
<html> |
| 3 |
<head> |
| 4 |
<title>Lua plugin for Geany - Introduction</title> |
| 5 |
</head> |
| 6 |
<body style="margin: 32px 25% 24px 5%"> |
| 7 |
<hr><h2>Lua scripting plugin for the Geany IDE</h2><hr> |
| 8 |
<p> |
| 9 |
This is a plugin for the <a href="http://www.geany.org/">Geany</a> IDE |
| 10 |
to provide <a href="http://www.lua.org/">Lua</a> scripting. |
| 11 |
</p><p> |
| 12 |
To begin, you should install the plugin and the example scripts. Please |
| 13 |
read the <tt> INSTALL </tt> file for more information. |
| 14 |
</p><p> |
| 15 |
The next time you start Geany, the plugin will look for a directory named <tt><b>geanylua</b></tt> |
| 16 |
in the user's plugin directory. <br> |
| 17 |
On Linux, this would be: <tt>~/.geany/plugins/geanylua</tt><br> |
| 18 |
( Unless you specify another config folder by the geany <tt>--config</tt> command line.)<br> |
| 19 |
Any scripts found in this <tt>/plugins/geanylua/</tt> directory will appear in |
| 20 |
the <i style="font-family:sans-serif">Tools->Lua Scripts</i> menu in Geany. |
| 21 |
</p><p> |
| 22 |
You can create additional scripts yourself, but all script files must have |
| 23 |
names that end with the <tt><b>.lua</b></tt> file extension. |
| 24 |
The menu labels are generated from the filenames like this: |
| 25 |
<ol> |
| 26 |
<li> The <tt><b>.lua</b></tt> filename extension is removed. |
| 27 |
<li> If the filename <i>begins</i> with two decimal digits, followed by a dot, |
| 28 |
those three characters are stripped off. Since the list of filenames is |
| 29 |
scanned in alphanumeric order, this convention allows for arbitrary |
| 30 |
sorting. For example if you wanted "<tt>Zebra</tt>" to appear before "<tt>Apple</tt>" |
| 31 |
you could name your files |
| 32 |
"<tt>01.Zebra.lua</tt>" and "<tt>02.Apple.lua</tt>" . |
| 33 |
<li> If the resulting label <i>ends</i> with a trailing underscore, that underscore |
| 34 |
is removed, and replaced with an ellipsis (three dots). This notation is generally |
| 35 |
used to indicate to the user that the menu item invokes an additional dialog. |
| 36 |
<li> If the label contains any addtional underscores, the first (leftmost) underscore is removed, |
| 37 |
and the letter immediately following it will be marked as the underlined |
| 38 |
"accelerator" key for the menu item. |
| 39 |
<li> Finally, the first letter of the label is capitalized, and all hyphens are converted to spaces. |
| 40 |
|
| 41 |
</ol> |
| 42 |
<p> |
| 43 |
No effort is made by the plugin to resolve conflicting accelerators. |
| 44 |
While these collisions are generally harmless, you should take some |
| 45 |
effort to make sure you don't create inaccessible (duplicate) mnemonic keys. |
| 46 |
</p><p> |
| 47 |
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 |
| 48 |
reload the plugin in order for the change to completely take effect. |
| 49 |
( The plugin can be reloaded either by restarting Geany, or |
| 50 |
by toggling it OFF/ON via Geany's Plugin Manager, |
| 51 |
or by calling the <tt>rescan()</tt> function from inside a script. ) |
| 52 |
</p><p> |
| 53 |
If there are any sub-directories that contain scripts, these will be recursed |
| 54 |
to create sub-menus, with two exceptions - folders named <tt><b>events</b></tt> or <tt><b>support</b></tt> |
| 55 |
will be ignored, these names are considered reserved. The <tt><b>events</b></tt> folder is |
| 56 |
described below, and the <tt><b>support</b></tt> folder can be used to store arbitrary |
| 57 |
user data files, modules, etc. |
| 58 |
</p><p> |
| 59 |
<a name="events"><br></a>The special directory <tt>./plugins/geanylua/events/</tt> |
| 60 |
can contain some scripts that |
| 61 |
will be invoked whenever the respective event is triggered by Geany. |
| 62 |
</p><p> |
| 63 |
Currently, there are nine valid filenames for the event scripts: |
| 64 |
<dl compact> |
| 65 |
<dt><tt>init.lua </tt></dt><dd> -- Runs when the plugin is loaded.</dd> |
| 66 |
<dt><tt>cleanup.lua </tt></dt><dd> -- Runs when the plugin is unloaded.</dd> |
| 67 |
|
| 68 |
<dt><tt>saved.lua </tt></dt><dd> -- Runs when an open document is saved.</dd> |
| 69 |
<dt><tt>created.lua </tt></dt><dd> -- Runs when a new document is created.</dd> |
| 70 |
<dt><tt>opened.lua </tt></dt><dd> -- Runs when an existing file is opened.</dd> |
| 71 |
<dt><tt>activated.lua</tt></dt><dd> -- Runs when switching documents (notebook tabs).</dd> |
| 72 |
|
| 73 |
<dt><tt>proj-opened.lua </tt></dt><dd> -- Runs when a project is opened.</dd> |
| 74 |
<dt><tt>proj-saved.lua </tt></dt><dd> -- Runs when a project is saved.</dd> |
| 75 |
<dt><tt>proj-closed.lua </tt></dt><dd> -- Runs when a project is closed.</dd> |
| 76 |
</dl> |
| 77 |
<p> |
| 78 |
Note that if any of these nine files exists, it will be executed each time |
| 79 |
its corresponding event occurs, which will result in some increase in disk activity. |
| 80 |
In particular, you might notice a delay in startup time with the <tt>opened.lua</tt> |
| 81 |
script when you open a bunch of files at once from the commmand line, etc. |
| 82 |
</p><p> |
| 83 |
<br><br> |
| 84 |
Consult the <a href="geanylua-ref.html">reference</a> page for documentation of the Geany-specific Lua functions. |
| 85 |
</p><p> |
| 86 |
|
| 87 |
A complete discussion of the Lua language is way beyond the scope of this |
| 88 |
plugin package, but there is plenty of information available on the net, |
| 89 |
For starters, you can check out: |
| 90 |
</p><p> |
| 91 |
<dl> |
| 92 |
|
| 93 |
<dt> |
| 94 |
The manual: |
| 95 |
</dt> |
| 96 |
<dd> |
| 97 |
<a href="http://www.lua.org/manual/5.1/"> |
| 98 |
http://www.lua.org/manual/5.1/ |
| 99 |
</a><br><br> |
| 100 |
</dd> |
| 101 |
|
| 102 |
<dt>The wiki:</dt> |
| 103 |
<dd> |
| 104 |
<a href="http://lua-users.org/wiki/TutorialDirectory"> |
| 105 |
http://lua-users.org/wiki/TutorialDirectory |
| 106 |
</a><br><br> |
| 107 |
</dd> |
| 108 |
|
| 109 |
<dt> |
| 110 |
The book: |
| 111 |
</dt> |
| 112 |
<dd> |
| 113 |
<a href="http://www.lua.org/pil/"> |
| 114 |
http://www.lua.org/pil/ |
| 115 |
</a><br><br> |
| 116 |
</dd> |
| 117 |
|
| 118 |
</dl> |
| 119 |
|
| 120 |
<p> |
| 121 |
Also, be warned that the plugin does not place any restrictions on what |
| 122 |
you can or can't do from inside a script. For example, if you decide to |
| 123 |
call <tt> os.exit() </tt> from a script, you will end your current Geany session |
| 124 |
immediately, and any unsaved changes will be lost! </p><p> |
| 125 |
You should also take some caution not to write a script that hangs indefinitely, |
| 126 |
if this happens, the only way out is to kill the editor. |
| 127 |
</p> |
| 128 |
|
| 129 |
|
| 130 |
</body> |
| 131 |
</html> |