xK/xB.adoc

xB(1)
=====
:doctype: manpage
:manmanual: uirc3 Manual
:mansource: uirc3 {release-version}

Name
----
xB - modular IRC bot

Synopsis
--------
*xB* [_OPTION_]...

Description
-----------
*xB* is a modular IRC bot with a programming language-agnostic plugin
architecture based on co-processes.

Options
-------
*-d*, *--debug*::
	Print more information to help debug various issues.

*-h*, *--help*::
	Display a help message and exit.

*-V*, *--version*::
	Output version information and exit.

*--write-default-cfg*[**=**__PATH__]::
	Write a configuration file with defaults, show its path and exit.
+
The file will be appropriately commented.

Commands
--------
The bot accepts the following commands when they either appear quoted by the
*prefix* string on a channel or unquoted as a private message sent directly
to the bot, on the condition that the sending user matches the *admin*
regular expression or that it is left unset:

*quote* [_message_]::
	Forwards the message to the IRC server as-is.
*quit* [_reason_]::
	Quits the IRC server, with an optional reason string.
*status*::
	Sends back a report about its state and all loaded plugins.
*load* _plugin_[, _plugin_]...::
	Tries to load the given plugins.
*unload* _plugin_[, _plugin_]...::
	Tries to unload the given plugins.
*reload* _plugin_[, _plugin_]...::
	The same as *unload* immediately followed by *load*.

Plugins
-------
Plugins communicate with the bot over their standard input and output streams
using the IRC protocol.  (Caveat: the standard C library doesn't automatically
flush FILE streams for pipes on newlines.)  A special *XB* command is introduced
for RPC, with the following subcommands:

*XB get_config* _key_::
	Request the value of the given configuration option.  If no such option
	exists, the value will be empty.  The response will be delivered in
	the following format:
+
```
XB :value
```
+
This is particularly useful for retrieving the *prefix* string.

*XB print* _message_::
	Make the bot print the _message_ on its standard output.

*XB register*::
	Once a plugin issues this command, it will start receiving all of the bot's
	incoming IRC traffic, which includes data from the initialization period.

All other commands will be forwarded directly to the IRC server.

Files
-----
*xB* follows the XDG Base Directory Specification.

_~/.config/xB/xB.conf_::
	The bot's configuration file.  Use the *--write-default-cfg* option
	to create a new one for editing.

_~/.local/share/xB/_::
	The initial working directory for plugins, in which they may create private
	databases or other files as needed.

_~/.local/share/xB/plugins/_::
_/usr/local/share/xB/plugins/_::
_/usr/share/xB/plugins/_::
	Plugins are searched for in these directories, in order, unless
	the *plugin_dir* configuration option overrides this.

Reporting bugs
--------------
Use https://git.janouch.name/p/uirc3 to report bugs, request features,
or submit pull requests.