[[!meta title="Documentation for Lua module for MCabber"]]

[[!toc]]

- - -

<a name="Lua.for.mcabber"></a>

## Lua for mcabber

Module provides embedded lua environment with some accessors to

mcabber functionality.

<a name="Options"></a>

### Options

* lua_init_filename - lua script, that will be loaded at startup

* lua_lm_debug      - if lm log handler is enabled, this option controls, whether lm log messages are dropped or passed to mcabber logging facility

<a name="Provided.lua.functions"></a>

### Provided lua functions

<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.message.type"></a>

### log message type  

**Values:**  normal, log, debug, notutf8  

<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 message type](#log.message.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.  

<a name="completion.sorting.order"></a>

### completion sorting order

Sorting order for completion category.  

**Values:**  sort, direct, reverse, append, prepend  

<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), argument enum value ([completion sorting order](#completion.sorting.order), 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.run"></a>

### main.hook_run

Runs handlers for given hook with supplied arguments.  

**Arguments:** string (hook name), table (hook arguments)    

**Return values:** [return enum field](#return.enum.field) ([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="Utility.Lua.Routines"></a>

## Utility Lua Routines

To handle conversion of enums and flag fields to/from human-readable strings.

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