xK/xB.adoc

105 lines
2.9 KiB
Plaintext

xB(1)
=====
:doctype: manpage
:manmanual: xK Manual
:mansource: xK {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/xK to report bugs, request features,
or submit pull requests.