[[!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: <https://bitbucket.org/georgri/mcabber-modules/>
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: <http://isbear.org.ua/hg/isbear/mcabber-avatar/>
* Homepage: <http://isbear.org.ua/docs/mcabber-avatar/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-avatar/>
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: <http://isbear.org.ua/hg/isbear/mcabber-avv/>
* Homepage: <http://isbear.org.ua/docs/mcabber-avv/index/>
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: <http://mcabber.com/hg/>
Simple module to beep on **all** messages. Available in mcabber 0.10.0. Serves the
purpose of example for module writing HOWTO.
## clock
* URL: <http://hg.lilotux.net/mcabber-modules/>
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: <http://isbear.org.ua/hg/isbear/mcabber-cmd/>
* Homepage: <http://isbear.org.ua/docs/mcabber-cmd/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-cmd/>
Provides command `/cmd`, that sends output of specified shell command to current buddy.
## commands (custom)
* URL: <https://github.com/hirthwork/mcabber-commands/>
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: <http://hg.lilotux.net/mcabber-modules/>
Trivial module; adds a command `#` to ignore a line. This module is part of the
mcabber-modules repository.
## disco
* URL: <http://isbear.org.ua/hg/isbear/mcabber-disco/>
* Homepage: <http://isbear.org.ua/docs/mcabber-disco/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-disco/>
Module adds `/disco` command, that sends service discovery requests.
## env
* URL: <http://isbear.org.ua/hg/isbear/mcabber-env/>
* Homepage: <http://isbear.org.ua/docs/mcabber-env/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-env/>
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: <http://isbear.org.ua/hg/isbear/mcabber-patches/>
* Homepage: <http://isbear.org.ua/docs/mcabber-patches/index/>
* Mirror: <http://hg.lilotux.net/mcabber-experimental/>
Modularization of legacy mcabber eventcmd script. Available in experimental
version of mcabber.
## eventcmd-ng
* URL: <http://isbear.org.ua/hg/isbear/mcabber-eventcmd-ng/>
* Homepage: <http://isbear.org.ua/docs/mcabber-eventcmd-ng/index/>
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: <http://hg.lilotux.net/mcabber-modules/>
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: <http://hg.lilotux.net/mcabber-modules/>
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: <http://www.freakysoft.de/repos/mcabber-modules/>
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: <https://github.com/alkino/mcabber-jingle>
* HG Mirror: <http://hg.lilotux.net/mod-mcabber-jingle/>
Jingle modules written by Alkino during the GSoC 2010. Contains a file transfer
module (IBB support).
## killpresence
* URL: <http://hg.lilotux.net/mcabber-modules/>
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: <http://hg.lilotux.net/mcabber-modules/>
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: <http://isbear.org.ua/hg/isbear/mcabber-lua/>
* Homepage: <http://isbear.org.ua/docs/mcabber-lua/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-lua/>
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: <http://isbear.org.ua/hg/isbear/lua-lm/>
* Homepage: <http://isbear.org.ua/docs/lua-lm/index/>
* Mirror: <http://hg.lilotux.net/lua-lm/>
## marking
* URL: <http://isbear.org.ua/hg/isbear/mcabber-marking/>
* Homepage: <http://isbear.org.ua/docs/mcabber-marking/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-marking/>
Adds ability to mark several buddies and do some command for each of these
buddies. Provides commands `/mark` and `/marked`.
## mpd
* URL: <http://isbear.org.ua/hg/isbear/mcabber-mpd/>
* Homepage: <http://isbear.org.ua/docs/mcabber-mpd/index/>
Provides information about currently playing song for modules like PEP.
## mucignore
* URL: <https://github.com/hirthwork/mcabber-mucignore/>
Simple plugin to ignore users in MUC conferences.
## pep
* URL: <http://isbear.org.ua/hg/isbear/mcabber-pep/>
* Homepage: <http://isbear.org.ua/docs/mcabber-pep/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-pep/>
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: <http://isbear.org.ua/hg/isbear/mcabber-templatecmd/>
* Homepage: <http://isbear.org.ua/docs/mcabber-templatecmd/index/>
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 <filename_here> .` - this module is for you.
## uptime
* URL: <http://isbear.org.ua/hg/isbear/mcabber-uptime/>
* Homepage: <http://isbear.org.ua/docs/mcabber-uptime/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-uptime/>
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: <http://isbear.org.ua/hg/isbear/mcabber-urlopen/>
* Homepage: <http://isbear.org.ua/docs/mcabber-urlopen/index/>
Looks for urls in incoming messages and prints them to log and/or calls shell
command to handle them.
## xttitle
* URL: <http://mcabber.com/hg/>
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: <http://isbear.org.ua/hg/isbear/mcabber-yaubil/>
* Homepage: <http://isbear.org.ua/docs/mcabber-yaubil/index/>
* Mirror: <http://hg.lilotux.net/mod-mcabber-yaubil/>
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
`<install prefix>/share/doc/libmcabber-<modulename>/`), 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