Debian Codegraph @

geanylua/docs/geanylua-ref.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <html>
3 <head>
4 <title>Lua plugin for Geany - Reference</title>
5 <style type="text/css">
6 <!--
7 UL,PRE,P{
8 margin: 12px 25% 12px 5%
9 }
10 .odd {
11 background-color:#f4f4fc
12 }
13 .even {
14 background-color:#ffffff
15 }
16 .desc {
17 font-family:sans-serif
18 }
19 -->
20 </style>
21 </head>
22 <body >
23 <hr><h2>Lua scripting plugin for the Geany IDE</h2><hr><br>
24 The Geany module provides these functions and variables...<br><br><br>
25 <div style="background-color:#fcf4f4; margin-left:12px; margin-right:12px">
26 <hr>
27 <table summary="quick links" width="90%" align="center" >
28 <tr align="center" >
29 <td><a href="#Editor_functions">Editor functions</a></td>
30 <td><a href="#System_functions">System functions</a></td>
31 <td><a href="#Dialog_functions">Dialog functions</a></td>
32 </tr></table>
33 <hr>
34 </div>
35 <br><br>
36
37 <b><a name="Editor_functions"></a>Editor functions:</b>
38
39 <table style="font-family:monospace" summary="function index" width="90%">
40 <tr class="odd">
41 <td>&nbsp; function <a href="#activate"><b>activate</b></a> ( tab_id )<br></td>
42 <td class="desc">-- Activate the specified editor tab.</td>
43 </tr>
44 <tr class="even">
45 <td>&nbsp; function <a href="#appinfo"><b>appinfo</b></a> ()<br></td>
46 <td class="desc">-- Return information about the current Geany instance.</td>
47 </tr>
48 <tr class="odd">
49 <td>&nbsp; function <a href="#batch"><b>batch</b></a> ( start )<br></td>
50 <td class="desc">-- Set a marker for a reversible group of operations.</td>
51 </tr>
52
53 <tr class="even">
54 <td>&nbsp; function <a href="#byte"><b>byte</b></a> ( [position] )<br></td>
55 <td class="desc">-- Get the numeric value of the character at position.</td>
56 </tr>
57 <tr class="odd">
58 <td>&nbsp; function <a href="#caret"><b>caret</b></a> ( [position] )<br></td>
59 <td class="desc">-- Get or set the caret position.</td>
60 </tr>
61
62 <tr class="even">
63 <td>&nbsp; function <a href="#close"><b>close</b></a> ( [filename]|[index] )<br></td>
64 <td class="desc">-- Close a document.</td>
65 </tr>
66
67 <tr class="odd">
68 <td>&nbsp; function <a href="#copy"><b>copy</b></a> ( [content]|[start,stop] )<br></td>
69 <td class="desc">-- Copy text to the clipboard.</td>
70 </tr>
71
72 <tr class="even">
73 <td>&nbsp; function <a href="#count"><b>count</b></a> ()<br></td>
74 <td class="desc">-- Get the number of open tabs.</td>
75 </tr>
76
77 <tr class="odd">
78 <td>&nbsp; function <a href="#cut"><b>cut</b></a> ()<br></td>
79 <td class="desc">-- Cut selection to the clipboard.</td>
80 </tr>
81
82 <tr class="even">
83 <td>&nbsp; function <a href="#documents"><b>documents</b></a> ( [doc_id] )<br></td>
84 <td class="desc">-- Access the list of all open documents.</td>
85 </tr>
86
87 <tr class="odd">
88 <td>&nbsp; function <a href="#filename"><b>filename</b></a> ()<br></td>
89 <td class="desc">-- Get the name of the current document.</td>
90 </tr>
91
92 <tr class="even">
93 <td>&nbsp; function <a href="#fileinfo"><b>fileinfo</b></a> ()<br></td>
94 <td class="desc">-- Return some information about the current document.</td>
95 </tr>
96
97 <tr class="odd">
98 <td>&nbsp; function <a href="#find"><b>find</b></a> ( phrase, start, stop, options )<br></td>
99 <td class="desc">-- Search for text within the document.</td>
100 </tr>
101
102 <tr class="even">
103 <td>&nbsp; function <a href="#height"><b>height</b></a> ()<br></td>
104 <td class="desc">-- Get the number of lines in the current document</td>
105 </tr>
106
107 <tr class="odd">
108 <td>&nbsp; function <a href="#keycmd"><b>keycmd</b></a> ( command )<br></td>
109 <td class="desc">-- Activate a built-in Geany menu command.</td>
110 </tr>
111
112 <tr class="even">
113 <td>&nbsp; function <a href="#keygrab"><b>keygrab</b></a> ( [prompt] )<br></td>
114 <td class="desc">-- Intercept a keystroke from Geany.</td>
115 </tr>
116
117
118 <tr class="odd">
119 <td>&nbsp; function <a href="#length"><b>length</b></a> ()<br></td>
120 <td class="desc">-- Get number of characters in the current document.</td>
121 </tr>
122
123 <tr class="even">
124 <td>&nbsp; function <a href="#lines"><b>lines</b></a> ( [index] )<br></td>
125 <td class="desc">-- Get the text on one specific line, or all of them.</td>
126 </tr>
127
128 <tr class="odd">
129 <td>&nbsp; function <a href="#match"><b>match</b></a> ( [position] )<br></td>
130 <td class="desc">-- Find a matching bracket, parenthesis, etc.</td>
131 </tr>
132
133 <tr class="even">
134 <td>&nbsp; function <a href="#navigate"><b>navigate</b></a> ( mode,count [,extend [,rect]])<br></td>
135 <td class="desc">-- Move the caret incrementally.</td>
136 </tr>
137
138 <tr class="odd">
139 <td>&nbsp; function <a href="#newfile"><b>newfile</b></a> ( [filename [, filetype] )<br></td>
140 <td class="desc">-- Create a new document.</td>
141 </tr>
142
143 <tr class="even">
144 <td>&nbsp; function <a href="#open"><b>open</b></a> ( [filename]|[index] )<br></td>
145 <td class="desc">-- Open or reload a file from disk.</td>
146 </tr>
147
148 <tr class="odd">
149 <td>&nbsp; function <a href="#paste"><b>paste</b></a> ()<br></td>
150 <td class="desc">-- Paste text from the clipboard.</td>
151 </tr>
152
153
154 <tr class="even">
155 <td>&nbsp; function <a href="#rowcol"><b>rowcol</b></a> ( [pos]|[row,col] )<br></td>
156 <td class="desc">-- Translate between linear and rectangular locations.</td>
157 </tr>
158
159 <tr class="odd">
160 <td>&nbsp; function <a href="#save"><b>save</b></a> ( [filename]|[index] )<br></td>
161 <td class="desc">-- Save an open document to a disk file.</td>
162 </tr>
163
164 <tr class="even">
165 <td>&nbsp; function <a href="#scintilla"><b>scintilla</b></a> ( msg_id, wparam, lparam )<br></td>
166 <td class="desc">-- Send a message directly to the Scintilla widget.</td>
167 </tr>
168
169 <tr class="odd">
170 <td>&nbsp; function <a href="#select"><b>select</b></a> ( [[start,] stop] )<br></td>
171 <td class="desc">-- Get or set the selection endpoints and caret.</td>
172 </tr>
173
174 <tr class="even">
175 <td>&nbsp; function <a href="#selection"><b>selection</b></a> ( [content] )<br></td>
176 <td class="desc">-- Get or set the contents of the document's selection.</td>
177 </tr>
178
179 <tr class="odd">
180 <td>&nbsp; function <a href="#settype"><b>settype</b></a> ( filetype )<br></td>
181 <td class="desc">-- Change the current file type.</td>
182 </tr>
183
184 <tr class="even">
185 <td>&nbsp; function <a href="#signal"><b>signal</b></a> ( widget, signal )<br></td>
186 <td class="desc">-- Send a GTK signal to a Geany interface widget.</td>
187 </tr>
188
189 <tr class="odd">
190 <td>&nbsp; function <a href="#status"><b>status</b></a> ( message )<br></td>
191 <td class="desc">-- Send a string to display in the status tab of the messages window.</td>
192 </tr>
193
194 <tr class="even">
195 <td>&nbsp; function <a href="#text"><b>text</b></a> ( [content] )<br></td>
196 <td class="desc">-- Get or set the contents of the entire document.</td>
197 </tr>
198
199 <tr class="odd">
200 <td>&nbsp; function <a href="#word"><b>word</b></a> ( [position] )<br></td>
201 <td class="desc">-- Get the word at the specified location.</td>
202 </tr>
203
204 <tr class="even">
205 <td>&nbsp; function <a href="#xsel"><b>xsel</b></a> ( [text] )<br></td>
206 <td class="desc">-- Get or set the contents of the primary X selection.</td>
207 </tr>
208
209 <tr class="odd">
210 <td>&nbsp; function <a href="#yield"><b>yield</b></a> ()<br></td>
211 <td class="desc">-- Refreshes the user interface.</td>
212 </tr>
213
214
215 <tr class="even">
216 <td>&nbsp;</td>
217 <td></td>
218 </tr>
219
220 <tr class="odd">
221 <td>&nbsp; var <a href="#caller"><b>caller</b></a> : <i>number</i><br>
222 </td><td class="desc">-- The index of the document that triggered an event.</td>
223 </tr>
224
225 <tr class="even">
226 <td>&nbsp; var <a href="#rectsel"><b>rectsel</b></a> : <i>boolean</i><br>
227 </td><td class="desc">-- Whether or not the selection is in rectangular mode.</td>
228 </tr>
229 <tr class="odd">
230 <td>&nbsp; var <a href="#project"><b>project</b></a> : <i>keyfile</i><br>
231 </td><td class="desc">-- An object representing a project configuration event.</td>
232 </tr>
233 <tr class="even">
234 <td>&nbsp; var <a href="#script"><b>script</b></a> : <i>string</i><br>
235 </td><td class="desc">-- The filename of the currently executing Lua script.</td>
236 </tr>
237 <tr class="odd">
238 <td>&nbsp; var <a href="#wordchars"><b>wordchars</b></a> : <i>string</i><br></td>
239 <td class="desc">-- The characters that are considered part of a word.</td>
240 </tr>
241
242 </table>
243
244
245 <br>
246 <br><br>
247
248 <b><a name="System_functions"></a>System functions:</b>
249 <table style="font-family:monospace" summary="function index" width="90%">
250 <tr class="odd">
251 <td>&nbsp; function <a href="#basename"><b>basename</b></a>( pathstr )<br></td>
252 <td class="desc">-- Extract the filename portion of a path string.</td>
253 </tr>
254 <tr class="even">
255 <td>&nbsp; function <a href="#dirlist"><b>dirlist</b></a>( path )<br></td>
256 <td class="desc">-- List the contents of a folder.</td>
257 </tr>
258 <tr class="odd">
259 <td>&nbsp; function <a href="#dirname"><b>dirname</b></a>( pathstr )<br></td>
260 <td class="desc">-- Get the directory portion of a file's path.</td>
261 </tr>
262 <tr class="even">
263 <td>&nbsp; function <a href="#fullpath"><b>fullpath</b></a>( filename )<br></td>
264 <td class="desc">-- Get the full path to a file.</td>
265 </tr>
266 <tr class="odd">
267 <td>&nbsp; function <a href="#launch"><b>launch</b></a> ( program [, arg1 [, arg2, ...]] )<br></td>
268 <td class="desc">-- Execute an external application.</td>
269 </tr>
270 <tr class="even">
271 <td>&nbsp; function <a href="#optimize"><b>optimize</b></a> ()<br></td>
272 <td class="desc">-- Run a script without the debug hook.</td>
273 </tr>
274 <tr class="odd">
275 <td>&nbsp; function <a href="#reloadconf"><b>reloadconf</b></a> ()<br></td>
276 <td class="desc">-- Reload Configuration.</td>
277 </tr>
278 <tr class="even">
279 <td>&nbsp; function <a href="#rescan"><b>rescan</b></a> ()<br></td>
280 <td class="desc">-- Regenerate the scripts menu.</td>
281 </tr>
282 <tr class="odd">
283 <td>&nbsp; function <a href="#stat"><b>stat</b></a> ( filename [, lstat] )<br></td>
284 <td class="desc">-- Retrieve some information about a disk file.</td>
285 </tr>
286 <tr class="even">
287 <td>&nbsp; function <a href="#timeout"><b>timeout</b></a> ( seconds )<br></td>
288 <td class="desc">-- Control maximum time allowed for script execution.</td>
289 </tr>
290 <tr class="odd">
291 <td>&nbsp; function <a href="#wkdir"><b>wkdir</b></a> ( [folder] )<br></td>
292 <td class="desc">-- Get or set the current working directory.</td>
293 </tr>
294 <tr class="even">
295 <td>&nbsp;</td>
296 <td></td>
297 </tr>
298 <tr class="odd">
299 <td>&nbsp; var <a href="#dirsep"><b>dirsep</b></a> : <i>string</i><br>
300 </td><td class="desc">-- The default filesystem path separator, "<tt>/</tt>" or "<tt>\</tt>".</td>
301 </tr>
302 </table>
303
304 <br>
305 <br><br>
306
307 <b><a name="Dialog_functions"></a>Dialog functions:</b>
308 <table style="font-family:monospace" summary="function index" width="90%">
309 <tr class="odd">
310 <td>&nbsp; function <a href="#choose"><b>choose</b></a> ( prompt, items )</td>
311 <td class="desc" width="33%">-- Select an item from the list.</td>
312 </tr>
313 <tr class="even">
314 <td>&nbsp; function <a href="#confirm"><b>confirm</b></a> ( title, question, default )</td>
315 <td class="desc">-- Ask a yes-or-no question.</td>
316 </tr>
317 <tr class="odd">
318 <td>&nbsp; function <a href="#input"><b>input</b></a> ( [prompt] [,default] )</td>
319 <td class="desc">-- Prompt to enter some text.</td>
320 </tr>
321 <tr class="even">
322 <td>&nbsp; function <a href="#message"><b>message</b></a> ( [title,] message )</td>
323 <td class="desc">-- Display some information.</td>
324 </tr>
325 <tr class="odd">
326 <td>&nbsp; function <a href="#pickfile"><b>pickfile</b></a> ( [mode [,path [,filter]]] )</td>
327 <td class="desc">-- Select a file from disk.</td>
328 </tr>
329 <tr class="even">
330 <td>&nbsp;</td>
331 <td></td>
332 </tr>
333 <tr class="odd">
334 <td>&nbsp; var <a href="#banner"><b>banner</b></a> : <i>string</i><br></td>
335 <td class="desc">-- The window title for all dialogs.</td>
336 </tr>
337 </table><br>
338 If you need a more advanced dialog creation API, check out the
339 <tt><big><a href="geanylua-input.html">dialog</a></big></tt> module.
340 <br><br><br>
341 <hr>
342
343
344 <hr><a name="activate"></a><h3><tt>geany.activate ( tab_id )</tt></h3><p>
345 Activates the document specified by <tt><b>tab_id</b></tt>.
346 </p>
347 <p>
348 If <tt><b>tab_id</b></tt> is a number, it activates the document at that index.
349 &nbsp; A <i>positive</i> number refers to the internal document array, and a <i>negative</i>
350 number refers to the (absolute) GtkNotebook index.<br>
351 Note that the indices begin at <tt>(1)</tt> and <tt>(-1)</tt> respectively.
352 </p>
353 <p>
354 If <tt><b>tab_id</b></tt> is a string, the function will try to activate the
355 notebook tab whose filename matches that string.<br>
356 ( The full pathname is required! )
357 </p><p>
358 Returns <tt><b>true</b></tt> on success, or <tt><b>false</b></tt> if the tab could not be found.
359 </p><br><br>
360
361 <a name="appinfo"></a><hr><h3><tt>geany.appinfo ()</tt></h3><p>
362 Returns a Lua table containing information about the currently running Geany instance.<br><br>
363 The <tt>appinfo</tt> table contains the following fields:
364 <br>&nbsp;
365 <table border="0" summary="appinfo table fields">
366 <tr><td width="5%"></td><td><tt>debug</tt></td><td> -- <tt>true</tt> if Geany is running in debug mode.</td></tr>
367 <tr><td width="5%"></td><td><tt>configdir &nbsp; </tt></td><td> -- User's local configuration folder.</td></tr>
368 <tr><td width="5%"></td><td><tt>datadir</tt></td><td> -- System-wide configuration folder.</td></tr>
369 <tr><td width="5%"></td><td><tt>docdir</tt></td><td> -- Location of the Geany help files.</td></tr>
370 <tr><td width="5%"></td><td><tt>scriptdir</tt></td><td> -- Top level folder for GeanyLua scripts.</td></tr>
371 <tr><td width="5%"></td><td><tt>tools</tt></td><td> -- Table of user-configured tools. (see below)</td></tr>
372 <tr><td width="5%"></td><td><tt>template</tt></td><td> -- Table of user's template information. (see below)</td></tr>
373 <tr><td width="5%"></td><td><tt>project</tt></td><td> -- Table of current project information. (see below)</td></tr>
374 </table>
375 <p>
376 &mdash;&mdash;&mdash;&mdash;</p><p>
377 The <tt>tools</tt> sub-table contains the following fields:
378 <br>&nbsp;
379 <table border="0" summary="tools table fields">
380 <tr><td width="15%"></td><td><tt>browser</tt> </td></tr>
381 <tr><td width="15%"></td><td><tt>term</tt> </td><td></tr>
382 <tr><td width="15%"></td><td><tt>print</tt> </td></tr>
383 <tr><td width="15%"></td><td><tt>grep</tt> </td></tr>
384 <tr><td width="15%"></td><td><tt>action</tt> </td></tr>
385 </table>
386 <p>
387 &mdash;&mdash;&mdash;&mdash;</p><p>
388 The <tt>template</tt> sub-table contains the following fields:
389 <br>&nbsp;
390 <table border="0" summary="template fields">
391 <tr><td width="15%"></td><td><tt>developer</tt> </td></tr>
392 <tr><td width="15%"></td><td><tt>company</tt> </td></tr>
393 <tr><td width="15%"></td><td><tt>mail</tt> </td><td></tr>
394 <tr><td width="15%"></td><td><tt>initial</tt> </td></tr>
395 <tr><td width="15%"></td><td><tt>version</tt> </td></tr>
396 </table>
397 <p>
398 &mdash;&mdash;&mdash;&mdash;</p><p>
399 The <tt>project</tt> sub-table *might* contain the following fields:
400 <br>&nbsp;
401 <table border="0" summary="template fields">
402 <tr><td width="15%"></td><td><tt>name</tt> </td><td> -- Name of project.</td></tr>
403 <tr><td width="15%"></td><td><tt>desc</tt> </td><td> -- Project description.</td></tr>
404 <tr><td width="15%"></td><td><tt>file</tt> </td><td> -- Project filename.</td></tr>
405 <tr><td width="15%"></td><td><tt>base</tt> </td><td> -- Base path of project files.</td></tr>
406 <tr><td width="15%"></td><td><tt>mask</tt> </td><td> -- Semicolon-delimited list of filetypes.</td></tr>
407 </table>
408 <p>
409 <b>* Important:</b> The entire <tt>project</tt> sub-table will be <tt>nil</tt> if there is no open project!<br>
410 <br><br>
411
412 <a name="basename"></a><hr><h3><tt>geany.basename ( pathstr )</tt></h3><p>
413 Returns the rightmost filename portion of <tt>pathstr</tt>, with the directory portion removed.
414 </p><br><br>
415
416 <hr><a name="batch"></a><h3><tt>geany.batch ( start )</tt></h3><p>
417 This function marks the beginning or ending of a group of operations<br>
418 that you want the user to be able to undo in a single step.</p>
419 <p>
420 If the <tt><b>start</b></tt> argument is <tt><b>true</b></tt>,
421 it marks the <i>beginning</i> of a group of operations.</p>
422 <p>
423 If the <tt><b>start</b></tt> argument is <tt><b>false</b></tt>,
424 it marks the <i>ending</i> of a group of operations.
425 </p><br><br>
426
427 <hr><a name="byte"></a><h3><tt>geany.byte ( [position] )</tt></h3><p>
428 When called with no arguments, returns the numeric value of the character at
429 the current caret position.</p><p>
430 When called with a numeric <tt><b>position</b></tt> argument, returns the
431 value of the character at that position.
432 </p><br><br>
433
434
435 <hr><a name="caret"></a><h3><tt>geany.caret ( [position] )</tt></h3><p>
436 When called with no arguments, returns the current caret position.</p>
437 <p>
438 When called with a single numeric argument, moves the caret to that position.<br>
439 Out-of-range values are adjusted to the nearest possible position (i.e. the start or end of the document.)
440 </p><br><br>
441
442 <a name="close"></a><hr><h3><tt>geany.close ( [filename]|[index] )</tt></h3>
443 <p>
444 When called with no arguments, closes the currently active document.
445 </p>
446 <p>
447 When called with a numeric argument, closes the file of that document index.
448 </p>
449 <p>
450 When called with a string argument, it will close that named document.
451 </p>
452 <p>
453 If the document has unsaved changes, the user will be prompted to save before closing,<br>
454 and will also be given the option to cancel the operation. &nbsp; To avoid this, you might <br>
455 want to consider using the <tt>geany.save()</tt> function beforehand.
456 </p>
457 <p>
458 Returns <tt><b>true</b></tt> if the document was successfully closed, or <tt><b>false</b></tt> otherwise.</p>
459 <br><br>
460
461 <hr><a name="copy"></a><h3><tt>geany.copy ( [content]|[start,stop] )</tt></h3><p>
462 When called with no arguments, copies the current selection to the clipboard.
463 </p><p>
464 When called with a single string argument, copies the contents of that string to the clipboard.
465 </p>
466 <p>
467 When called with two arguments, copies the portion of the current document's text
468 that lies between the <tt><b>start</b></tt> and <tt><b>stop</b></tt> positions.
469 (Both positions must be positive numbers.)
470 </p>
471 <p>
472 Returns the number of characters copied, or <tt><b>nil</b></tt> if there is no open document.
473 </p>
474 <br><br>
475
476 <hr><a name="count"></a><h3><tt>geany.count ()</tt></h3><p>
477 Returns the number of open documents.
478 </p><br><br>
479
480
481 <hr><a name="cut"></a><h3><tt>geany.cut ()</tt></h3><p>
482 Cuts the current selection to the clipboard.
483 </p>
484 <p>
485 Returns the number of characters cut, or <tt><b>nil</b></tt> if there is no open document.
486 </p><br><br>
487
488
489 <a name="dirlist"></a><hr><h3><tt>geany.dirlist ( path )</tt></h3><p>
490 Returns an iterator function that will be called once for each entry (file or subdirectory) in the specified folder.
491 The iterator produces only the name of each entry, and in no particular order.</p><p>
492 This function will generate an error dialog if the specified folder does not exist or cannot be accessed.
493 </p><br><br>
494
495 <a name="dirname"></a><hr><h3><tt>geany.dirname ( pathstr )</tt></h3><p>
496 Returns the directory portion of <tt>pathstr</tt>, with the rightmost filename portion removed.
497 </p><br><br>
498
499 <hr><a name="documents"></a><h3><tt>geany.documents ( [doc_id] )</tt></h3><p>
500 When called with a numeric argument, returns the full path and filename of <br>
501 the document at the index specified by <tt><b>doc_id</b></tt>.
502 </p>
503 <p>
504 When called with a string argument, returns the numeric index of the document with the<br>
505 path/filename that matches the <tt><b>doc_id</b></tt> string.<br>
506 </p>
507 <p>
508 Either of the two forms above may also return <tt><b>nil</b></tt> if the argument cannot be matched.</p>
509 <p>
510 Note: The <i>index</i> here refers to the editor's internal document array,
511 and might not be <br>
512 the same as the notebook tab index, since the tabs can be re-ordered by the user.
513 </p>
514 <p>
515 <br><br>
516 When called with no arguments, the function returns an iterator to list the full path and filename
517 of each document currently open in the editor.</p><p>
518 For example:</p>
519 <pre>
520
521 for filename in geany.documents()
522 do
523 print(filename)
524 end
525 </pre>
526
527 <br><br>
528
529
530 <a name="filename"></a><hr><h3><tt>geany.filename ()</tt></h3><p>
531 Returns the full path and filename of the current Geany document.</p><p>
532 If there is no open document, or if the current document is untitled, returns <tt><b>nil</b></tt>.
533 </p><br><br>
534
535
536 <a name="fileinfo"></a><hr><h3><tt>geany.fileinfo ()</tt></h3><p>
537 Returns a Lua table containing various information about the current document.<br>
538 If there is no open document, returns <tt><b>nil</b></tt>.
539 </p><p>
540 The returned table contains the following fields:
541 <table border="0" summary="fileinfo fields">
542 <tr><td width="5%"></td><td><tt>name</tt> </td><td> -- The filename, without the path.</td></tr>
543 <tr><td width="5%"></td><td><tt>path</tt> </td><td> -- The full path of the file's directory, including the trailing slash.</td></tr>
544 <tr><td width="5%"></td><td><tt>ext</tt> </td><td> -- The file extension, including the dot, e.g. "<b>.DLL</b>" or "<b>.txt</b>"</td></tr>
545 <tr><td width="5%"></td><td><tt>type</tt> </td><td> -- A one-word description of the filetype, e.g. "<b>C</b>" or "<b>Python</b>".</td></tr>
546 <tr><td width="5%"></td><td><tt>desc</tt> </td><td> -- A longer description of the filetype, e.g. "<b>Lua source file</b>" or "<b>Cascading StyleSheet</b>".</td></tr>
547 <tr><td width="5%"></td><td><tt>comment_single</tt> </td><td> -- The string used for a single-line comment, e.g. "<b class="desc">//</b>".</td></tr>
548 <tr><td width="5%"></td><td><tt>comment_open</tt> </td><td> -- The string used to begin a multi-line comment, e.g. "<b class="desc">&lt;!--</b>".</td></tr>
549 <tr><td width="5%"></td><td><tt>comment_close</tt> </td><td> -- The string used to end a multi-line comment, e.g. "<b class="desc">--&gt;</b>".</td></tr>
550 <tr><td width="5%"></td><td><tt>action</tt> </td><td> -- The action command as executed by the context menu</td></tr>
551 <!--
552 <tr><td width="5%"></td><td><tt>compiler</tt> </td><td> -- The command used to compile this type of file.</td></tr>
553 <tr><td width="5%"></td><td><tt>linker</tt> </td><td> -- The command used to link this type of file.</td></tr>
554 <tr><td width="5%"></td><td><tt>exec</tt> </td><td> -- The primary command used to execute this type of file.</td></tr>
555 <tr><td width="5%"></td><td><tt>exec2</tt> </td><td> -- An alternative command used to execute this type of file.</td></tr>
556 -->
557 <tr><td width="5%"></td><td><tt>ftid</tt> </td><td> -- The unique numeric filetype identifier, as used by Geany.</td></tr>
558 <tr><td width="5%"></td><td><tt>encoding</tt> </td><td> -- The file's in-memory encoding. (may differ from the on-disk encoding.)</td></tr>
559 <tr><td width="5%"></td><td><tt>bom</tt> </td><td> -- <tt><b>true</b></tt> if the file contains a <b>B</b>yte-<b>O</b>rder <b>M</b>arker.</td></tr>
560 <tr><td width="5%"></td><td><tt>changed</tt> </td><td> -- <tt><b>true</b></tt> if the file has unsaved changes.</td></tr>
561 <tr><td width="5%"></td><td><tt>readonly</tt> </td><td> -- <tt><b>true</b></tt> if the in-memory document is tagged as read-only.</td></tr>
562 </table>
563 <br><br>
564
565
566
567 <a name="find"></a><hr><h3><tt>geany.find ( phrase, start, stop, options )</tt></h3><p>
568 Searches within the current document for the string <tt>phrase</tt>, beginning at <br>
569 the numeric <tt>start</tt> position and ending at the <tt>stop</tt> position.<br>
570 ( To search backwards, specify a <tt>start</tt> value greater than <tt>stop</tt> . )<br><br>
571 </p><p>
572
573
574 The <tt>options</tt> argument is a table, each element may be one of the following strings:<br>
575
576 <table border="0" summary="search options">
577 <tr><td width="3%">&nbsp;</td><td width="20%"><tt>
578 "matchcase"</tt></td><td> -- A match only occurs with text that matches the case of the search string.
579 </td></tr>
580 <tr><td>&nbsp;</td><td><tt>
581 "wholeword" </tt> </td><td> -- A match only occurs if the characters before and after are not word characters.
582 </td></tr>
583 <tr><td>&nbsp;</td><td><tt>
584 "wordstart" </tt> </td><td> -- A match only occurs if the character before is not a word character.
585 </td></tr>
586 <tr><td>&nbsp;</td><td><tt>
587 "regexp" </tt> </td><td> -- The search string should be interpreted as a regular expression.
588 </td></tr>
589 <tr><td>&nbsp;</td><td><tt>
590 "posix" </tt> </td><td> -- Use bare parentheses
591 <tt><b>(</b></tt>
592 <tt><b>)</b></tt>
593 for tagged sections rather than the escaped <tt><b>\(</b></tt> and <tt><b>\)</b></tt>.
594 </td></tr>
595 <tr><td colspan="3">
596 ( The empty set <tt><b>{}</b></tt> may also be specified, to search using the default options. )
597 </td></tr>
598 </table>
599 <p>
600 If a match is found, the function returns the starting and ending positions of the match,<br>
601 otherwise it returns <tt><b>nil</b>.</tt>
602 </p><p>
603 For example, to select the first case-sensitive whole-word match of the string
604 &nbsp;'<b>foobar</b>'&nbsp; you could use something like this:</p>
605 <pre>
606 a,b = geany.find( "foobar", 0, geany.length(), {"wholeword","matchcase"} )
607 if (a) then
608 geany.select(a,b)
609 else
610 geany.message("Search phrase not found.")
611 end
612 </pre><br><br>
613
614
615
616 <a name="fullpath"></a><hr><h3><tt>geany.fullpath ( filename )</tt></h3><p>
617 Returns the fully canonicalized form of the path to an <i>existing</i> named file, or <tt>nil</tt> if the path could not be found.
618 </p><br><br>
619
620
621
622
623 <a name="height"></a><hr><h3><tt>geany.height ()</tt></h3><p>
624 Returns the total number of lines in the current document.
625 </p><br><br>
626
627 <a name="keycmd"></a><hr><h3><tt>geany.keycmd ( command )</tt></h3><p>
628 Activates (runs) one of Geany's built-in menu commands.</p><p>
629 The <tt>command</tt> argument should be one the string constants defined in the
630 "<tt>glspi_keycmd.h</tt>" header from the plugin sources. &nbsp;
631 For example, to display Geany's preferences dialog, you could use:</p><p>
632 <tt> &nbsp; geany.keycmd("MENU_PREFERENCES")</tt>
633 </p>
634 <p>
635 This function raises an error if the command argument is invalid.
636 </p><br><br>
637
638
639
640
641
642 <a name="keygrab"></a><hr><h3><tt>geany.keygrab ( [prompt] )</tt></h3>
643
644 <p>Intercepts the next keyboard key pressed, preventing the editor from
645 receiving that keyboard event.</p>
646
647 <p>This function returns the value of the pressed key as a string.
648 Alphanumeric keys will return their keyboard value,
649 such as <tt>"a"</tt> or <tt>"1"</tt>,
650 while other keys may return a string describing the key,
651 such as <tt>"Return"</tt> or <tt>"Escape"</tt>.</p>
652
653 <p>Only one instance of this function may be active at a time.
654 This function will return <tt><b>nil</b></tt> if another instance is already waiting for a keypress.</p>
655
656 <p>If the optional <tt>prompt</tt> string argument is present, its text will be shown
657 in a "calltip" near the upper left-hand area of the current document.
658 The prompt will not be shown if no document is open.</p>
659
660 <p>Notes:
661 <ul>
662 <li>This function should work on non-US keyboards, although this has not been tested.
663 Scripts written for one keyboard may not be portable to other systems.</li>
664 <li>Key combinations with the modifier keys <b>[Ctrl]</b> or <b>[Alt]</b>
665 are not supported.</li>
666 <li>Detection of the <b>[Shift]</b> key state is unreliable.</li>
667 <li>Keys may be dropped when this function is called in rapid succession (as in a loop). For best results, use of this function should be confined to detecting single "lowercase" key presses.</li>
668 <li>Consult <tt>gdk/gdkkeysyms.h</tt> in the GTK sources for an idea of key names.</li>
669 <li>This function was primarily intended for assigning "chained" sets of hot key
670 options, in conjunction with user-defined <a href="geanylua-keys.html">keybindings</a>.</li>
671 </ul>
672 </p>
673 <br><br>
674
675
676
677
678
679 <a name="launch"></a><hr><h3><tt>geany.launch ( program [, arg1 [, arg2, ...]] )</tt></h3><p>
680 Executes the external application specified by &nbsp;<tt>program</tt>,&nbsp;
681 passing any additional arguments to its command line.
682 </p>
683 <p>
684 Returns <tt>true</tt> if the process was succesfully created, else it returns <tt>false</tt> plus an error message.</p>
685 <p>
686 For example:<br><tt>
687 &nbsp; local ok,msg = geany.launch("firefox", "http://www.yahoo.com/")<br>
688 &nbsp; if not ok then geany.message(msg) end</tt>
689 </p>
690 <p>
691 This function returns immediately, regardless of the status of the newly-created process.
692 If you need to wait for a process to complete before returning,
693 use Lua's built-in &nbsp;<tt>os.execute()</tt>&nbsp; function instead.
694 </p>
695 <p>Note that using this function on MS-Windows might require installing the
696 "<b><tt>gspawn-win32-helper.exe</tt></b>" program somewhere in your <tt>PATH</tt>. &nbsp;
697 ( It is included in the GTK/GLib package. )</p>
698 <br><br>
699
700
701 <a name="length"></a><hr><h3><tt>geany.length ()</tt></h3><p>
702 Returns the text length of the current document.
703 </p><br><br>
704
705
706 <a name="lines"></a><hr><h3><tt>geany.lines ( [index] )</tt></h3><p>
707 When called with one argument, returns a string containing the text at
708 the specified line number of the current document.<br>
709 It may also return <tt><b>nil</b></tt> if there is no open document,
710 or if the specified <tt><b>index</b></tt> is outside the range of lines.
711 </p><p>
712 When called without any arguments, it returns an iterator that steps
713 through each line of the current document. <br>
714 So you can use it like this:<pre>
715 for line in geany.lines()
716 do
717 print(line)
718 end
719 </pre>
720 <br><br>
721
722
723 <a name="match"></a><hr><h3><tt>geany.match ( [position] )</tt></h3><p>
724 Attempts to find a corresponding matching brace from the given <tt><b>position</b></tt> of one brace.<br>
725 ( If the <tt><b>position</b></tt> argument is omitted, the current caret position is assumed. )
726 </p>
727 <p>The brace characters handled are: <tt><b>&nbsp; () [] {} &lt;&gt;</b></tt></p>
728 <p> The search is forwards from an opening brace and backwards from a closing brace.<br>
729 If the character at <tt><b>position</b></tt> is not a brace character, or a matching brace cannot be found,<br>
730 the return value is -1. Otherwise, the return value is the position of the matching brace.
731 </p><br><br>
732
733
734
735 <a name="navigate"></a><hr><h3><tt>geany.navigate ( mode, count [,extend [,rect]] )</tt></h3><p>
736 Moves the caret incrementally.</p>
737 <p>
738 The &nbsp;<tt><b>mode</b></tt> &nbsp;argument must be one of the following strings:
739 <ul>
740 <li><tt>"char"</tt> &nbsp; -- Move by characters.</li>
741 <li><tt>"part"</tt> &nbsp; -- Move by segments in <big>MixedCase</big> or <big>under_score</big> style identifiers.</li>
742 <li><tt>"word"</tt> &nbsp; -- Move by words.</li>
743 <li><tt>"edge"</tt> &nbsp; -- Move to beginning or end of current line.</li>
744 <li><tt>"line"</tt> &nbsp; -- Move up or down by lines.</li>
745 <li><tt>"para"</tt> &nbsp; -- Move up or down by paragraphs.</li>
746 <li><tt>"page"</tt> &nbsp; -- Move up or down by pages.</li>
747 <li><tt>"body"</tt> &nbsp; -- Move to the beginning or end of the entire document.</li>
748 </ul>
749 <p>
750 If the numeric <tt><b>count</b></tt> argument is <i>positive</i>, the caret is moved <i>forward</i> or <i>down</i> by that many steps.<br>
751 If it is <i>negative</i>, the caret is moved <i>backward</i> or <i>up</i> by that many steps.<br>
752 ( If it is <i>zero</i> there is not much point in using this function. )<br>
753 There is also no point in using a magnitude greater than <i>one</i> for the <tt>"edge"</tt> or <tt>"body"</tt> modes.
754 </p>
755 <p>
756 If the optional boolean <tt><b>extend</b></tt> argument is <tt><b>true</b></tt>,
757 the selection is expanded or contracted to the new caret position,
758 similar to holding down the&nbsp; <big>[Shift]</big> &nbsp;key when navigating with the keyboard.
759 </p><p>
760 If the optional boolean <tt><b>rect</b></tt> argument is also <tt><b>true</b></tt>,
761 the selection is treated as <i>rectangular</i> rather than <i>linear</i>.<br>
762 ( Rectangular selection is only supported for <tt>char</tt>, <tt>edge</tt>,
763 <tt>line</tt>, or <tt>page</tt> modes. )
764 </p>
765 <br><br>
766
767
768 <a name="newfile"></a><hr><h3><tt>geany.newfile ( [filename [, filetype] )</tt></h3><p>
769 <p>When called with no arguments, creates a new, untitled document.</p>
770 <p>When called with one argument, creates a new document with the specified <tt>filename</tt>.</p>
771 <p>When called with two argument, creates a new document with the specified
772 <tt>filename</tt> and <tt>filetype</tt> (a one-word description of the filetype,
773 e.g. "C" or "Python".). If you want untitled document then set <tt>filename</tt> as <tt>""</tt>.</p>
774 <p>So you can use it like this:</p>
775 <pre>local s = geany.selection();
776
777 if (s ~= "") and (s ~= nil) then
778 local t = geany.fileinfo();
779 geany.newfile("", t.type);
780 geany.selection(s);
781 end</pre>
782 <p>(create a new, untitled document, with selected text and auto set filetype).</p>
783 <br><br>
784
785
786 <a name="open"></a><hr><h3><tt>geany.open ( [filename]|[index] )</tt></h3><p>
787 When called with no arguments, reloads the currently active document from disk.
788 </p><p>
789 When called with a numeric argument, reloads the file of that document index.
790 </p><p>
791 When called with a string argument, it will reload that filename if it is already open,
792 or otherwise it will open it in a new tab. <br>
793 It will not create a non-existent file, for that you need to use <tt>geany.newfile()</tt>
794 </p>
795 <p>
796 Returns the <i>one-based</i> document index on success,
797 or <i>zero</i> if the document could not be opened or reloaded.</p>
798 <br><br>
799
800 <a name="optimize"></a><hr><h3><tt>geany.optimize ()</tt></h3><p>
801 Disables the Lua interpreter's "debug hook", the thing that
802 allows the plugin to track line number information and elapsed time.</p><p>
803 The advantage of calling <tt>optimize()</tt> is that a lengthy, CPU-intensive
804 script can sometimes run much faster.
805 </p><p>
806 The disadvantage is that you lose the line number information that helps in
807 debugging your script, and the built-in protection against things like endless loops.
808 For this reason you should only use this function if you really need it, and
809 only when you are reasonably sure that your script doesn't contain any errors.
810 </p><p>For best results this function should be called at the very
811 beginning of the script.
812
813 </p>
814 <br><br>
815
816 <a name="paste"></a><hr><h3><tt>geany.paste ()</tt></h3><p>
817 Pastes the text from the clipboard into the active document at the current caret position,<br>
818 replacing any current selection.
819 </p><p>
820 Returns <tt><b>nil</b></tt> if there is no open document,
821 or if the document is marked read-only.</p><p>
822 Otherwise it returns the effective change in the document's size. <br>
823 ( Which may actually be negative, if the clipboard content size is less than the prior selection. )
824 </p>
825 <br><br>
826
827
828 <a name="reloadconf"></a><hr><h3><tt>geany.reloadconf ()</tt></h3>
829 <p>This function will cause Geany to reload most of it's configuration files without restarting
830 (as menu item <b><i>Tools-><u>R</u>eload Configuration</i></b>).</p>
831 <!-- The list was copied from https://geanypy.readthedocs.io/en/latest/api.html#geany.reload_configuration -->
832 <p>Currently the following files are reloaded:</p>
833 <ul>
834 <li>all template files;</li>
835 <li>new file templates;</li>
836 <li>the New (with template) menus will be updated;</li>
837 <li>Snippets (snippets.conf);</li>
838 <li>filetype extensions (filetype_extensions.conf);</li>
839 <li><i>setting</i>s and <i>build_settings</i> sections of the filetype definition files.</li>
840 </ul>
841 <p>This function which can be used if you updated one of these configuration files, or modified or added template files.</p>
842 <br><br>
843
844
845 <a name="rescan"></a><hr><h3><tt>geany.rescan ()</tt></h3><p>
846 Scans the scripts folder, rebuilds the <b><i>Tools-><u>L</u>ua Scripts</i></b> menu,
847 and re-initializes the GTK accelerator group (keybindings) associated with the plugin.
848 </p><br><br>
849
850
851 <a name="rowcol"></a><hr><h3><tt>geany.rowcol ( [position]|[line,column] )</tt></h3><p>
852 This function translates between line/column coordinates and linear position (offset from beginning of document).<br>
853 </p>
854 <p>The syntax takes three forms:</p>
855 <ul>
856 <li>
857 With <i>no</i> arguments, it returns the rectangular coordinates of the current caret position:<br>
858 <tt>&nbsp; line, column = geany.rowcol()</tt><br>
859 ( Note that in Lua a single function call like the one above returns both values! )<br><br>
860 </li>
861 <li>
862 With <i>one</i> argument, it it returns the rectangular coordinates of the specified <tt><b>position</b></tt>
863 argument:<br>
864 <tt>&nbsp; line, column = geany.rowcol(position)</tt><br><br>
865 </li>
866
867 <li>
868 With <i>two</i> arguments, it translates from the given <tt><b>line</b></tt> and <tt><b>column</b></tt>
869 to the linear position:<br>
870 <tt>&nbsp; position = geany.rowcol(line,column)</tt>
871 </li>
872 </ul>
873 <p>
874 Out-of-range arguments are adjusted to the nearest valid possibility.
875 </p><br><br>
876
877 <a name="save"></a><hr><h3><tt>geany.save ( [filename]|[index] )</tt></h3><p>
878 When called with no arguments, saves the currently active document to disk.
879 </p><p>
880 When called with a numeric argument, saves the file of that document index.
881 </p><p>
882 When called with a string argument, it will save that named document ( That is, of course, if it is open. )
883 </p>
884 <p>
885 Returns <tt><b>true</b></tt> on success, or <tt><b>false</b></tt> if the document could not be saved.</p>
886 <br><br>
887
888
889 <a name="scintilla"></a><hr><h3><tt>geany.scintilla ( msg_id [, wparam [, lparam]] )</tt></h3><p>
890 <i>Power users only!</i>
891 </p>
892 <p>
893 Sends a <tt><b>SCI_*</b></tt> message directly to the Scintilla widget of the active document.</p>
894 <p>
895 The <tt><b>msg_id</b></tt> can be a numeric value, or a case-insensitive string with or
896 without the <tt>"SCI_"</tt> prefix,
897 such as <tt>"SCI_POSITIONFROMPOINT"</tt>, <tt>"POSITIONFROMPOINT"</tt>, or <tt>"PositionFromPoint"</tt>.
898 </p><p>
899 The wparam, lparam, and return types depend on the particular message, based on the
900 interface described in the &nbsp;"<tt><small>Scintilla.iface</small></tt>"&nbsp; file from the Scintilla sources.
901 </p><p>
902 For API calls which expect a pre-allocated char buffer as the lparam, the allocation is
903 automatically managed
904 by the GeanyLua module, your lparam is ignored, and the return value is a Lua string.&nbsp;
905 In cases where the length is specified
906 in the wparam, the null terminator is not counted - if you ask for 3 chars, you get 3 chars.
907 </p><p>
908 Currently only string, numeric, and boolean types are supported, any API call that
909 expects or returns complex types will result in an error. &nbsp;This function tries hard to
910 protect from garbage being passed to
911 Scintilla, but ultimately <i>you</i> are expected to know what you're doing!
912 </p><br><br>
913
914 <a name="select"></a><hr><h3><tt>geany.select ( [[start,] stop]] )</tt></h3><p>
915 When called with no arguments, returns the beginning <b><i>and</i></b> ending points of
916 the current selection, in the form:<br>
917 <tt>
918 &nbsp; start, stop = geany.select()
919 </tt><br>
920 ( Note that in Lua a single function call like the one above returns both values! )</p>
921 <p>
922 To find out if the selection is rectangular, test the
923 boolean variable <tt><b>geany.rectsel</b></tt> immediately after this call.
924 </p>
925 <p><br>
926 If this function is called with two arguments, it creates a new selection in
927 the current document.
928 <br> The selection is <i>anchored</i> at the <tt><b>start</b></tt>
929 position, and <i>extended</i> to the <tt><b>stop</b></tt> position.</p><p>
930 The boolean variable <tt><b>geany.rectsel</b></tt> can be set prior to this
931 call to control
932 whether this selection is created in normal or rectangular mode.
933 </p>
934 <p><br>
935 If called with one argument, the caret is moved to that position, but no selection is created,<br>
936 and any existing selection is lost.
937 </p>
938 <p>
939 <br>
940 Note that in all cases, the value of <tt><b>stop</b></tt> is considered to be
941 the end of the selection where the caret is located.</p><p>
942 So, if <tt><b>stop</b></tt> is less than <tt><b>start</b></tt>, the caret is postioned
943 at the <i>beginning</i> of the selection, <br>similar to a selection created by
944 dragging the mouse <i>backwards</i> in the document.</p>
945 <p>
946 <b>Hint:</b> To select the entire document, you can use: &nbsp;
947 <tt>geany.select( 0, geany.length() )</tt>
948 </p><br><br>
949
950
951 <a name="selection"></a><hr><h3><tt>geany.selection ( [content] )</tt></h3><p>
952 When called with no arguments, returns the selected text in the current Geany
953 document as a string. <br>
954 Returns the empty string if no text is selected, or <tt><b>nil</b></tt>
955 if there is no open document.
956 </p><p>When called with one argument, the selected text of the current document
957 will be replaced with the specified <tt>content</tt>
958 string.<br>
959 If no text is currently selected, the text will be inserted at the current
960 (caret) position.
961 </p><br><br>
962
963 <a name="settype"></a><hr><h3><tt>geany.settype ( filetype )</tt></h3>
964 <p>Will change the current file type. Use one-word description of the
965 file type, e.g. "C" or "Python" (see the "<tt>filetype_extensions.conf</tt>"
966 file).
967 </p><br><br>
968
969 <a name="signal"></a><hr><h3><tt>geany.signal ( widget, signal )</tt></h3><p>
970 Emits a GTK signal to a given widget in the Geany user interface.</p><p>
971 The <tt>widget</tt> argument is a string identifying the widget by its Glade &nbsp;<tt><b>"id"</b></tt>&nbsp; attribute.<br>
972 The <tt>signal</tt> argument is a string identifying the signal to be emitted.
973 </p><p>
974 This function was primarily intended for activating Geany's builtin menu commands.<br>
975 For instance, to display the file open dialog you could do:<br>
976 <tt> &nbsp; geany.signal("menu_open1", "activate")</tt>
977 </p><p>
978 The function does not return a value, but may trigger an error message if the
979 widget name is not found or the signal name is not valid for the specified widget.
980 &nbsp;
981 Note that it is generally easier and more reliable to use the <tt>keycmd()</tt> function whenever possible.
982 </p><br><br>
983
984 <a name="stat"></a><hr><h3><tt>geany.stat( filename [, lstat] )</tt></h3><p>
985 Returns a table providing some (limited) information about the specified file.<br>
986 If the information could not be obtained, the function returns <tt>nil</tt> plus an string describing the reason for failure.
987 </p>
988 <p>
989 If the file is a symbolic link, and the optional &nbsp;<tt>lstat</tt>&nbsp; argument is <tt>true</tt>, the
990 information is returned about the link itself, otherwise the table provides
991 information about the file that the link points to.
992 </p><p>
993 The returned table contains the following fields:
994 <table border="0" summary="stat table fields">
995 <tr><td width="5%"></td><td><tt>size </tt></td><td> -- The size of the file, in bytes.</td></tr>
996 <tr><td width="5%"></td><td><tt>time </tt></td><td> -- Modification time, in seconds from the epoch.</td></tr>
997 <tr><td width="5%"></td><td><tt>type </tt></td><td> -- A single-character string that denotes the type of file (see below)</td></tr>
998 <tr><td width="5%"></td><td><tt>read </tt></td><td> -- <tt>true</tt> if the effective user can read from the file.</td></tr>
999 <tr><td width="5%"></td><td><tt>write</tt></td><td> -- <tt>true</tt> if the effective user can modify the file.</td></tr>
1000 <tr><td width="5%"></td><td><tt>exec </tt></td><td> -- <tt>true</tt> if the effective user can execute the file.</td></tr>
1001 </table>
1002 <p><br>
1003 The <tt>type</tt> field contains one of the following values:
1004 <table border="0" summary="stat table type field values">
1005 <tr><td width="5%"></td><td><tt>"b" </tt></td><td> -- a block-oriented device.</td></tr>
1006 <tr><td width="5%"></td><td><tt>"c" </tt></td><td> -- a character-special device.</td></tr>
1007 <tr><td width="5%"></td><td><tt>"d" </tt></td><td> -- a directory.</td></tr>
1008 <tr><td width="5%"></td><td><tt>"f" </tt></td><td> -- a FIFO or named pipe.</td></tr>
1009 <tr><td width="5%"></td><td><tt>"l" </tt></td><td> -- a symbolic link.</td></tr>
1010 <tr><td width="5%"></td><td><tt>"r" </tt></td><td> -- a regular file.</td></tr>
1011 <tr><td width="5%"></td><td><tt>"s" </tt></td><td> -- a socket.</td></tr>
1012 </table>
1013 <p>
1014 Note that this function does not support symbolic links or ACL permissions on MS-Windows.
1015 </p><br><br>
1016
1017
1018 <a name="status"></a><hr><h3><tt>geany.status ( message )</tt></h3>
1019 <p>
1020 Sends a message to the status tab of the messages window.
1021 </p><p>
1022 The <tt>message</tt> argument is the string to be displayed.
1023 </p><p>
1024 This function's purpose is to provide a user-friendly way to display messages without using the dialog popup.
1025 </p><p>
1026 This function does not return a value.</p><br><br>
1027
1028
1029 <a name="text"></a><hr><h3><tt>geany.text ( [content] )</tt></h3><p>
1030 When called with no arguments, returns the entire text of the currently
1031 active Geany document as a string.<br>( Returns <tt><b>nil</b></tt>
1032 if there is no open document.)
1033 </p><p>
1034 When called with one argument, the entire text of the current
1035 document is replaced with the specified <tt>content</tt> string.
1036 </p><br><br>
1037
1038
1039 <a name="timeout"></a><hr><h3><tt>geany.timeout ( seconds )</tt></h3><p>
1040
1041 Attempts to control the maximum time allowed, in whole seconds, for the current script to
1042 finish execution.</p><p>
1043 By default, scripts are allowed 15 seconds to complete, but if your script needs
1044 more time, you can increase it here.
1045 </p><p>
1046 Note that the interpreter is only able to trigger this "timeout exceeded" error when it is actually processing instructions.
1047 This provides protection against things like accidentally creating an endless loop,
1048 but it might still be possible to create a script that hangs indefinitely. ( For instance if
1049 you call <tt>io.read()</tt> without access to a terminal. )</p><p>
1050 The internal timer is paused whenever one of the dialog box functions is called,
1051 to allow the user time to respond.
1052 </p><p>
1053 Setting the timeout to zero will disable it completely, that is, the script will never time out.
1054 </p><p><br><br>
1055
1056 <a name="wkdir"></a><hr><h3><tt>geany.wkdir ( [folder] )</tt></h3><p>
1057 When called with no arguments, returns the current working directory.</p>
1058 <p>
1059 When called with one argument, tries to change into that <tt>folder</tt>,
1060 and returns <tt>true</tt> on sucess, or <tt>false</tt> plus an error message
1061 on failure.
1062 </p><br><br>
1063
1064 <a name="word"></a><hr><h3><tt>geany.word ( [position] )</tt></h3><p>
1065 When called with no arguments, returns the word at the current caret position.
1066 </p><p>
1067 When called with one argument, returns the word at the specified
1068 <tt><b>position</b></tt>.
1069 </p><p>
1070 This function can return an empty string if the position is not touching
1071 a character that is considered to be part of a word. You can modify this
1072 set of characters in the <tt><b>geany.wordchars</b></tt> variable.
1073 </p><br><br>
1074
1075
1076 <a name="xsel"></a><hr><h3><tt>geany.xsel ( [text] )</tt></h3><p>
1077 When called with no arguments, returns the text-based contents of the primary X selection.
1078 </p><p>
1079 When called with one argument, assigns that <tt>text</tt> as the contents of the primary X selection.
1080
1081 </p><p>
1082 This function is only valid for X-Window environments, on MS-Windows, it does nothing.
1083 </p><br><br>
1084
1085 <a name="yield"></a><hr><h3><tt>geany.yield ()</tt></h3><p>
1086 Temporarily returns control to the IDE, to allow user interface elements to
1087 be refreshed/repainted during lengthy script operations.
1088 </p><p>Since most scripts will probably have a run time of less than a couple of seconds,
1089 you will likely never need this function. But if you do, it should be used with caution,
1090 since it allows Geany's state to be changed during script execution. This could have
1091 unpleasant consequences, for instance if the user closes a document that the script is referencing.
1092 </p>
1093 <br><br>
1094 <br><br>
1095 <hr><hr>
1096
1097 <!-- Dialog functions -->
1098 <h3>&nbsp; &nbsp; &nbsp; Dialog functions</h3>
1099 <hr>
1100
1101 <a name="choose"></a><hr><h3><tt>geany.choose ( prompt, items )</tt></h3><p>
1102 Displays a dialog box to allow the user to choose from a list of items. </p><p>
1103 The <tt>prompt</tt> argument string will display a message above the list box
1104 to explain the request.</p><p>
1105 The <tt>items</tt> argument is a Lua table, each element of the table must be
1106 a string.
1107 </p><p>
1108 The function returns the selected item as a string:</p>
1109 <ul>
1110 <li>If the <b>OK</b> button is clicked,
1111 <li>If the [Return] key is pressed while the item list is active.
1112 <li>If the user double-clicks an item in the list.
1113 </ul>
1114 <p>
1115 If the <b>Cancel</b> button is clicked, or if the dialog is is dismissed by
1116 some other means, e.g. by pressing the [Escape] key, the function returns
1117 <tt><b>nil</b></tt>.
1118 </p><br><br>
1119
1120
1121 <a name="confirm"></a><hr><h3><tt>geany.confirm ( title, question, default )</tt></h3><p>
1122 Displays a simple yes-or-no style dialog box to ask the specified
1123 <tt>question</tt>.<br>
1124 The <tt>title</tt> argument is displayed as a bold-faced title for the dialog.
1125 </p><p>
1126 Returns <tt><b>true</b></tt> if the 'Yes' button is clicked,
1127 or <tt><b>false</b></tt> if the 'No' button is
1128 clicked.</p><p>
1129 If the dialog is dismissed by some other means, e.g. by pressing the
1130 [Escape] key, <br>the function will return the boolean value specified by the
1131 <tt>default</tt> argument. </p>
1132 <p>All three arguments are required, but you can pass <tt><b>nil</b></tt>
1133 as the first argument to suppress the title.
1134 </p><br><br>
1135
1136
1137 <a name="input"></a><hr><h3><tt>geany.input ( [prompt] [,default] )</tt></h3><p>
1138 Displays an input dialog to prompt the user for some text. </p><p>
1139 The <tt>prompt</tt> argument string will display a message above the entry box
1140 to explain what input is requested.</p><p>
1141 The <tt>default</tt> argument string, if present, will add some pre-selected
1142 text into the entry area.</p><p>
1143 If the <b>OK</b> button is clicked, or if the [Return] key is pressed while the
1144 entry field is active, the function will return the contents of the entry field
1145 as a string.</p><p>
1146 If the <b>Cancel</b> button is clicked, or if the dialog is is dismissed by
1147 some other means, e.g. by pressing the
1148 [Escape] key, the function returns <tt><b>nil</b></tt>.
1149 </p><br><br>
1150
1151
1152 <a name="message"></a><hr><h3><tt>geany.message ( [title,] message )</tt></h3><p>
1153 When called with one argument, displays a simple dialog box containing
1154 the specified <tt>message</tt> string. </p>
1155 <p>When called with two arguments, the <tt>title</tt> argument is displayed as
1156 a bold-faced title,
1157 and the <tt>message</tt> argument will be the message text.
1158 </p><br><br>
1159 <hr>
1160
1161 <a name="pickfile"></a><hr><h3><tt>geany.pickfile ( [mode [,path [,filter]]] )</tt></h3>
1162 <p>
1163 Displays a dialog that allows the user to select a filename.</p><p>
1164 All three arguments are optional, but you can pass <tt>nil</tt> as a placeholder to
1165 use the default value for any of the arguments.</p><p>
1166 The <tt>mode</tt> argument specifies the type of dialog, and must be one
1167 of two strings, either <tt>"open"</tt> or <tt>"save"</tt>.<br>
1168 ( passing <tt>nil</tt> is the same as <tt>"open"</tt> )<br>
1169 In <tt>"save"</tt> mode the function will issue an overwrite confirmation prompt if the targeted file already exists.
1170 </p><p>
1171 The <tt>path</tt> string argument sets the initial directory for the dialog, or <tt>nil</tt>
1172 to use the current directory.<br>
1173 If the last (rightmost) element of the path is an existing directory, the path will be used as-is,
1174 otherwise the last element is assumed to be a filename (whether it actually exists on disk or not)
1175 and will be parsed off and used as the suggested filename for the dialog.
1176 </p><p>
1177 The <tt>filter</tt> argument controls which files are displayed,
1178 or it can be <tt>nil</tt> to display all files.<br>
1179 It is a string consisting of pairs of substrings, where each substring
1180 is separated by the pipe "<tt>|</tt>" symbol.<br>
1181 The first element in each pair of substrings is the human-readable description of the filetype,<br>
1182 and the second element of the
1183 pair is a set of semicolon-delimited shell wildcards to filter on.<br>
1184 For instance, a filter for web files might look like:<br>
1185 <tt><b> &nbsp; "HTML files|*.html;*.htm|PHP files|*.php;*.php4|Style sheets|*.css"</b></tt>
1186 <br>
1187 ( Those familiar with
1188 <a href="http://en.wikipedia.org/wiki/Borland_Delphi">Borland Delphi</a>
1189 might recognize this syntax from the
1190 <a href="http://www.delphibasics.co.uk/RTL.asp?Name=TOpenDialog">TOpenDialog.Filter</a> property. )
1191 </p>
1192 <p><br>
1193 Note that this function does not actually open or save anything, it merely returns the
1194 full path and filename of the selected file, or <tt>nil</tt> if the user cancels the dialog.</p>
1195 <br><br>
1196 <hr>
1197 <hr>
1198 <h3>Module level variables</h3>
1199 <hr>
1200 <a name="wordchars"></a><hr><h3><tt>geany.wordchars</tt></h3><p>
1201 This variable determines which characters are considered to be part of a word.
1202 </p><p>
1203 It is used by the <tt><b>geany.word()</b></tt> function and may also be reset by that
1204 function if its current value cannot be interpreted as a string.</p><p>
1205 The default value is:<br><tt>
1206 &nbsp; &nbsp; <big> <big>
1207 "_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"</big> </big></tt>
1208 <p>
1209 If you need to modify this string, you may want to save a copy of the original
1210 so you can restore it later.
1211 </p><br><br>
1212
1213 <a name="rectsel"></a><hr><h3><tt>geany.rectsel</tt></h3><p>
1214 This variable controls and/or returns the "selection mode" of the current document.
1215 </p><p>
1216 It is used by the <tt><b>geany.select()</b></tt> function and is adjusted
1217 when the selection is queried, and examined when the selection is set. <br>
1218 It may also be reset if its current value cannot be interpreted as a boolean.</p>
1219 <p>
1220 A value of <tt><b>true</b></tt> represents a rectangular selection
1221 and <tt><b>false</b></tt> represents the normal linear selection mode.
1222 </p><br><br>
1223
1224 <a name="banner"></a><hr><h3><tt>geany.banner</tt></h3><p>
1225 This variable controls the window title for dialogs displayed by the current script.
1226 </p><p>
1227 It may be reset by the dialog functions if its value cannot be interpreted as a string.
1228 </p><br><br>
1229
1230
1231 <a name="caller"></a><hr><h3><tt>geany.caller</tt></h3><p>
1232 This variable stores the internal index of the document that triggered one of the <a href="./geanylua-intro.html#events">event scripts</a>.</p>
1233 <p>
1234 For example, to print the filename of a file that has just been saved, you could put<br>
1235 this line in your <b>~/.geany/plugins/lua/events/saved.lua</b> script file:</p><p>
1236 <tt>&nbsp; print(geany.documents(geany.caller))</tt>
1237 </p><p>
1238
1239
1240
1241
1242 This variable is only relevant for the opened, created, activated, and saved event scripts,
1243 for all other scripts it is set to zero.<br>
1244
1245 </p><br><br>
1246
1247 <a name="dirsep"></a><hr><h3><tt>geany.dirsep</tt></h3><p>
1248 This variable returns the default filesystem path separator.<br>
1249 ( A forward slash <tt><b>/</b></tt> for Unix or
1250 a backslash <tt><b>\</b></tt> for MS-Windows. )
1251 </p><br><br>
1252
1253
1254 <a name="project"></a><hr><h3><tt>geany.project</tt></h3><p>
1255 This variable provides a reference to the <a href="geanylua-keyfile.html">GKeyFile</a> object
1256 for the project that triggered a
1257 &nbsp;proj-*&nbsp; <a href="./geanylua-intro.html#events">event script</a>.</p>
1258 <p>
1259 The information stored in the object can be manipulated using the <tt>keyfile</tt> module.<br>
1260 For example, to print the description of the project that has just been opened, you could put<br>
1261 this line in your <b>~/.geany/plugins/lua/events/proj-opened.lua</b> script file:</p><p>
1262 <tt>&nbsp; print(keyfile.value(geany.project, "project", "description"))</tt>
1263 </p><p>
1264 This variable is only relevant for the project-based event scripts, for all other scripts it is set to <tt>nil</tt>.<br>
1265
1266 </p><br><br>
1267
1268
1269 <a name="script"></a><hr><h3><tt>geany.script</tt></h3><p>
1270 This variable stores the full path and filename of the active script.</p>
1271 <br><br>
1272 <hr>
1273 <br><br>
1274 <div align="right"><small>&copy; 2007-2008 <i>Jeff Pohlmeyer </i> &nbsp; </small></div>
1275 <br><br>
1276 <br><br><br><br>
1277 <br><br><br><br>
1278 <br><br><br><br>
1279 <br><br><br><br>
1280
1281 </body>
1282 </html>