129
|
1 |
|
|
2 |
[[!meta title="Documentation for Lua module for MCabber"]] |
|
3 |
|
|
4 |
[[!toc]] |
|
5 |
|
|
6 |
|
|
7 |
- - - |
|
8 |
|
|
9 |
<a name="print"></a> |
|
10 |
## print |
|
11 |
Prints its arguments to log with default priority. |
|
12 |
**Arguments:** something, ... |
|
13 |
|
|
14 |
<a name="dopath"></a> |
|
15 |
### dopath |
|
16 |
Loads lua file from default location. |
|
17 |
XXX: g_filename_from_utf8? |
|
18 |
**Arguments:** string (filename, without ".lua") |
|
19 |
**Return values:** string (error message, optional) |
|
20 |
|
|
21 |
<a name="yes.or.no.ansvers"></a> |
|
22 |
### yes or no ansvers |
|
23 |
**Values:** 1, 0, enable, disable, true, false, on, off, yes, no |
|
24 |
|
|
25 |
<a name="main.yesno"></a> |
|
26 |
### main.yesno |
|
27 |
According to [yes or no ansvers](#yes.or.no.ansvers) returns true or false. |
|
28 |
If ansver is not recognized, returns nil. |
|
29 |
**Arguments:** anything (string expected) |
|
30 |
**Return values:** boolean or nil |
|
31 |
|
|
32 |
<a name="main.version"></a> |
|
33 |
### main.version |
|
34 |
Returns information about mcabber version |
|
35 |
**Return values:** table |
|
36 |
|
|
37 |
<a name="log.print.type"></a> |
|
38 |
### log print type |
|
39 |
**Values:** normal, log, debug, notutf0 |
|
40 |
|
|
41 |
<a name="roster.type"></a> |
|
42 |
### roster type |
|
43 |
**Values:** user, group, agent, room, special |
|
44 |
|
|
45 |
<a name="main.log"></a> |
|
46 |
### main.log |
|
47 |
Prints message to log. |
|
48 |
Note: most likely you need notutf8 flag enabled. |
|
49 |
**Arguments:** [log [print](#print) type](#log.[print](#print).type), message, message... |
|
50 |
|
|
51 |
<a name="main.option"></a> |
|
52 |
### main.option |
|
53 |
Sets or gets value of mcabber option. |
|
54 |
You can specify nil as a value to delete option. |
|
55 |
If you omit option name, it returns hash table of all options. |
|
56 |
**Arguments:** string (option name, optional), string (value, optional) |
|
57 |
**Return values:** string (value, optional) |
|
58 |
|
|
59 |
<a name="main.alias"></a> |
|
60 |
### main.alias |
|
61 |
Sets or gets alias. |
|
62 |
You can specify nil as a command to delete alias. |
|
63 |
If you omit alias name, it will return hash table of all aliases. |
|
64 |
**Arguments:** string (alias name, optional), string (command, optional) |
|
65 |
**Return values:** string (command, optional) |
|
66 |
|
|
67 |
<a name="main.bind"></a> |
|
68 |
### main.bind |
|
69 |
Sets or gets binding. |
|
70 |
You can specify nil as a command to unbind key. |
|
71 |
If you omit keycode, it will return hash table of all bindings. |
|
72 |
**Arguments:** string (keycode, optional), string (command, optional) |
|
73 |
**Return values:** string (command, optional) |
|
74 |
|
|
75 |
<a name="main.fileoption"></a> |
|
76 |
### main.fileoption |
|
77 |
Gets option, expanding it as filename. |
|
78 |
**Arguments:** string (option name) |
|
79 |
**Return values:** string (expanded option value) or nil |
|
80 |
|
|
81 |
<a name="main.connection"></a> |
|
82 |
### main.connection |
|
83 |
Returns lightuserdata of mcabber's loudmouth connection. |
|
84 |
This can be very useful with lua-loudmouth, and not much otherwise. |
|
85 |
**Return values:** lightuserdata or nil |
|
86 |
|
|
87 |
<a name="main.print.info"></a> |
|
88 |
### main.print_info |
|
89 |
Prints a system message to buddy's window. |
|
90 |
**Arguments:** string (jid), string (message) |
|
91 |
|
|
92 |
<a name="main.beep"></a> |
|
93 |
### main.beep |
|
94 |
Beeps with system speaker. |
|
95 |
|
|
96 |
<a name="main.run"></a> |
|
97 |
### main.run |
|
98 |
Runs specified mcabber command. |
|
99 |
**Arguments:** string |
|
100 |
|
|
101 |
<a name="main.status"></a> |
|
102 |
### main.status |
|
103 |
Returns your current status. |
|
104 |
**Return values:** string (status letter), string (status message) |
|
105 |
|
|
106 |
<a name="main.roster"></a> |
|
107 |
### main.roster |
|
108 |
Returns array of jids of buddies in roster. |
|
109 |
**Return values:** table |
|
110 |
|
|
111 |
<a name="main.current.buddy"></a> |
|
112 |
### main.current_buddy |
|
113 |
Returns jid of current selected buddy or sets current buddy to buddy with specified jid. |
|
114 |
**Arguments:** string (optional) |
|
115 |
**Return values:** string (optional) |
|
116 |
|
|
117 |
<a name="main.full.jid"></a> |
|
118 |
### main.full_jid |
|
119 |
Returns full jid (with current resource) of specified buddy (or current, if not specified). |
|
120 |
Note, that if there are no resources online, it will return just what it got. |
|
121 |
**Arguments:** string (jid, optional) |
|
122 |
**Return values:** string (jid) |
|
123 |
|
|
124 |
<a name="resources.table"></a> |
|
125 |
### resources table |
|
126 |
Hash table with resource name as keys and another hash tables as values. |
|
127 |
Inner tables contain resource-specific information: priority, status and message. |
|
128 |
|
|
129 |
<a name="main.buddy.info"></a> |
|
130 |
### main.buddy_info |
|
131 |
Returns a hash table with information on specified buddy. |
|
132 |
Table contains fields type, name, onserver and resources (which points to [resources table](#resources.table)). |
|
133 |
**Arguments:** string (jid) |
|
134 |
**Return values:** table |
|
135 |
|
|
136 |
<a name="main.add.feature"></a> |
|
137 |
### main.add_feature |
|
138 |
Adds xmlns to disco#info features list. |
|
139 |
**Arguments:** string (xmlns) |
|
140 |
|
|
141 |
<a name="main.del.feature"></a> |
|
142 |
### main.del_feature |
|
143 |
Removes xmlns from disco#info features list. |
|
144 |
**Arguments:** stirng (xmlns) |
|
145 |
|
|
146 |
<a name="event.context"></a> |
|
147 |
### event context |
|
148 |
Enum, indicating what exactly caused [event function](#event.function) firing. |
|
149 |
**Values:** timeout, cancel, reject, accept |
|
150 |
|
|
151 |
<a name="event.function"></a> |
|
152 |
### event function |
|
153 |
Function to be called, when some event state change occurs |
|
154 |
**Arguments:** [event context](#event.context), string (event args) |
|
155 |
**Return values:** boolean (if event shoud be preserved) |
|
156 |
|
|
157 |
<a name="main.event"></a> |
|
158 |
### main.event |
|
159 |
Creates new event. If called without arguments, returns event id list. |
|
160 |
**Arguments:** [event function](#event.function) (optional), string (event id), string (description, optional), integer (expiration timeout, optional) |
|
161 |
**Return values:** string (event id) or nothing (creation error) or table (list of event names) |
|
162 |
|
|
163 |
<a name="completion.type"></a> |
|
164 |
### completion type |
|
165 |
Built-it completion types can be specified as string, instead of id. |
|
166 |
**Values:** cmd, jid, urljid, name, status, filename, roster, buffer, group, groupname, multiline, room, resource, auth, request, events, eventsid, pgp, color, otr, ortpolicy, yesno |
|
167 |
|
|
168 |
<a name="command.arguments.table"></a> |
|
169 |
### command arguments table |
|
170 |
It can parse barewords (with escapes), double-quoted strings (with escapes), single-quoted strings (without escapes), options and arguments. |
|
171 |
Arguments are separated only by whitespace, so, consequential quoted strings or barewords are one argument. |
|
172 |
This strings are equal: |
|
173 |
|
|
174 |
* ab\ cd\'e\\f\" |
|
175 |
* "ab cd'e\\f\"" |
|
176 |
* 'ab cd'\''e\f"' |
|
177 |
* ab" cd'"'e\f"' |
|
178 |
|
|
179 |
Returned table have option names as keys, option values as values, and arguments as sequential members. -- option is supported. |
|
180 |
Example: "-t jid -m 9 -- -aa bb cc" will result in { t = 'jid', m = 9, '-aa', 'bb', 'cc' } |
|
181 |
Implementation notes: |
|
182 |
|
|
183 |
* All options should be before any arguments. First non-option argument disables options recognizing. |
|
184 |
* EOL is a cutting edge, that can cut much earlier, than you expect. Non-closed quoted strings lose leading quote and option without value loses its leading minus. |
|
185 |
* Escape character just before EOL is preserved. |
|
186 |
|
|
187 |
<a name="command.function"></a> |
|
188 |
### command function |
|
189 |
Function to handle newly registered command. |
|
190 |
Argument type passed depends on how command is registered. |
|
191 |
**Arguments:** string (arguments) or [command arguments table](#command.arguments.table) |
|
192 |
|
|
193 |
<a name="main.parse.args"></a> |
|
194 |
### main.parse_args |
|
195 |
Function to parse command argument string to [command arguments table](#command.arguments.table). |
|
196 |
**Arguments:** string |
|
197 |
**Return values:** table |
|
198 |
|
|
199 |
<a name="main.add.category"></a> |
|
200 |
### main.add_category |
|
201 |
Adds completion category. |
|
202 |
**Arguments:** table (values are used as words for completion, optional) |
|
203 |
**Return values:** integer (category id, in fact [completion type](#completion.type)) or nil |
|
204 |
|
|
205 |
<a name="main.del.category"></a> |
|
206 |
### main.del_category |
|
207 |
Removes completion category. |
|
208 |
**Arguments:** integer (category id) |
|
209 |
|
|
210 |
<a name="main.add.completion"></a> |
|
211 |
### main.add_completion |
|
212 |
Adds word to a completion list. |
|
213 |
**Arguments:** integer (completion group id), string (word) |
|
214 |
|
|
215 |
<a name="main.del.completion"></a> |
|
216 |
### main.del_completion |
|
217 |
Removes word from a completion list. |
|
218 |
**Arguments:** integer (completion group id), string (word) |
|
219 |
|
|
220 |
<a name="main.command"></a> |
|
221 |
### main.command |
|
222 |
Associates mcabber command name and lua function. |
|
223 |
As a completion you can also specify a string name (see [completion type](#completion.type)) instead of table, for non-builtin, you can just pass integer id. |
|
224 |
Note, that for now there are no way to unregister completion group, so, resources can be exausted easily. |
|
225 |
Also note, that it ignores keys in a completion table. |
|
226 |
**Arguments:** string (command name), [command function](#command.function), boolean (parse args flag, optional), table (completions, optional)/[completion type](#completion.type) (or integer comletion group id, optional) |
|
227 |
**Return values:** userdata (command object) |
|
228 |
|
|
229 |
<a name="command:del"></a> |
|
230 |
### command:del |
|
231 |
Unregisters given command from mcabber. Object will be destroyed later. |
|
232 |
|
|
233 |
<a name="timer.function"></a> |
|
234 |
### timer function |
|
235 |
Function, that will be called periodically until it returns false. |
|
236 |
**Return values:** boolean |
|
237 |
|
|
238 |
<a name="main.timer"></a> |
|
239 |
### main.timer |
|
240 |
Creates new [timer function](#timer.function), that will be called periodically. |
|
241 |
**Arguments:** integer (interval, seconds), [timer function](#timer.function) |
|
242 |
|
|
243 |
<a name="background.reading.function"></a> |
|
244 |
### background reading function |
|
245 |
Function, that processes output from pipe in asynchronous way. |
|
246 |
**Arguments:** string (data) or nil (eof) |
|
247 |
**Return values:** boolean (false if reading should be terminated) |
|
248 |
|
|
249 |
<a name="main.bgread"></a> |
|
250 |
### main.bgread |
|
251 |
Runs specified command and passes its output to a given function. |
|
252 |
**Arguments:** string (command), [background reading function](#background.reading.function) |
|
253 |
|
|
254 |
<a name="hook.handler.result"></a> |
|
255 |
### hook handler result |
|
256 |
What to do with hook processing afterwards |
|
257 |
**Values:** proceed, stop, drop |
|
258 |
|
|
259 |
<a name="hook.handler.priority"></a> |
|
260 |
### hook handler priority |
|
261 |
Feel free to specify just a number instead of some preset value. |
|
262 |
**Values:** high, default, idle-high, idle, low |
|
263 |
|
|
264 |
<a name="hook.function"></a> |
|
265 |
### hook function |
|
266 |
Function to be called, when hook will be processsed. |
|
267 |
XXX: we can provide object as argument, but is this necessary? |
|
268 |
**Arguments:** table (arguments hash) |
|
269 |
**Return values:** [hook handler result](#hook.handler.result) |
|
270 |
|
|
271 |
<a name="main.hook"></a> |
|
272 |
### main.hook |
|
273 |
Installs hook handler, returns an object, that you need to keep until |
|
274 |
hook handling is no more needed. |
|
275 |
**Arguments:** string (hook name), [hook function](#hook.function), integer (priority, optional) |
|
276 |
**Return values:** userdata (hook object) |
|
277 |
|
|
278 |
<a name="hook:del"></a> |
|
279 |
### hook:del |
|
280 |
Unregisters given hook handler from mcabber. Object will be destroyed later. |
|
281 |
|
|
282 |
<a name="guard.function"></a> |
|
283 |
### guard function |
|
284 |
Function to be called, when option changes it's value. |
|
285 |
Old option value is still accessible through [main.option](#main.option). |
|
286 |
**Arguments:** string (key), string (new value) |
|
287 |
**Return values:** string (value to save in hash table) |
|
288 |
|
|
289 |
<a name="main.add.guard"></a> |
|
290 |
### main.add_guard |
|
291 |
Installs option guard for given option. |
|
292 |
**Arguments:** string ( option name ), [guard function](#guard.function) |
|
293 |
**Return values:** boolean ( success ) |
|
294 |
|
|
295 |
<a name="main.del.guard"></a> |
|
296 |
### main.del_guard |
|
297 |
Removes option guard from given option. |
|
298 |
By default, lua will refuse to remove guards, not installed |
|
299 |
by lua. Still, you can force guard removal. |
|
300 |
**Arguments:** string ( option name ), boolean ( force removal ) |
|
301 |
**Return values:** boolean ( success ) |
|
302 |
|
|
303 |
- - - |
|
304 |
|
|
305 |
- - - |
|
306 |
|
|
307 |
<a name="argument.enum.field"></a> |
|
308 |
## argument enum field |
|
309 |
String that will be converted to number or just plain number, that will be passed as is. |
|
310 |
Note, that if enum name is not recognized no error will be raised and default vale will be used. |
|
311 |
|
|
312 |
<a name="return.enum.field"></a> |
|
313 |
### return enum field |
|
314 |
String. If no string found, plain number will be returned. |
|
315 |
|
|
316 |
<a name="argument.flags.field"></a> |
|
317 |
### argument flags field |
|
318 |
Can be just plain number, then it is passed as is. |
|
319 |
Can be a string, then it is recognized as a single enabled flag. |
|
320 |
Or can be a table of the following format: |
|
321 |
|
|
322 |
* integer keys should have string values, that will be used as enabled flag names or numerical values, that will be just ORed; |
|
323 |
* string keys should be flag names, that will be enabled, if corresponding value contains true value. |
|
324 |
|
|
325 |
<a name="returned.flags.field"></a> |
|
326 |
### returned flags field |
|
327 |
Is always a table with present flag names as keys with true values. |
|
328 |
Not present flags are not present in table either. |
|
329 |
Not recognized values, if present, will be stored as a number in a first sequential table member (table[1]). |
|
330 |
|
|
331 |
- - - |