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