.\"
.\" Copyright (c) 2013-2020 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 IRCCDCTL.CONF 5
.Os
.\" NAME
.Sh NAME
.Nm irccdctl.conf
.Nd irccdctl configuration file
.\" DESCRIPTION
.Sh DESCRIPTION
The
.Nm irccdctl
utility use the same configuration file syntax and paths, see the manual of
irccd.conf file for more information.
.\" CONFIGURATION SECTIONS
.Sh CONFIGURATION SECTIONS
Configuration are always stored in dedicated section in the form
.Ar [name]
where name is one of the section defined below and are case-sensitive.
.\" [general]
.Ss general
This section defines the global irccdctl parameters.
.Pp
Available options:
.Bl -tag -width 18n
.It Va verbose No (bool)
Enable verbose message (Optional, default: false).
.El
.\" [connect]
.Ss connect
The section socket permit irccdctl to connect to a specific irccd transport,
only one must be defined. Just like transports you can connect to Unix or
internet sockets.
.Pp
Available options:
.Bl -tag -width 18n
.It Va type No (string)
Connection type, must be set to
.Dq ip
or
.Dq unix .
.It Va password No (string)
An authentication password (Optional, default: none).
.El
.Pp
The following options are available for the
.Ar ip
type:
.Bl -tag -width 18n
.It Va hostname No (string)
Host to connect.
.It Va port No (int)
Port number.
.It Va ipv4 No (bool)
Try to connect with ipv4 (Optional: default true).
.It Va ipv6 No (bool)
Try to connect with ipv6 (Optional: default true).
.El
.Pp
The following options are available for the
.Ar unix
type:
.Bl -tag -width 18n
.It Va path No (string)
The file path to the socket.
.El
.\" [alias]
.Ss alias
The alias section can be used to define custom user commands.
.Pp
To define an alias, just add a new section named
.Va [alias.name]
where name is your desired alias name.
.Pp
Then, add any option you like to execute commands you want. The option name is
ignored and serves as auto-documentation only.
.Pp
Example:
.Bd -literal -offset Ds
[alias.present]
say-hello = ( "server-message", "localhost", "#staff", "hello world!" )
warning = ( "server-me", "localhost", "#staff", "is a bot")
.Ed
.Pp
This alias
.Cm present
will do:
.Bl -enum
.It
Send a message on the channel #staff in the server localhost
.It
Send an action emote on the same channel
.El
.Pp
To use this alias, call
.Nm irccdctl
.Cm present .
.Pp
Sometimes, you want to pass parameters to your alias. The placeholder syntax
allows you to define where your command line arguments will be replaced before
being sent to irccd.
.Pp
The syntax uses
.Ar %n
where
.Ar n
is an integer starting from 0.
.Pp
As you have seen in the present alias example above, the channel and server
are hardcoded so the user is not able to use this alias for different channels.
Let's update this alias with placeholders to make it more generic.
.Pp
Example:
.Bd -literal -offset Ds
[alias.present]
say-hello = ( "server-message", "%0", "%1", "hello world!" )
warning = ( "server-me", "%0", "%1", "is a bot")
.Ed
.Pp
Now, the
.Cm present
alias will except two arguments from the command line when the user invokes
irccdctl as following:
.Bd -literal -offset Ds
irccdctl present
.Ed
.Pp
Thus if you want to use this alias on the #staff@localhost, you call the alias
using:
.Bd -literal -offset Ds
irccdctl present localhost "#staff"
.Ed
.\" EXAMPLES
.Sh EXAMPLES
Example for internet transports.
.Bd -literal
[connect]
type = "internet"
hostname = "localhost"
port = "9999"
.Ed
Example for unix transports.
.Bd -literal
[connect]
type = "unix"
path = "/tmp/irccd.sock"

# inspired by irssi /cycle
[alias.cycle]
leave = ( "server-part", "%0", "%1" )
join = ( "server-join", "%0", "%1" )
.Ed
.\" SEE ALSO
.Sh SEE ALSO
.Xr irccd 1 ,
.Xr irccdctl 1
.\" AUTHORS
.Sh AUTHORS
.Nm irccdctl
was written by David Demelier <markand@malikania.fr>