|
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 - - - |