aboutsummaryrefslogtreecommitdiff
path: root/zyklonb.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'zyklonb.adoc')
-rw-r--r--zyklonb.adoc104
1 files changed, 104 insertions, 0 deletions
diff --git a/zyklonb.adoc b/zyklonb.adoc
new file mode 100644
index 0000000..d02368f
--- /dev/null
+++ b/zyklonb.adoc
@@ -0,0 +1,104 @@
+zyklonb(1)
+==========
+:doctype: manpage
+:manmanual: uirc3 Manual
+:mansource: uirc3 {release-version}
+
+Name
+----
+zyklonb - an experimental IRC bot
+
+Synopsis
+--------
+*zyklonb* [_OPTION_]...
+
+Description
+-----------
+*zyklonb* 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 *ZYKLONB* command is
+introduced for RPC, with the following subcommands:
+
+*ZYKLONB 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:
++
+```
+ZYKLONB :value
+```
++
+This is particularly useful for retrieving the *prefix* string.
+
+*ZYKLONB print* _message_::
+ Make the bot print the _message_ on its standard output.
+
+*ZYKLONB 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
+-----
+*zyklonb* follows the XDG Base Directory Specification.
+
+_~/.config/zyklonb/zyklonb.conf_::
+ The bot's configuration file. Use the *--write-default-cfg* option
+ to create a new one for editing.
+
+_~/.local/share/zyklonb/_::
+ The initial working directory for plugins, in which they may create private
+ databases or other files as needed.
+
+_~/.local/share/zyklonb/plugins/_::
+_/usr/local/share/zyklonb/plugins/_::
+_/usr/share/zyklonb/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.