Mercurial > irccd
view doc/src/irccd.md @ 721:2fa1f2c898ee
Irccd: use struct's in server events
author | David Demelier <markand@malikania.fr> |
---|---|
date | Mon, 16 Jul 2018 13:29:48 +0200 |
parents | 1b04ffb2b35e |
children | ebe561276c33 |
line wrap: on
line source
% irccd % David Demelier % 2017-12-08 The `irccd` program is an IRC bot which connects to one or more severs and dispatches events to plugins. # Synopsis $ irccd [options...] # Options The following options are available: - `-c, --config file`: specify the configuration file, - `-v, --verbose`: be verbose, - `--version`: show the version. # Paths Irccd uses different types of paths depending on the context. - Configuration - Plugins Paths prefixed by (W) means they are only used on Windows, others prefixed by (U) means they are used on Unix systems # Configuration The following directories are searched in the specified order for configuration files. For example, the files `irccd.conf` and `irccdctl.conf` will be searched there. - \(W) %APPDATA%/irccd/config - \(U) ${XDG\_CONFIG\_HOME}/irccd - \(U) ${HOME}/.config/irccd (if XDG\_CONFIG\_HOME is not set) - CMAKE\_INSTALL\_SYSCONFDIR/irccd Examples: - /home/john/.config/irccd/irccd.conf - /usr/local/etc/irccd.conf - C:/Program Files/irccd/etc/irccd/irccd.conf - C:/Users/john/AppData/irccd/config # Plugins These directories are searched in the following order to load plugins when they are not specified by full paths. - current working directory - \(W) %APPDATA%/irccd/share/plugins - \(U) ${XDG\_DATA\_HOME}/irccd/plugins - \(U) ${HOME}/.local/share/irccd/plugins (if XDG\_DATA\_HOME is not set) - CMAKE\_INSTALL\_LIBDIR/irccd (both native and Javascript) Examples: - /home/john/.local/share/irccd/plugins/ask.js - /usr/local/lib/irccd/plugins/ask.js - C:/Users/john/AppData/irccd/share/plugins/ask.js - C:/Program Files/irccd/lib/irccd/plugins/ask.js # Templates and formatting Plugins can be configured using a powerful template syntax, this allows editing the plugin messages to override them. The syntax is `?{}` where `?` is replaced by one of the token defined below. Braces are mandatory and cannot be ommited. To write a literal template construct, prepend the token twice. ## Availables templates The following templates are available: - `%`, date and time (see [Time](#time)), - `#{name}`, name will be substituted from the keywords (see [Keywords](#keywords)), - `${name}`, name will be substituted from the environment variable (see [Environment variables](#environment-variables)), - `@{attributes}`, the attributes will be substituted to IRC colors (see [Attributes](#attributes)), ## Time When you can use patterns, the date and time may be used just like `strftime(3)` so for the hours and minutes, you can use **%H:%M**. ## Environment variables If supported, you can use environment variables like **${HOME}**. Please note that braces are mandatory. ## IRC attributes The attribute format is composed of three parts, foreground, background and modifiers, each separated by a comma. Note: attributes and colors are not supported by all IRC clients. Warning: do not use colors and attributes outside IRC (e.g. for storing text in files) because escape codes are only valid in IRC context. ### Available colors - white, - black, - blue, - green, - red, - brown, - purple, - orange, - yellow, - lightgreen, - cyan, - lightcyan, - lightblue, - pink, - grey, - lightgrey. ### Available attributes - bold, - italic, - strike, - reset, - underline, - underline2, - reverse. ## Shell attributes Like IRC attributes, it's possible to specify colors and attributes in some places such as logger configuration. Warning: colors are not supported on all platforms. ### Available colors - black, - red, - green, - orange, - blue, - purple, - cyan, - white, - default. ### Available attributes - bold, - dim, - underline, - blink, - reverse, - hidden. ## Keywords Keywords are arbitrary names that are replaced depending on the context. They are usually available to configure plugins. ### Predefined keywords Here's the list of keywords that a lot of plugins uses: - **#{channel}**, the channel name, - **#{command}**, the command to invoke the plugin, e.g. `!ask`, - **#{message}**, a message (depending on context), - **#{origin}**, the full user, e.g. `markand!~mkd@localhost`, - **#{nickname}**, the short nickname, - **#{plugin}**, the plugin name, - **#{server}**, the current server name, - **#{topic}**, the topic, - **#{target}**, a target, e.g. a person who gets kicked. Warning: these keywords can be overriden by plugins. ## Examples ### Valid constructs - `#{target}, welcome`: if target is set to "irccd", becomes "irccd, welcome", - `@{red}#{target}`: if target is specified, it is written in red. ### Invalid or literals constructs - `##{target}`: will output "#{target}", - `##`: will output "##", - `#target`: will output "#target", - `#{target`: will throw an error. ### Colors & attributes - `@{red,blue}`: will write text red on blue background, - `@{default,yellow}`: will write default color text on yellow background, - `@{white,black,bold,underline}`: will write white text on black in both bold and underline. ### In the logger plugin For instance, using the **logger** plugin, it's possible to customize the pattern to use when someone joins a channel like that: #{origin} joined #{channel} The keyword **#{origin}** will be substituted to the nickname and **#{channel}** to the channel name. # See also - irccd.conf(5) - irccdctl(1)