--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/api.mdwn Tue Aug 21 15:32:19 2012 +0300
@@ -0,0 +1,331 @@
+
+[[!meta title="Documentation for Lua module for MCabber"]]
+
+[[!toc]]
+
+
+- - -
+
+<a name="print"></a>
+## print
+Prints its arguments to log with default priority.
+**Arguments:** something, ...
+
+<a name="dopath"></a>
+### dopath
+Loads lua file from default location.
+XXX: g_filename_from_utf8?
+**Arguments:** string (filename, without ".lua")
+**Return values:** string (error message, optional)
+
+<a name="yes.or.no.ansvers"></a>
+### yes or no ansvers
+**Values:** 1, 0, enable, disable, true, false, on, off, yes, no
+
+<a name="main.yesno"></a>
+### main.yesno
+According to [yes or no ansvers](#yes.or.no.ansvers) returns true or false.
+If ansver is not recognized, returns nil.
+**Arguments:** anything (string expected)
+**Return values:** boolean or nil
+
+<a name="main.version"></a>
+### main.version
+Returns information about mcabber version
+**Return values:** table
+
+<a name="log.print.type"></a>
+### log print type
+**Values:** normal, log, debug, notutf0
+
+<a name="roster.type"></a>
+### roster type
+**Values:** user, group, agent, room, special
+
+<a name="main.log"></a>
+### main.log
+Prints message to log.
+Note: most likely you need notutf8 flag enabled.
+**Arguments:** [log [print](#print) type](#log.[print](#print).type), message, message...
+
+<a name="main.option"></a>
+### main.option
+Sets or gets value of mcabber option.
+You can specify nil as a value to delete option.
+If you omit option name, it returns hash table of all options.
+**Arguments:** string (option name, optional), string (value, optional)
+**Return values:** string (value, optional)
+
+<a name="main.alias"></a>
+### main.alias
+Sets or gets alias.
+You can specify nil as a command to delete alias.
+If you omit alias name, it will return hash table of all aliases.
+**Arguments:** string (alias name, optional), string (command, optional)
+**Return values:** string (command, optional)
+
+<a name="main.bind"></a>
+### main.bind
+Sets or gets binding.
+You can specify nil as a command to unbind key.
+If you omit keycode, it will return hash table of all bindings.
+**Arguments:** string (keycode, optional), string (command, optional)
+**Return values:** string (command, optional)
+
+<a name="main.fileoption"></a>
+### main.fileoption
+Gets option, expanding it as filename.
+**Arguments:** string (option name)
+**Return values:** string (expanded option value) or nil
+
+<a name="main.connection"></a>
+### main.connection
+Returns lightuserdata of mcabber's loudmouth connection.
+This can be very useful with lua-loudmouth, and not much otherwise.
+**Return values:** lightuserdata or nil
+
+<a name="main.print.info"></a>
+### main.print_info
+Prints a system message to buddy's window.
+**Arguments:** string (jid), string (message)
+
+<a name="main.beep"></a>
+### main.beep
+Beeps with system speaker.
+
+<a name="main.run"></a>
+### main.run
+Runs specified mcabber command.
+**Arguments:** string
+
+<a name="main.status"></a>
+### main.status
+Returns your current status.
+**Return values:** string (status letter), string (status message)
+
+<a name="main.roster"></a>
+### main.roster
+Returns array of jids of buddies in roster.
+**Return values:** table
+
+<a name="main.current.buddy"></a>
+### main.current_buddy
+Returns jid of current selected buddy or sets current buddy to buddy with specified jid.
+**Arguments:** string (optional)
+**Return values:** string (optional)
+
+<a name="main.full.jid"></a>
+### main.full_jid
+Returns full jid (with current resource) of specified buddy (or current, if not specified).
+Note, that if there are no resources online, it will return just what it got.
+**Arguments:** string (jid, optional)
+**Return values:** string (jid)
+
+<a name="resources.table"></a>
+### resources table
+Hash table with resource name as keys and another hash tables as values.
+Inner tables contain resource-specific information: priority, status and message.
+
+<a name="main.buddy.info"></a>
+### main.buddy_info
+Returns a hash table with information on specified buddy.
+Table contains fields type, name, onserver and resources (which points to [resources table](#resources.table)).
+**Arguments:** string (jid)
+**Return values:** table
+
+<a name="main.add.feature"></a>
+### main.add_feature
+Adds xmlns to disco#info features list.
+**Arguments:** string (xmlns)
+
+<a name="main.del.feature"></a>
+### main.del_feature
+Removes xmlns from disco#info features list.
+**Arguments:** stirng (xmlns)
+
+<a name="event.context"></a>
+### event context
+Enum, indicating what exactly caused [event function](#event.function) firing.
+**Values:** timeout, cancel, reject, accept
+
+<a name="event.function"></a>
+### event function
+Function to be called, when some event state change occurs
+**Arguments:** [event context](#event.context), string (event args)
+**Return values:** boolean (if event shoud be preserved)
+
+<a name="main.event"></a>
+### main.event
+Creates new event. If called without arguments, returns event id list.
+**Arguments:** [event function](#event.function) (optional), string (event id), string (description, optional), integer (expiration timeout, optional)
+**Return values:** string (event id) or nothing (creation error) or table (list of event names)
+
+<a name="completion.type"></a>
+### completion type
+Built-it completion types can be specified as string, instead of id.
+**Values:** cmd, jid, urljid, name, status, filename, roster, buffer, group, groupname, multiline, room, resource, auth, request, events, eventsid, pgp, color, otr, ortpolicy, yesno
+
+<a name="command.arguments.table"></a>
+### command arguments table
+It can parse barewords (with escapes), double-quoted strings (with escapes), single-quoted strings (without escapes), options and arguments.
+Arguments are separated only by whitespace, so, consequential quoted strings or barewords are one argument.
+This strings are equal:
+
+* ab\ cd\'e\\f\"
+* "ab cd'e\\f\""
+* 'ab cd'\''e\f"'
+* ab" cd'"'e\f"'
+
+Returned table have option names as keys, option values as values, and arguments as sequential members. -- option is supported.
+Example: "-t jid -m 9 -- -aa bb cc" will result in { t = 'jid', m = 9, '-aa', 'bb', 'cc' }
+Implementation notes:
+
+* All options should be before any arguments. First non-option argument disables options recognizing.
+* 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.
+* Escape character just before EOL is preserved.
+
+<a name="command.function"></a>
+### command function
+Function to handle newly registered command.
+Argument type passed depends on how command is registered.
+**Arguments:** string (arguments) or [command arguments table](#command.arguments.table)
+
+<a name="main.parse.args"></a>
+### main.parse_args
+Function to parse command argument string to [command arguments table](#command.arguments.table).
+**Arguments:** string
+**Return values:** table
+
+<a name="main.add.category"></a>
+### main.add_category
+Adds completion category.
+**Arguments:** table (values are used as words for completion, optional)
+**Return values:** integer (category id, in fact [completion type](#completion.type)) or nil
+
+<a name="main.del.category"></a>
+### main.del_category
+Removes completion category.
+**Arguments:** integer (category id)
+
+<a name="main.add.completion"></a>
+### main.add_completion
+Adds word to a completion list.
+**Arguments:** integer (completion group id), string (word)
+
+<a name="main.del.completion"></a>
+### main.del_completion
+Removes word from a completion list.
+**Arguments:** integer (completion group id), string (word)
+
+<a name="main.command"></a>
+### main.command
+Associates mcabber command name and lua function.
+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.
+Note, that for now there are no way to unregister completion group, so, resources can be exausted easily.
+Also note, that it ignores keys in a completion table.
+**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)
+**Return values:** userdata (command object)
+
+<a name="command:del"></a>
+### command:del
+Unregisters given command from mcabber. Object will be destroyed later.
+
+<a name="timer.function"></a>
+### timer function
+Function, that will be called periodically until it returns false.
+**Return values:** boolean
+
+<a name="main.timer"></a>
+### main.timer
+Creates new [timer function](#timer.function), that will be called periodically.
+**Arguments:** integer (interval, seconds), [timer function](#timer.function)
+
+<a name="background.reading.function"></a>
+### background reading function
+Function, that processes output from pipe in asynchronous way.
+**Arguments:** string (data) or nil (eof)
+**Return values:** boolean (false if reading should be terminated)
+
+<a name="main.bgread"></a>
+### main.bgread
+Runs specified command and passes its output to a given function.
+**Arguments:** string (command), [background reading function](#background.reading.function)
+
+<a name="hook.handler.result"></a>
+### hook handler result
+What to do with hook processing afterwards
+**Values:** proceed, stop, drop
+
+<a name="hook.handler.priority"></a>
+### hook handler priority
+Feel free to specify just a number instead of some preset value.
+**Values:** high, default, idle-high, idle, low
+
+<a name="hook.function"></a>
+### hook function
+Function to be called, when hook will be processsed.
+XXX: we can provide object as argument, but is this necessary?
+**Arguments:** table (arguments hash)
+**Return values:** [hook handler result](#hook.handler.result)
+
+<a name="main.hook"></a>
+### main.hook
+Installs hook handler, returns an object, that you need to keep until
+hook handling is no more needed.
+**Arguments:** string (hook name), [hook function](#hook.function), integer (priority, optional)
+**Return values:** userdata (hook object)
+
+<a name="hook:del"></a>
+### hook:del
+Unregisters given hook handler from mcabber. Object will be destroyed later.
+
+<a name="guard.function"></a>
+### guard function
+Function to be called, when option changes it's value.
+Old option value is still accessible through [main.option](#main.option).
+**Arguments:** string (key), string (new value)
+**Return values:** string (value to save in hash table)
+
+<a name="main.add.guard"></a>
+### main.add_guard
+Installs option guard for given option.
+**Arguments:** string ( option name ), [guard function](#guard.function)
+**Return values:** boolean ( success )
+
+<a name="main.del.guard"></a>
+### main.del_guard
+Removes option guard from given option.
+By default, lua will refuse to remove guards, not installed
+by lua. Still, you can force guard removal.
+**Arguments:** string ( option name ), boolean ( force removal )
+**Return values:** boolean ( success )
+
+- - -
+
+- - -
+
+<a name="argument.enum.field"></a>
+## argument enum field
+String that will be converted to number or just plain number, that will be passed as is.
+Note, that if enum name is not recognized no error will be raised and default vale will be used.
+
+<a name="return.enum.field"></a>
+### return enum field
+String. If no string found, plain number will be returned.
+
+<a name="argument.flags.field"></a>
+### argument flags field
+Can be just plain number, then it is passed as is.
+Can be a string, then it is recognized as a single enabled flag.
+Or can be a table of the following format:
+
+* integer keys should have string values, that will be used as enabled flag names or numerical values, that will be just ORed;
+* string keys should be flag names, that will be enabled, if corresponding value contains true value.
+
+<a name="returned.flags.field"></a>
+### returned flags field
+Is always a table with present flag names as keys with true values.
+Not present flags are not present in table either.
+Not recognized values, if present, will be stored as a number in a first sequential table member (table[1]).
+
+- - -
\ No newline at end of file