.\"
.\" Copyright (c) 2013-2021 David Demelier <markand@malikania.fr>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd @IRCCD_MAN_DATE@
.Dt IRCCD 1
.Os
.\" NAME
.Sh NAME
.Nm irccd
.Nd IRC Client Daemon
.\" SYNOPSIS
.Sh SYNOPSIS
.Nm
.Op Fl c Ar file
.Op Fl v
.Nm
.Ar info
.Nm
.Ar version
.\" DESCRIPTION
.Sh DESCRIPTION
The
.Nm
program is an IRC bot which connects to one or more severs and
dispatches events to plugins and connected clients.
.Pp
The following options are available:
.Bl -tag -width indent-xxx
.It Fl c Ar file
specify the configuration file.
.It Fl v
be verbose.
.El
.Pp
When ran without arguments,
.Nm
will read your configuration file and dispatch IRC events to the plugins and
connected clients indefinitely.
.Pp
Otherwise, the following commands are available:
.Bl -tag -width 12n
.It Cm info
Show in a scriptable manner the options that were selected during irccd's build.
.It Cm version
Get the irccd version. if Mercurial was available when building irccd then the
current revision is bundled in the output.
.El
.\" PLUGINS
.Sh PLUGINS
The
.Nm
program can run plugins once IRC events are received. For example, if someone
sends you a private message plugins will be invoked with that event. Both native
plugins written in C++ and Javascript are supported (if enabled at compile
time).
.Pp
The following IRC events are supported:
.Bl -tag -width 12n
.\" onCommand
.It onCommand
This is a special event that does not exist in IRC context. It calls the plugin
special invocation command using
.Ar "!name arguments..."
syntax. The exclamation mark is configured by default to be the command
character prefix, then if the adjacent name is known to be a loaded plugin it is
invoked with the additional arguments.
.Pp
Example: to call the
.Nm hangman
plugin, one may use !hangman to start a game.
.Pp
See also
.Xr irccd.conf 5
on how to change the command character prefix under a
.Va [server]
section.
.\" onConnect
.It onConnect
When a server successfully connects to an IRC server.
.\" onDisconnect
.It onDisconnect
When a server disconnected from an IRC server both in case of failures or
explicit user disconnection.
.\" onInvite
.It onInvite
Event called when the bot itself has been invited to a channel.
.\" onJoin
.It onJoin
When someone joins a channel.
.\" onKick
.It onKick
When someone has been kicked from a channel, irccd may be included.
.\" onLoad
.It onLoad
This is a special event that does not exist in IRC context. It is invoked when
the plugin is initialized.
.\" onMessage
.It onMessage
Upon private message.
.\" onMe
.It onMe
On action emote, also most known as
.Ar /me
command.
.\" onMode
.It onMode
When a user or channel mode change.
.\" onNames
.It onNames
When a list of nicknames has been received.
.\" onNick
.It onNick
On nick change, irccd may be included.
.\" onNotice
.It onNotice
On private notice.
.\" onPart
.It onPart
When someone leaves a channel.
.\" onReload
.It onReload
This is a special event that does not exist in IRC context. It is invoked when
the user asks to reload a plugin.
.\" onTopic
.It onTopic
When a channel topic has been changed.
.\" onUnload
.It onUnload
This is a special event that does not exist in IRC context. It is invoked when
the user asks to unload a plugin and before exiting.
.\" onWhois
.It onWhois
When a whois information has been received.
.El
.Pp
The following plugins are provided with irccd:
.Pp
.Bl -bullet -compact
.It
ask
.It
auth
.It
hangman
.It
history
.It
joke
.It
links
.It
logger
.It
plugin
.It
roulette
.It
tictactoe
.El
.Pp
See additional documentation in their own manual page in the form
.Xr irccd-plugin-name 7
where name is the actual plugin name.
.\" HOOKS
.Sh HOOKS
Hooks are a different and more lightweight approach to plugins, they are
executed upon incoming events and spawned each time a new event arrives.
.Pp
In contrast to plugins, differences are:
.Pp
.Bl -bullet -compact
.It
Hooks can not be filtered with rules.
.It
Hooks does not support all events. These events are not supported:
.Em onLoad , onUnload , onReload , onCommand , onNames , onWhois .
.It
Hooks can be written in any language.
.It
Execution may be slower since scripting languages require to fire up the
interpreter each time a new event is available.
.El
.Pp
Each hook will receive as positional argument the event name (similar to plugin
events) and the event arguments.
.Pp
An example of hook in shell script is available as
.Pa @CMAKE_INSTALL_FULL_DOCDIR@/examples/sample-hook.sh
file.
.Pp
See also the section
.Va [hooks]
in
.Xr irccd.conf 5
manual page to enable hooks.
.\" TRANSPORTS
.Sh TRANSPORTS
The daemon can be controlled at runtime using the dedicated
.Nm irccdctl
tool or using sockets.
.Pp
Both TCP/IP and UNIX sockets are supported and SSL layer may be enabled over it
for a secure connection. If authentication is desired, it can be enabled too.
.Pp
See also the
.Va [transport]
section in the
.Xr irccd.conf 5
manual page.
.\" RULES
.Sh RULES
.Nm
supports a feature called rules which allows you to define a fine-grained set of
rules allowed for specific plugins. For instance, you may want to disable some
IRC events for some plugins depending on your set of parameters. This is useful
for plugins that generates huge traffic.
.Pp
Rule events are matched using the same name as plugin events described in the
section above. For example, to disable a private message event you must use the
.Ar onCommand
value.
.Pp
See also the
.Va [rule]
section in the
.Xr irccd.conf 5
manual page.
.\" DIRECTORIES
.Sh DIRECTORIES
.Nm
uses different types of paths depending on the context.
.Pp
Paths prefixed by (W) means they are only used on Windows, others prefixed by
(U) means they are used on UNIX systems.
.Pp
.Ss Configuration
The following directories are searched in the specified order for configuration
files. For example, the files
.Pa irccd.conf
and
.Pa irccdctl.conf
will be searched there.
.Bl -bullet
.It
(W) %APPDATA%/irccd/config
.It
(U) ${XDG_CONFIG_HOME}/irccd
.It
(U) ${HOME}/.config/irccd (if XDG_CONFIG_HOME is not set)
.El
.\" SEE ALSO
.Sh SEE ALSO
.Xr irccd-api 7 ,
.Xr irccd-templates 7 ,
.Xr irccd-ipc 7 ,
.Xr irccd-plugin-ask 7 ,
.Xr irccd-plugin-auth 7 ,
.Xr irccd-plugin-hangman 7 ,
.Xr irccd-plugin-history 7 ,
.Xr irccd-plugin-joke 7 ,
.Xr irccd-plugin-links 7 ,
.Xr irccd-plugin-logger 7 ,
.Xr irccd-plugin-plugin 7 ,
.Xr irccd-plugin-roulette 7 ,
.Xr irccd-plugin-tictactoe 7 ,
.Xr irccd-test 1 ,
.Xr irccd.conf 5 ,
.Xr irccdctl 1 ,
.Xr irccdctl.conf 5