# HG changeset patch # User Myhailo Danylenko # Date 1345552339 -10800 # Node ID ea30cf6c5bea2c40f7f31eadfc89539141acf165 # Parent 8692a6fbe415ab58b28d12a23517522488cd293f Rearrange documentation diff -r 8692a6fbe415 -r ea30cf6c5bea CMakeLists.txt --- a/CMakeLists.txt Tue Aug 21 15:29:27 2012 +0300 +++ b/CMakeLists.txt Tue Aug 21 15:32:19 2012 +0300 @@ -59,6 +59,8 @@ if(DOCGEN_EXECUTABLE) add_custom_command(OUTPUT ${lua_BINARY_DIR}/lua.html COMMAND ${DOCGEN_EXECUTABLE} -f html -t "Documentation for Lua module for MCabber" -o ${lua_BINARY_DIR}/lua.html -- ${lua_SOURCES} DEPENDS ${DOCGEN_EXECUTABLE} ${lua_SOURCES} WORKING_DIRECTORY ${lua_SOURCE_DIR}) add_custom_target(doc ALL DEPENDS ${lua_BINARY_DIR}/lua.html) + add_custom_command(OUTPUT ${lua_SOURCE_DIR}/docs/api.mdwn COMMAND ${DOCGEN_EXECUTABLE} -f mdwn -t "Documentation for Lua module for MCabber" -o ${lua_SOURCE_DIR}/docs/api.mdwn -- ${lua_SOURCES} DEPENDS ${DOCGEN_EXECUTABLE} ${lua_SOURCES} WORKING_DIRECTORY ${lua_SOURCE_DIR}) + add_custom_target(update_api DEPENDS ${lua_SOURCE_DIR}/docs/api.mdwn) endif() ## Packaging information @@ -97,7 +99,7 @@ install(FILES ${lua_BINARY_DIR}/lua.html DESTINATION share/doc/${CPACK_PACKAGE_NAME}) endif() install(DIRECTORY examples DESTINATION share/doc/${CPACK_PACKAGE_NAME} PATTERN "*~" EXCLUDE) -install(FILES README TODO COPYING DESTINATION share/doc/${CPACK_PACKAGE_NAME}) +install(FILES docs/readme.mdwn docs/todo.mdwn COPYING DESTINATION share/doc/${CPACK_PACKAGE_NAME}) install(DIRECTORY help DESTINATION share/mcabber) install(FILES ${PROJECT_BINARY_DIR}/lua.avv DESTINATION share/mcabber/avv/modules RENAME lua) diff -r 8692a6fbe415 -r ea30cf6c5bea README --- a/README Tue Aug 21 15:29:27 2012 +0300 +++ b/README Tue Aug 21 15:32:19 2012 +0300 @@ -1,32 +1,1 @@ - -This is a lua 5.1 module for mcabber. - -See examples/README for information, how to get example -scripts working with this module. - -To install it, you will need: -- lua 5.1 -- glib -- mcabber -- cmake -- perl (optional) - -Then do -$ mkdir build -$ cd build -$ cmake .. -$ make edit_cache -$ make -# make install - -Debian users can instead of make install do -$ fakeroot make package -# dpkg -i libmcabber-lua*.deb - -This code underlies terms of GNU GPL v2 or later. - -I willi be happy to get feedback, patches, suggestions, etc. -You can send me email or contact via jabber . - - -- Myhailo Danylenko - +docs/readme.mdwn \ No newline at end of file diff -r 8692a6fbe415 -r ea30cf6c5bea TODO --- a/TODO Tue Aug 21 15:29:27 2012 +0300 +++ b/TODO Tue Aug 21 15:32:19 2012 +0300 @@ -1,30 +1,1 @@ - -finish roster list information -non-setting settings? -mcabber_config_file use option to set dir? -do uninitialization of commands and features with objects? -help system accessors (needs major rewrite and planning) -object access to roster and buddies? -in mcabber add hook/call to also handle room status changes -well, so, mcabber will pass all arguments to hooks in utf. but do we really need to convert names to utf? -use glib filename charset conversion functions? -toggle routine should handle multiple status toggles -think about how tune notification should act on start/quit -clarify situation with disco, maybe it is due to this we are unable to receive pep events -lm debug should be more flexible -common pubsub infrastructure, in particular, xmlns-based event handlers? -forms abandoning hook to inform server -eliminate main.parse_args? -common disco routines should get connection object from outer space - no mcabber dependency, the same for forms parsing, pep sending (though it anyway needs to be converted to pubsub)... -tune should set self-song only on reply from server -test node config -publish library handlers? -check all that callbacks for empty 'to' fields in print_info -reply routine? -put here mcabber headers snapshot -put here mcabber-modules patch -change module name to just lua? -go through TODO and remove done :/ -update build system -check for resource freeing on unloading - +docs/todo.mdwn \ No newline at end of file diff -r 8692a6fbe415 -r ea30cf6c5bea docs/api.mdwn --- /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]] + + +- - - + + +## print +Prints its arguments to log with default priority. +**Arguments:** something, ... + + +### dopath +Loads lua file from default location. +XXX: g_filename_from_utf8? +**Arguments:** string (filename, without ".lua") +**Return values:** string (error message, optional) + + +### yes or no ansvers +**Values:** 1, 0, enable, disable, true, false, on, off, yes, no + + +### 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 + + +### main.version +Returns information about mcabber version +**Return values:** table + + +### log print type +**Values:** normal, log, debug, notutf0 + + +### roster type +**Values:** user, group, agent, room, special + + +### 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... + + +### 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) + + +### 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) + + +### 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) + + +### main.fileoption +Gets option, expanding it as filename. +**Arguments:** string (option name) +**Return values:** string (expanded option value) or nil + + +### 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 + + +### main.print_info +Prints a system message to buddy's window. +**Arguments:** string (jid), string (message) + + +### main.beep +Beeps with system speaker. + + +### main.run +Runs specified mcabber command. +**Arguments:** string + + +### main.status +Returns your current status. +**Return values:** string (status letter), string (status message) + + +### main.roster +Returns array of jids of buddies in roster. +**Return values:** table + + +### 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) + + +### 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) + + +### 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. + + +### 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 + + +### main.add_feature +Adds xmlns to disco#info features list. +**Arguments:** string (xmlns) + + +### main.del_feature +Removes xmlns from disco#info features list. +**Arguments:** stirng (xmlns) + + +### event context +Enum, indicating what exactly caused [event function](#event.function) firing. +**Values:** timeout, cancel, reject, accept + + +### 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) + + +### 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) + + +### 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 + + +### 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. + + +### 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) + + +### main.parse_args +Function to parse command argument string to [command arguments table](#command.arguments.table). +**Arguments:** string +**Return values:** table + + +### 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 + + +### main.del_category +Removes completion category. +**Arguments:** integer (category id) + + +### main.add_completion +Adds word to a completion list. +**Arguments:** integer (completion group id), string (word) + + +### main.del_completion +Removes word from a completion list. +**Arguments:** integer (completion group id), string (word) + + +### 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) + + +### command:del +Unregisters given command from mcabber. Object will be destroyed later. + + +### timer function +Function, that will be called periodically until it returns false. +**Return values:** boolean + + +### main.timer +Creates new [timer function](#timer.function), that will be called periodically. +**Arguments:** integer (interval, seconds), [timer function](#timer.function) + + +### 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) + + +### main.bgread +Runs specified command and passes its output to a given function. +**Arguments:** string (command), [background reading function](#background.reading.function) + + +### hook handler result +What to do with hook processing afterwards +**Values:** proceed, stop, drop + + +### hook handler priority +Feel free to specify just a number instead of some preset value. +**Values:** high, default, idle-high, idle, low + + +### 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) + + +### 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) + + +### hook:del +Unregisters given hook handler from mcabber. Object will be destroyed later. + + +### 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) + + +### main.add_guard +Installs option guard for given option. +**Arguments:** string ( option name ), [guard function](#guard.function) +**Return values:** boolean ( success ) + + +### 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 ) + +- - - + +- - - + + +## 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. + + +### return enum field +String. If no string found, plain number will be returned. + + +### 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. + + +### 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 diff -r 8692a6fbe415 -r ea30cf6c5bea docs/index.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/index.mdwn Tue Aug 21 15:32:19 2012 +0300 @@ -0,0 +1,9 @@ + +[[!meta title="mcabber-lua"]] + +# Lua scripting for MCabber + +Module provides embedded lua interpreter and functions to +manipulate MCabber from it. + +[ [[!hg mcabber-lua desc="SOURCE"]] ] [ [[README|readme]] ] [ [[TODO|todo]] ] [ [[API|api]] ] [ [[RC|lua.rc]] ] diff -r 8692a6fbe415 -r ea30cf6c5bea docs/lua.rc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/lua.rc Tue Aug 21 15:32:19 2012 +0300 @@ -0,0 +1,11 @@ + +# initialization file to load at module loading time +#set lua_init_filename = ~/.mcabber/mcabberrc.lua + +# enable lua-loudmouth debug output to be shown in log +#set lua_lm_debug = 1 + +# here go any options, used by your scripts + +module load lua + diff -r 8692a6fbe415 -r ea30cf6c5bea docs/readme.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/readme.mdwn Tue Aug 21 15:32:19 2012 +0300 @@ -0,0 +1,57 @@ + +# Lua scripting for MCabber + +This module creates lua interpreter environment and puts some lua +functions in it to interact with mcabber. Module provides command 'lua' +to run lua expressions in that environment. + +Lua interface is available in api reference, built with 'docgen' help. +It is also available online. + +In 'examples' dir there are some example scripts, that may be used as +is or for reference. See also 'README' in 'examples' dir. + +# Installation + +To install it, you need: + + * mcabber headers + * liblua + * glib + * gmodule + * docgen (optional, for documentation) + * cmake + * make + * c compiler (gcc) + * linker (binutils) + +Then do: + + $ mkdir build + $ cd build + $ cmake .. + $ make edit_cache + $ make + # make install + +Debian users can instead of make install do: + + $ make package + # dpkg -i libmcabber-lua_*.deb + +Users of other distributions can select appropriate package generator, +using cache editor. + +# License + +This code underlies terms of GNU GPL v2 or later. You can find it in +file COPYING from this distribution or on a GNU web-site +. + +# Contact + +I will be happy to get feedback, patches, suggestions, etc. +You can send me email or contact via jabber . + + -- Myhailo Danylenko + diff -r 8692a6fbe415 -r ea30cf6c5bea docs/todo.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/todo.mdwn Tue Aug 21 15:32:19 2012 +0300 @@ -0,0 +1,30 @@ + +* finish roster list information +* non-setting settings? +* mcabber_config_file use option to set dir? +* do uninitialization of commands and features with objects? +* help system accessors (needs major rewrite and planning) +* object access to roster and buddies? +* in mcabber add hook/call to also handle room status changes +* well, so, mcabber will pass all arguments to hooks in utf. but do we really need to convert names to utf? +* use glib filename charset conversion functions? +* toggle routine should handle multiple status toggles +* think about how tune notification should act on start/quit +* clarify situation with disco, maybe it is due to this we are unable to receive pep events +* lm debug should be more flexible +* common pubsub infrastructure, in particular, xmlns-based event handlers? +* forms abandoning hook to inform server +* eliminate main.parse_args? +* common disco routines should get connection object from outer space - no mcabber dependency, the same for forms parsing, pep sending (though it anyway needs to be converted to pubsub)... +* tune should set self-song only on reply from server +* test node config +* publish library handlers? +* check all that callbacks for empty 'to' fields in print_info +* reply routine? +* put here mcabber headers snapshot +* put here mcabber-modules patch +* change module name to just lua? +* go through TODO and remove done :/ +* update build system +* check for resource freeing on unloading + diff -r 8692a6fbe415 -r ea30cf6c5bea examples/lua.rc --- a/examples/lua.rc Tue Aug 21 15:29:27 2012 +0300 +++ b/examples/lua.rc Tue Aug 21 15:32:19 2012 +0300 @@ -2,12 +2,6 @@ # initialization file to load set lua_init_filename = ~/.mcabber/mcabberrc.lua -# lua function name to be called on hooks invocation -set lua_hook_function = hook_handler - -# enable lua-loudmouth debug output to be shown in log -set lua_lm_debug = 1 - # show notifications for pep events set lua_pep_notification = enable