diff -r eff7327bcabe -r 1e57279b82b1 Modules.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Modules.mdwn Sun May 14 20:58:00 2017 +0300 @@ -0,0 +1,334 @@ + +[[!toc levels=2]] + +# Overview + +Starting from version 0.10.0, mcabber supports dynamic loading of modules. It +introduces the command `/module` with subcommands to load, unload and obtain +info on modules. This command is allowed during initialization time, so you can +specify it in your mcabberrc. Modules are searched in the directory specified in +mcabber variable `modules_dir`, that you should set before issuing these +commands. Default module installation/loading directory is `/usr/lib/mcabber`. + +The API is still experimental and likely to be changed, but there is a short +HOWTO about writing your own modules in `doc/` subdirectory of mcabber source. +It contains up-to-date information on module-related routines that mcabber +offers and some examples. + +# Existing modules + +Right now the following modules are available (if you know of some other +modules, feel free to add them to list below): + +## antispam + +* URL: + +Enables simple question-based antispam-bot which asks predefined question to +every unsubscribed buddy, expecting them to give the right predefined answer. +Currently you may change the standard question/answer only by changing the +source code. + +## avatar + +* URL: +* Homepage: +* Mirror: + +This module implements avatar publishing/retrieving via pep/pubsub. It informs +you when your buddies publish their avatars via pep and provides command +`/avatar` to publish your own. But this is not all: It also will actually show +you buddy's avatar! Yes, it is aalib :) + +Note: this module should eventually merge with pep (at least partially) + +## avv + +* URL: +* Homepage: + +Advanced version verification (or something like that, I now cannot recollect +initial meaning of this abbreviature). Alternative module loading system, that +allows flexible module compatibility determination. It splits API, provided by +mcabber into a set of smaller APIs. This allows to omit module update, when +major API change have not changed used by this module mini-APIs. Also, module +information is now stored separately, in usual text file, that may be adapted by +hand to user environment. Fallback legacy module loading scheme is not yet +implemented :( + +## beep + +* URL: + +Simple module to beep on **all** messages. Available in mcabber 0.10.0. Serves the +purpose of example for module writing HOWTO. + +## clock + +* URL: + +This module uses the 'info' option to display the date and time in the status +bar. This module is part of the mcabber-modules repository. + +## cmd + +* URL: +* Homepage: +* Mirror: + +Provides command `/cmd`, that sends output of specified shell command to current buddy. + +## commands (custom) + +* URL: + +Allows to add commands with dynamic completion lists, based on regexp-matching +over incoming buddy messages (a bit similar to urlopen). Useful for +microblogging. + +## comment + +* URL: + +Trivial module; adds a command `#` to ignore a line. This module is part of the +mcabber-modules repository. + +## disco + +* URL: +* Homepage: +* Mirror: + +Module adds `/disco` command, that sends service discovery requests. + +## env + +* URL: +* Homepage: +* Mirror: + +Tampering with mcabber's environment. This module can be useful for development +and debugging, as well as for on-the-fly changing of some parameters, like +`AAOPTS` for aalib, used in avatar module. Also provides way to change current +working directory. + +## eventcmd + +* URL: +* Homepage: +* Mirror: + +Modularization of legacy mcabber eventcmd script. Available in experimental +version of mcabber. + +## eventcmd-ng + +* URL: +* Homepage: + +Another approach for eventcmd. It passes arguments to script as environment +variables, so, you can use `$jid` instead of `$1`. Because of this it is more +flexible for future changes (see hooks description in HOWTO). Though, it is not +officially approved new interface for eventcmd - it is only my vision of it. + +## extsay + +* URL: + +If you use the [screen][] utility, this module will let you open your editor in +a new screen window, and will send the message once you exit the editor. Check +the [README][extsay-readme] file! This module is part of the mcabber-modules +repository. + +## fifo + +Modularization of mcabber FIFO. Allows recreation of fifo in run-time by +reloading module. This module has been merged into mcabber development tree +(0.10.2-dev). + +## info_msgcount + +* URL: + +Displays the number of unread messages (buffers) in the status bar. This module +relies on the `info` option, so it cannot be used with the clock module +described above. This module is part of the mcabber-modules repository. + +## ignore_auth + +* URL: + +Ignores subscription requests from every jid matching configurable regexs. Adds +the command ignore_auth to add a regex to the list (`/ignore_auth .*@icq`). The +option ignore_auth can be used to disable/enable this feature temporily +(`/set ignore_auth = 1`). This module is part of the forked mcabber-modules +repository from franky. + +## jingle + +* URL: +* HG Mirror: + +Jingle modules written by Alkino during the GSoC 2010. Contains a file transfer +module (IBB support). + +## killpresence + +* URL: + +Adds two commands, killpresence and killchatstates, that can be used repectively +to ignore the current presence from a fulljid (e.g. to kill a "ghost") and to +reset the chat state status of an online contact. This module is part of the +mcabber-modules repository. + +## lastmsg + +* URL: + +Stores highlighted messages received in MUC rooms while you are away. When +you're back, you can use the command `/lastmsg` you display them. This module is +part of the mcabber-modules repository. + +## lua + +* URL: +* Homepage: +* Mirror: + +Lua interface module for mcabber. Adds `/lua` command (and much more in example +scripts). Needs much more work, but already usable. + +Example scripts for this module extensively use lua bindings for loudmouth, +`lua-lm`. It can be found here: + +* URL: +* Homepage: +* Mirror: + +## marking + +* URL: +* Homepage: +* Mirror: + +Adds ability to mark several buddies and do some command for each of these +buddies. Provides commands `/mark` and `/marked`. + +## mpd + +* URL: +* Homepage: + +Provides information about currently playing song for modules like PEP. + +## mucignore + +* URL: + +Simple plugin to ignore users in MUC conferences. + +## pep + +* URL: +* Homepage: +* Mirror: + +Suite of modules to publish and process PEP (Personal Eventing Protocol) tune, +mood, geoloc and activity events. + +## si + +Stream initiation (file transfer profile) module. Uses streams module for its +transfer methods, thus, it now supports both IBB and SOCKS5 Bytestreams. +Provides command `/si`. + +**Note:** Stalled in the process of rewrite/update, contact +[me](xmpp:isbear@jabber.kiev.ua), if you are interested in picking it up. + +## streams + +In-Band and SOCKS5 Bytestreams implementation. Adds command `/stream`. It +supports IBB native session initiation and bare SCOKS5 Bytestream requests and +can send/receive files this way. Though, this module is, probably, the only +implementation, that supports such file transfer methods, so you will be unable +to use this module alone to exchange files with, other clients. However this +module is designed with ability to be used by other modules as transfer pipe, +so, there is si/file-transfer module to transfer files in more convenient way. +This module should be considered still in beta stage, but yet already usable. + +**Note:** Stalled in the process of rewrite/update, contact +[me](xmpp:isbear@jabber.kiev.ua), if you are interested in picking it up. + +## templatecmd + +* URL: +* Homepage: + +Allows to define alias-like commands with shell-like positional arguments +substitution. Provides command `/templatecmd`. If you're searching for a way to +define alias for `/send_to -f .` - this module is for you. + +## uptime + +* URL: +* Homepage: +* Mirror: + +Module to show mcabber uptime. It can either determine full mcabber process +uptime from linux `/proc` filesystem or just count time from module loading +moment. + +## urlopen + +* URL: +* Homepage: + +Looks for urls in incoming messages and prints them to log and/or calls shell +command to handle them. + +## xttitle + +* URL: + +Displays the number of unread messages in the X Terminal Title. The option +`xttitle_short_format` can be set to use a very short title. + +## yaubil + +* URL: +* Homepage: +* Mirror: + +Yet Another Useless Built-In Language. Provides `/eval`, `/if`, `/then`, +`/else`, `/let` and `/multi` commands. Probably most useful amongst them is +`/multi`. If, breaking my expectations, this module becomes useful and famous +(presence of beard may cause this), I promise, that I'll improve +string/parentheses parsing, add loops and maybe even switch to tree-producing +parser with operators precedence. + +# Notes on modules, written by isbear, aka Mykhailo Danylenko + +* I use cmake as build system, it allows me to quickly generate debian packages + (not too accurate, but at least it is package). See README for a brief + description how to build module. +* Most modules need more work - to add flexibility, providing mcabber variables, + that control module behaviour, to check for resource releasing in extreme + situations, etc. +* Most modules, that provide some command also include help file for them (in + English). You may need to adjust variable help_dirs, if you have installed + module with another prefix than mcabber itself to be able to use this help + files. +* Every module contains file modulename.rc (by default it will be installed into + `/share/doc/libmcabber-/`), that contains list of + all mcabber variables introduced by this module with descriptions and load + commands, necessary to get this module loaded (i.e. first load commands for + modules, that are required for this module to work, then load command for this + module itself). +* If you have found a bug in module, please contact me by mail or jabber (both + can be found in README file). +* Unfortunately, most of the modules are now kinda unmaintained (if you need + something - ping me, and I'll try to do something about that, but no + guarantees). Adoption requests are warmly welcomed. + +[screen]: http://www.gnu.org/software/screen/ +[extsay-readme]: http://hg.lilotux.net/mcabber-modules/raw-file/tip/extsay-ng/README