Srain Documentation Release 1.3.0 Shengyu Zhang Sep 21, 2021
Srain DocumentationRelease 1.3.0
Shengyu Zhang
Sep 21, 2021
Contents
1 All pages 31.1 Srain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.4 Commands Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.5 Configuration Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.6 Development Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291.7 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301.8 Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301.9 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341.10 Support Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2 Indices and Tables 47
i
ii
Srain Documentation, Release 1.3.0
Welcome to Srain documentation!
Latest version: 2021-09-23 Version 1.3.0.
The source code of this documentation is hosted on GitHub. If you found any mistake, feel free to file issue or pullrequest.
Contents 1
Srain Documentation, Release 1.3.0
2 Contents
CHAPTER 1
All pages
1.1 Srain
Modern IRC client written in GTK.
Home | Documentation | Source code
3
Srain Documentation, Release 1.3.0
1.1.1 Packaging Status
1.1.2 Features
• Fully open source
• RFC {1459,2812} compatible
• Partial IRCv3 support
• Multi-platform support (Linux, Windows, macOS and BSD)
• Act like modern IM client
– Graphical user interface
– Convenient connection panel
– Interactive channel search
– Forward message in one click
– URL preview
– Desktop notificaion
– Special optimization for bridge/relay bot
• Act like geek IRC client
– Anything can be done via commands
– Fine-grained configuration with hot update support
– Regex based message render and filter mechanisms
– IPC based plugin system (TODO)
1.1.3 Need Help?
Frequently Asked Questions may be helpful.
Feel free to contact us if you have any question about Srain.
• IRC Channel: #srain @ Libera Chat
• Github: file an issue Here
1.1.4 License
GNU General Public License Version 3
1.2 Quick Start
4 Chapter 1. All pages
Srain Documentation, Release 1.3.0
• Start Srain
• Connect to IRC server
– Predefined Server
– Custom Server
– Using Command
• Join Channel
– Directly Join
– Search Channel
– Using Command
Note: For your information, the following screenshots are taken under GNOME 3.34.4 with Wayland backed withArc GTK theme and Breeze icon theme.
1.2.1 Start Srain
After the Installation of Srain, you will find Srain in your applications list, if not, just type srain in your shell to runit. Then you will see Srain’s initial interface.
1.2. Quick Start 5
Srain Documentation, Release 1.3.0
1.2.2 Connect to IRC server
freenode is a famous IRC network, the official channel of Srain #srain is also hosted on it. Let’s start by connecting tofreenode.
Predefined Server
Srain has a predefined list of commonly used IRC servers, freenode is one of it. If you want to add server into this list,refer to Configuration Manual.
Click the connection button on the Srain header bar, select the page “Quick Mode”, select the item “freenode” fromcandidate box with label “Server”, enter your nickname, then click the “Connect” button:
If everything goes well, Srain should connected to freenode, then your would see some message from freenode’sserver:
Custom Server
While the server your want to connect to is not listed in the predefined list, switch to the page “Advanced Mode”, enterthe hostname, port, and etc.
Note:
• If the port is a TLS port, make sure that the option “Use secure connection” is checked.
• If the server’s certificate is untrusted and you insist on continuing, check the option “Do not verify certificate”.
6 Chapter 1. All pages
Srain Documentation, Release 1.3.0
Then click the “Connect” button:
Using Command
Refer to /server and /connect.
If you want to automatically execute commands at each time Srain starts, please refer to Playground.
1.2.3 Join Channel
After connecting to freenode, now let’s try to join #srain, the official channel of Srain.
Directly Join
While your has a clear channel to join, such as #srain, just click the join button, select the page “Join Channel”, enterthe channel name in the input entry with label “Channel”, then click the “Join” button:
Now you should joined the channel:
Search Channel
While you don’t know the exact name of the channel, click the join button, switch to page “Search Channel”, click thebutton with “refresh” icon, Srain should start receiving channel list from server.
1.2. Quick Start 7
Srain Documentation, Release 1.3.0
8 Chapter 1. All pages
Srain Documentation, Release 1.3.0
Then you can enter the keyword or specify the filter conditions to search channel. For example we enter “#s”, selectthe channel you want to join from channe list, then click “Join” button to join it.
Note: If the channel requires a join password, try double click the row of channel.
Using Command
Refer to /join.
1.3 Installation
Srain is available on GNU/Linux, Windows, macOS and BSD.
• Dependencies
• Building
– Play with Meson
– Makefile Helper
• Distribution Packages
1.3. Installation 9
Srain Documentation, Release 1.3.0
– GNU/Linux
* Arch Linux
* Debian
· Pre-built package
· Build byself
* Fedora
* Flatpak
* Gentoo
* openSUSE
– Windows
* Pre-built package
* Build byself
– macOS
– BSD
* OpenBSD
10 Chapter 1. All pages
Srain Documentation, Release 1.3.0
1.3.1 Dependencies
Name Notes Versionmeson Only for Building > 0.45.0make Optional, only for developmentappstream Only for building, on Debian-based distributionscoreutils Only for buildinggcc Only for buildingpkg-config Only for buildinggettext Only for buildingglib2glib-networking Optional, for TLS connection supportgtk+3 >= 3.18libsouplibconfig >= 1.5libsecretopensslpython-sphinx Optional, for building documentation
1.3.2 Building
You should install the aboved Dependencies on your platform before the following steps.
Firstly, download source code of srain, you can get source code of latest release:
$ wget https://github.com/SrainApp/srain/archive/1.3.0.tar.gz$ tar -xvzf 1.3.0.tar.gz$ cd srain-1.3.0
Or get git version:
$ git clone https://github.com/SrainApp/srain.git$ cd srain
Play with Meson
Srain use Meson with ninja backend as its build system. You can build it via the following commands:
$ meson setup builddir$ cd builddir$ ninja
Install(root privileges required):
$ cd builddir# ninja install
HTML documentation and manpage are built and installed by default, if you don’t need them, just set meson optiondoc_builders to an empty array when setup:
$ meson setup -Ddoc_builders=[] builddir
1.3. Installation 11
Srain Documentation, Release 1.3.0
Makefile Helper
We also provide a simple Makefile helper to simplify meson commands. It is convenient for development.
$ make # Build srain$ make build # Same as above$ make install # Install srain to prefix under project root$ make run # Run srain with isolated $HOME and XDG Directory$ make debug # Same as `make run`, but with GDB attached$ make inspect # Same as `make run`, but with GtkInspector$ make clean # Remove all compilation and installation result$ make doc # View installed HTML documentation
1.3.3 Distribution Packages
GNU/Linux
Arch Linux
Packages srain and srain-git (git version) are available on AUR, it is quite easy to install using AUR helper(yay as anexample):
$ yay -S srain$ yay -S srain-git # git version
If you are the user of Arch Linux CN Repository, try:
# pacman -S archlinuxcn/srain# pacman -S archlinuxcn/srain-git # git version
Debian
There is no srain package in the official repository yet.
Pre-built package
We provide pre-built deb package that you can get it from Github release page.
Build byself
Copy the debian folder on srain-contrib to srain folder. Then type following command on your terminal:
$ dpkg-buildpackage -b -us -uc
Note that the dependencies mentioned above also should be installed. The details could be found on debian/crontrolfile.
Then install the package (replace package name with the name of your package):
$ sudo apt-get install -f ../srain_1.3.0-1_amd64.deb
12 Chapter 1. All pages
Srain Documentation, Release 1.3.0
Fedora
Srain now in offical repository of fedora, use dnf to install it.
# dnf install srain
Flatpak
cpba is maintaining Flatpak manifest for Srain and The built package is available on Flathub, just execute the followingcommands to install if you already have flatpak installed:
$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.→˓flatpakrepo$ flatpak install flathub im.srain.Srain
Gentoo
Please refers to gentoo portage overlays.
openSUSE
alois is maintaining openSUSE package for Srain, following this link to install it.
Windows
Srain requires Windows 7 or later.
Pre-built package
After 2020-08-10 Version 1.1.2, we provide Windows portable binary that you can get it from Github release page.
Build byself
If you want to build Srain on Windows youself, you should use the toolchains provided by MSYS2 project.
Firstly install MSYS2, then open a MSYS2 shell, install the basic build tools:
$ pacman -S base-devel$ pacman -S mingw-w64-i686-toolchain # For 32-bit Windows$ pacman -S mingw-w64-x86_64-toolchain # For 64-bit Windows
Then download the package script from MinGW PKGBUILD for Srain, run the following commands at the directoryof PKGBUILD:
$ MINGW_INSTALLS=mingw32 makepkg-mingw -fsi # For 32-bit Windows$ MINGW_INSTALLS=mingw64 makepkg-mingw -fsi # For 64-bit Windows
1.3. Installation 13
Srain Documentation, Release 1.3.0
If everything goes well, Srain is installed under your MinGW prefix.
Note: If you suffer the “error while loading shared libraries: xxxx.dll: cannot open shared object file: No such file ordirectory” problem when running, please run it in cmd but not msys2 shell, and it will show you real missing library.1
macOS
Warning: macOS support of Srain is still experimental.
There is not a distribution package or package script for Srain on macOS, you should build Srain by yourself.
Firstly install Homebrew, run the following commands to install dependencies:
$ brew install coreutils gcc pkg-config # building$ brew install gettext glib-networking gtk+3 libsoup libconfig
Then follow the steps in Building.
BSD
OpenBSD
Please refers to OpenBSD Ports.
1.4 Commands Manual
• Playground
• Syntax
• Available Commands
– /reload
– /server
– /connect
– /ignore & /unignore
– /query & /unquery
– /join
– /part
– /quit
– /topic
1 https://github.com/Alexpux/MINGW-packages/issues/3939#issuecomment-397988379
14 Chapter 1. All pages
Srain Documentation, Release 1.3.0
– /msg
– /me
– /nick
– /whois
– /invite
– /kick
– /mode
– /ctcp
– /pattern
– /filter & /unfilter
– /render & /unrender
– /quote
• Obsoleted Commands
– /rignore & /unrignore
– /relay & /unrelay
1.4.1 Playground
User can run commands in two ways, the one way is typing them into the input entry of chat buffer.
The another way is writing the commands to the server.auto-run and chat.auto-run configuration items.For more details, please refer to Configuration Manual.
1.4.2 Syntax
A command is a line of string that has the following format, different elements are separated by whitespace:
/<name|alias> [subcommand] [<option> [value]]... [argument]...
User should use name to invoke a command. The command’s name starts with a slash / and doesn’t contain anywhitespace, such as: /join. Some commands have alias that can be used instead of name, for example, user canuse /j instead of /join.
Note: When you want to send a message starts with a slash, please prepend another slash to the message. Forexample, you want to send “/this is a slash prefixed message”, you need to type “//this is a slash prefixed message”.
A subcommand is a instruction behind the command name, it is optional.
An option, as its name, is optional too, starts with a hyphen - and may has a value.
option is often used as the switch of a flag or a way to change some default values. For example, The command/connect -tls -port 6697, option -tls is just a flag that tells srain use secure connections with TLS. And-port requires a value, if -port is not specified, program will use the default value 6667. Check /connect formore details.
1.4. Commands Manual 15
Srain Documentation, Release 1.3.0
If a value starts with a hyphen - or contains whitespaces, it should be enclosed by single quotation mark '.
Note: All option should appear behind subcommand (If any), and before argument.
An argument is similar to value, but commonly it doesn’t have a default value so it can not be omitted (actually itdepends on the implement of the command). If the first argument starts with a hyphen -, it should be enclosed bysingle quotation mark '. If an argument contains whitespaces, it should be quoted too. Specially, the last argumentcan contain whitespace without quoted.
If you want to use a single quotation mark in a quoted text, use backslash \ to escape it. For backslash itself, usedouble backslash \\.
1.4.3 Available Commands
/reload
Usage:
/reload
Reload user configuration.
/server
Usage:
/server [connect|disconnect|list] <name>
Predefined IRC server management.
Sub commands:
• connect: connect to specified predefined server
• disconnect: disconnect from specified predefined server
• list: list all predefined servers
Arguments:
• name: unique name of server
/connect
Usage:
/connect [-port <port>] [-pwd <password>] [-tls] [-tls-noverify][-user <username>] [-real <realname>] <host> <nick>
Create a IRC server and connect to it immediately.
Options:
• -port: server port, default 6667
• -pwd: connection password, default empty
16 Chapter 1. All pages
Srain Documentation, Release 1.3.0
• -tls: use secure connections with TLS
• -tls-noverify: use TLS connection without certificate verification
• -user: specify username, default same as nickname
• -real: specify realname, default same as nickname
Arguments:
• host: server host
• nick: specify nickname
Example:
/connect -real 'I am srainbot' -tls -port 6697 chat.freenode.org srainbot/connect 127.0.0.1 srainbot
/ignore & /unignore
Usage:
/ignore [-cur] <nick>/unignore [-cur] <nick>
Ignore/unignore somebody’s message.
Options:
• -cur: only ignore in current chat
/query & /unquery
Usage:
/query|q <nick>/unquery [nick]
Start/stop private chat with somebody. For /unquery , If no nick is specified, it stops the current private chat.
/join
Usage:
/join|j <channel>[,<channel>]... [<passwd>[,<passwd>]]...
Join specified channel(s), channels are separated by commas ,.
Example:
/join #archinux-cn,#gzlug,#linuxba/join #channel1,#channe2 passwd1
1.4. Commands Manual 17
Srain Documentation, Release 1.3.0
/part
Usage:
/part|leave [<channel>[,<channel>]]... [<reason>]
Leave specified channel(s) with optional reason, channels are separated by commas ,. If no channel is specified, itleaves the current channel.
Example:
/part #archinux-cn Zzz.../part #archlinux-cn,#tuna/part
/quit
Usage:
/quit [reason]
Quit current server with optional reason.
/topic
Usage:
/topic [-rm|<topic>]
Set the current channel’s topic. If no topic specified, it just displays the current channel’s topic.
• -rm: remove current channel’s topic
Example:
# Just view the topic/topic# Set the topic to "Welcome to Srain!"/topic Welcome to Srain!# Clear the topic/topic -rm
/msg
Usage:
/msg|m <target> <message>
Send message to a target, the target can be channel or somebody’s nick. If you want to send a message to channel, youshould /join it first.
18 Chapter 1. All pages
Srain Documentation, Release 1.3.0
/me
Usage:
/me <message>
Send an action message to the current target.
/nick
Usage:
/nick <new_nick>
Change your nickname.
/whois
Usage:
/whois <nick>
Get somebody’s information on the server.
/invite
Usage:
/invite <nick> [channel]
Invite somebody to join a channel. If no channel is specified, it falls back to current channel.
/kick
Usage:
/kick <nick> [channel] [reason]
Kick somebody from a channel, with optional reason. If no channel is specified, it falls back to current channel.
/mode
Usage:
/mode <target> <mode>
Change target ‘s mode.
1.4. Commands Manual 19
Srain Documentation, Release 1.3.0
/ctcp
Usage:
/ctcp <target> <command> [message]
Send a CTCP request to target. The commonly used commands are: CLIENTINFO, FINGER, PING, SOURCE,TIME, VERSION, USERINFO. For the detail of each command, please refer to https://modern.ircdocs.horse/ctcp.html.
If you send a CTCP PING request without message, you will get the latency between the target.
Note: DCC is not yet supported.
/pattern
Usage:
/pattern add <name> <pattern>/pattern rm <name>/pattern list
Regular expression pattern management. The added pattern can be used elsewhere in the application, such as /filter &/unfilter and /render & /unrender.
Sub commands:
• add: add a pattern with given name
• rm: remove a pattern with given name
• list: list all availables patterns
Arguments:
• name: unique name of pattern
• pattern: a valid Perl-compatible Regular Expression
/filter & /unfilter
Usage:
/filter [-cur] <pattern>/unfilter [-cur] <pattern>
Filter message whose content matches specified pattern.
Options:
• -cur: only ignore in current chat
Arguments:
• pattern: name of regular expression pattern which is managed by /pattern
Example:
This filter message that content is “Why GTK and not Qt?”:
20 Chapter 1. All pages
Srain Documentation, Release 1.3.0
/pattern add troll ^Why GTK and not Qt\?$/filter troll
To cancel the filter of these kind of message, use:
/unfilter troll
Note: Pattern NO NEED to consider the case where the mIRC color code is included in the message.
/render & /unrender
Usage:
/render [-cur] <nick> <pattern>/unrender [-cur] <nick> <pattern>
Render message of specific user via specific pattern.
The given pattern should contains specific Named Subpatterns used for capturing message fragment from originalmessage content and become part of rendered message.
There are list of available named subpatterns:
• (?<sender>): match name of sender, once this subpatterns is matched, the original sender will be displayedas message remark
• (?<content>): match content of rendered message
• (?<time>): match time of rendered message
Arguments:
• nick: nickname of user
• pattern: name of regular expression pattern which is managed by /pattern
Options:
• -cur: only effects the user under current chat
Example:
We assume that there is a IRC bot named “xmppbot”. It forwards message between XMPP and IRC. On IRC side, theforwarded message looks like “<xmppbot> [xmpp_user] xmpp_message”, you can render it to a more easy-to-readformat via the following commands:
/pattern add xmpp \[(?<sender>[^:]+?)\] (?<content>.*)/render xmppbot xmpp
The forwarded meessage will look like “<xmpp_user> xmpp_message”, and the original message sender “xmppbot”will be displayed as message remark. Please refer to What is “relay message transform”? see its effect.
Note: Pattern SHOULD consider the case where the mIRC color code is included in the message.
1.4. Commands Manual 21
Srain Documentation, Release 1.3.0
/quote
Usage:
/quote <raw message>
For sending special IRC commands.
New in version 1.2.0.
1.4.4 Obsoleted Commands
/rignore & /unrignore
This command has been dropped since 2019-06-14 Version 1.0.0rc5, please use /filter & /unfilter instead.
/relay & /unrelay
This command has been dropped since 2019-06-14 Version 1.0.0rc5, please use /render & /unrender instead.
1.5 Configuration Manual
Srain uses Libconfig to process configuration file.
• Configuration File
• Syntax
• Priority and Fallback
• All Configurable Items
1.5.1 Configuration File
The path of system wide configuration file builtin.cfg depends on the compile flag --sysconfdir, default tobe /etc/srain.
The path of user wide configuration file srain.cfg is $XDG_CONFIG_HOME/srain, usually it is ~/.config/srain (~/.var/app/im.srain.Srain for flatpak installs).
The difference between system wide and user wide configuration file is the priority, The user wide configurationalways overwrite the one in system wide configuration. For more details about priority, refer to Priority andFallback.
1.5.2 Syntax
For the syntax of configuration file, please refer to Libconfig’s documentation: Configuration Files
For an example configuration, refer to All Configurable Items.
22 Chapter 1. All pages
Srain Documentation, Release 1.3.0
1.5.3 Priority and Fallback
A group is a collection of configurations. The same group in different place have different priority.
server: { # A top level ``server`` group
# ...
user = {}default-messages = {}irc = {}chat = { } # A ``chat`` group directly in ``server``
chat-list = ({ }, # A ``chat`` group in ``chat-list``# ...
)}
server-list: ({ }, # A ``server`` group in ``server-list``# ...
)
For example, A server group contains the information(not all) of connection to IRC servers. server group canappear at the top level of configuration file, or be an element of server-list list with a unique name. The toplevel server is often used to specify the global configuration, and server-list is used to specify specified IRCservers.
The configuration in server-list can overwrite the top level server, and if an option is not specified inserver-list, It will fallback to server.
Another similar group is chat, chat contains configuration of chat panel, such as whether to show topic, whetherto save chat log and etc. Every server group can contain a chat group and a chat-list list. Elements inchat-list are also identified with an unique name.
As same as the relationship between top level server and server-list, chat-list is used to specify a speci-fied chat and has higher priority.
As mentioned above, The priority of user configuration is always higher than system’s, so we can get the prioritysorting of server and chat group:
server-list(user) >top level server(user) >server-list(system) >top level server(system)
chat-list in server-list(user) >chat in server-list(user) >chat-list in top level server(user) >chat in top level server(user) >chat-list in server-list(system) >chat in server-list(system) >chat-list in top level server(system) >chat in top level server(system)
1.5. Configuration Manual 23
Srain Documentation, Release 1.3.0
1.5.4 All Configurable Items
Here is the default system wide configuration file used by Srain, all configurable items are already listed here. you canmake a copy as your user configuration file, but note:
1. User configuration always overwrite system’s, if you don’t know what does this option means, please removeit from your user configuration rather than overwrite it
2. The server’s name in server-list is unique, please remoeve the duplicated server in server-listbefore using
# Srain built-in configuration file# Application configuration.
version = "1.0.0rc5" # String; Every configuration file should have a# version, altough it is not used yet
# id = "im.srain.Srain" # The identifier for Sraintheme = "default-bubble" # String; Theme; Available values: defaultcsd = true # Bool; Whether enable Client-Side Decorationsend-on-ctrl-enter = false # Bool; Send messsage on CTRL+Enter pressedexit-on-close = false # Bool; Exit program on main window closedauto-connect = [] # String array; Servers that are auto connected
# after startup
# If you want to report/fix a bug, terminal log will be helpful.log ={
prompt-color = true # Bool; Colorful outputprompt-file = false # Bool; Display the filename of the file which log
# statement is locatedprompt-function = true # Bool; As aboved, function nameprompt-line = false # Bool; As aboved, line number
# String array; Specify the log level of a group of filesdebug-targets = [] # Files with debug log levelinfo-targets = [] # Files with information log levelwarn-targets = [""] # Files with warning log levelerror-targets = [] # Files with error" log level
}
# Global IRC Server configuration, this group can also appear in server-list.server ={
auto-join = [] # String array; Chats that are auto joined after server# is created
auto-run = [] # String array; Commands that are auto run after server# is created
user ={
nickname = "SrainUser"username = "Srain"realname = "Can you can a can?"
login:{
method = "none" # String; Login method; Available values:# - none: No login method, default value
(continues on next page)
24 Chapter 1. All pages
Srain Documentation, Release 1.3.0
(continued from previous page)
# - nickserv: Login with NICKSERV command# - msg-nickserv: Login with /msg NickServ identify# - sasl-plain: Login with SASL PLAIN mechanism# - sasl-ecdsa: Login with SASL# ECDSA-NIST256P-CHALLENGE mechanism
# For method "sasl-ecdsa"# certificate = "" # String; Path to login certificate file
}
# Default messages for performing specified actionpart-message = "Leaving."kick-message = "Kick."away-message = "Away from keyboard."quit-message = "El Psy Congroo."
}
# Chat configuration, this group can also appear in chat-list.chat ={
log = true # Bool; Persistent chat log to storagenotify = true # Bool; Send notification when you are
# mentioned by others or receiving any# ERROR message
notify-all = true # Bool; Send notification when receiving# any PRIVMSG/ACTION/NOTIFY/ERROR message
show-topic = true # Bool; Show topicshow-avatar = false # Bool; Show user avatershow-user-list = true # Bool; Show user listrender-mirc-color = true # Bool; Render mirc colornick-completion-suffix = ":" # String; Suffix of completed nick name
# e.g. "nick: msg"
preview-url = true # Bool; Show previewer for every URLauto-preview-url = true # Bool; Automatically preview supported URL
auto-run = [] # String array; Commands that are auto run after# chat is created
}
# Specified chat configuration, every element in list should have a unique# ``name``.chat-list =(
{# ``name`` is necessary for a ``chat`` group in ``chat-list``.name = "#srain"show-topic = true
})
}
# Specified server configuration, every element in list should have a unique# "name".server-list =(
{(continues on next page)
1.5. Configuration Manual 25
Srain Documentation, Release 1.3.0
(continued from previous page)
# ``name``, ``addresses`` are necessary for a ``server`` group# in ``server-list``, otherwise you can not connect to it.name = "Libera Chat" # String; The unique name of serveraddresses = [
"irc.libera.chat:6697"] # String array; Addresses of IRC server,
# each address follows the format of# <host>[:<port>]. The port can be omitted,# default 6667 for non-TLS and 6697 for TLS
tls = true # Bool; Connect with TLS encryption# tls-noverify = false # Bool; Connect with TLS encryption but without
# certificate verification, only used while# connecting to a self-signed certificate# verified server
encoding = "utf-8" # String; Encoding of IRC server, to get# all available value of encoding, check the# output of ``iconv --list``
# ipv6 = false # Use IPv6 connection, not yet supported},{
name = "GIMPNet"addresses = ["irc.gimp.org:6697", "irc.gnome.org:6697"]tls = trueencoding = "utf-8"
},{
name = "OFTC"addresses = ["irc.oftc.net:6697"]tls = trueencoding = "utf-8"
},{
name = "hackint"addresses = ["irc.hackint.org:6697"]tls = trueencoding = "utf-8"
},{
name = "Rizon"addresses = ["irc.rizon.net:6697"]
tls = trueencoding = "utf-8"
},{
name = "DALnet"addresses = [
"irc.dal.net:6697","agility.nl.eu.dal.net:6697","bifrost.ca.us.dal.net:6697","bitcoin.uk.eu.dal.net:6697","choopa.nj.us.dal.net:6697","diamond.hub.dal.net:6697","fidelity.tx.us.dal.net:6697","foxtrot.hub.dal.net:6697","halcyon.il.us.dal.net:6697","hash.ix.nl.dal.net:6697",
(continues on next page)
26 Chapter 1. All pages
Srain Documentation, Release 1.3.0
(continued from previous page)
"hoon.ix.au.dal.net:6697","istana.ix.sg.dal.net:6697","jingo.ix.us.dal.net:6697","karsk.ix.eu.dal.net:6697","kiwi.ix.nz.dal.net:6697","koala.vc.au.dal.net:6697","laud.ix.us.dal.net:6697","loyalty.ix.us.dal.net:6697","merlin.hub.dal.net:6697","midnight.hub.dal.net:6697","ninja.hub.dal.net:6697","nonstop.ix.me.dal.net:6697","oi.ix.au.dal.net:6697","oper-e.dal.net:6697","paradigm.hub.dal.net:6697","powertech.no.eu.dal.net:6697","punch.wa.us.dal.net:6697","rangers.ix.us.dal.net:6697","redemption.ix.us.dal.net:6697","renew.hub.dal.net:6697","smurf.hub.dal.net:6697","underworld.se.eu.dal.net:6697","uworld.hub.dal.net:6697"
]tls = trueencoding = "utf-8"
},{
name = "EFnet"addresses = [
"irc.efnet.fr:6667","efnet.port80.se:6697","efnet.portlane.se:6667","irc.du.se:6667","irc.homelien.no:6667","irc.inet.tele.dk:6667","irc.nordunet.se:6667","irc.underworld.no:6667","irc.choopa.net:6697","irc.colosolutions.net:6667","irc.mzima.net:6667","irc.prison.netirc.servercentral.net:6667"
]tls = falseencoding = "utf-8"
},{
name = "IRCnet"addresses = [
"irc.ssl.ircnet.com:6697","irc.ircnet.com:6667","irc.at.ircnet.com:6667","irc.be.ircnet.com:6667","irc.cz.ircnet.com:6667","irc.dk.ircnet.com:6667","irc.ee.ircnet.com:6667","irc.fi.ircnet.com:6667",
(continues on next page)
1.5. Configuration Manual 27
Srain Documentation, Release 1.3.0
(continued from previous page)
"irc.fr.ircnet.com:6667","irc.de.ircnet.com:6667","irc.hu.ircnet.com:6667","irc.it.ircnet.com:6667","irc.jp.ircnet.com:6667","irc.nl.ircnet.com:6667","irc.no.ircnet.com:6667","irc.pl.ircnet.com:6667","irc.si.ircnet.com:6667","irc.se.ircnet.com:6667","irc.us.ircnet.com:6667"
]tls = falseencoding = "utf-8"
},{
name = "Undernet"addresses = [
"irc.undernet.org:6667","ix1.undernet.org:6667","ix2.undernet.org:6667","ashburn.va.us.undernet.org:6667","bucharest.ro.eu.undernet.org:6667","budapest.hu.eu.undernet.org:6667","chicago.il.us.undernet.org:6667"
]tls = falseencoding = "utf-8"
},{
name = "QuakeNet"addresses = [
"irc.quakenet.org:6667","dreamhack.se.quakenet.org:6667","euroserv.fr.quakenet.org:6667","irc.ipv6.quakenet.org:6667","port80a.se.quakenet.org:6667","port80b.se.quakenet.org:6667","port80c.se.quakenet.org:6667","portlane.se.quakenet.org:6667","servercentral.il.us.quakenet.org:6667","underworld1.no.quakenet.org:6667"
]tls = falseencoding = "utf-8"
},{
name = "freenode"addresses = [
"irc.freenode.net:6697","chat.freenode.net:6697","irc.freenode.org:6697","chat.freenode.org:6697"
]tls = trueencoding = "utf-8"
},(continues on next page)
28 Chapter 1. All pages
Srain Documentation, Release 1.3.0
(continued from previous page)
{name = "localhost"addresses = ["localhost:6667", "127.0.0.1:6667"]tls = false
}
# TODO: More predefined servers)
1.6 Development Specification
int bus_count = 1;
1.6.1 Codeing Style
• Public header __XXX_H
•
• Tab
• – 80 char per line
–
–
– gtk_widget_class_bind_template_child()
– case
• –
– +
–
• – 80
• Git commit log: MODULE(TYPE): DESCRIPTION (MODULE) All Core Sirc Sui PrefsFilter Decorator Lib I18n Data Plugin Build Script Doc... (TYPE) feat implchange fix improve cleanup refactor update release misc...
• I18N numbered argument %n$X
• Change log:
– Changed:
– Added:
– Removed:
– Imporved: bug
• – (TODO)
–
–
1.6. Development Specification 29
Srain Documentation, Release 1.3.0
– change log
–
–
– commit tag
– * Arch Linux: @SilverRainZ
* Gentoo: @xeirrr
* . . .
1.7 Miscellaneous
1.7.1 Hot Keys
• ctrl + j/k: switch chat panel
• up/down: scroll message list
Note: Customized hot keys will be supported in the future.
1.7.2 Chat Logs
Chat logs is enabled by default, log files are located at $XDG_DATA_HOME/srain/logs, usually it is ~/.local/share/srain/logs.
1.7.3 Insert Emojis
Click the emoji button or use shortcuts Ctrl+. or Ctrl+;.
New in version 1.3.
1.8 Frequently Asked Questions
Frequently asked questions are listed here, you can visit issue page to see more questions that asked by our users.
• Does Srain support Windows?
• What is “relay message transform”?
• Where are the log files?
• How can I send message which has a slash(“/”) prefixed?
• How can I remove my stored password?
• How can I hide JOIN/PART messages of channel?
• Why can’t I login to my ZNC server?
30 Chapter 1. All pages
Srain Documentation, Release 1.3.0
Fig. 1: Emoji button
1.8. Frequently Asked Questions 31
Srain Documentation, Release 1.3.0
1.8.1 Does Srain support Windows?
Yes, please refer to Windows.
1.8.2 What is “relay message transform”?
There are many relay bots forward messages from other IM to IRC network, “Relay message transform” make thesemessages easier to read.
For example, there is a telegram bot named “telegram”, the words in brackets is the named of the telegram user.
Run command /pattern add normal-relay \[(?<sender>[^:]+?)\] (?<content>.*) and /render telegram normal-relay, you get:
For more details, please refer to commands-pattern and commands-render.
1.8.3 Where are the log files?
Refer to Chat Logs.
1.8.4 How can I send message which has a slash(“/”) prefixed?
Please prepend another slash to the message.
Refer to Syntax.
32 Chapter 1. All pages
Srain Documentation, Release 1.3.0
1.8.5 How can I remove my stored password?
Just leave the password entry empty and check the “Remember password” checkbox before connect to server or joinchannel, the corresponding password will be removed.
Or you can use secret-tool (provided by libsecret) to manage all your stored passwords.
1.8.6 How can I hide JOIN/PART messages of channel?
So far, Srain has not yet a specialized option for hiding such messages. You can use write regular expression to filterthem:
/pattern add filter-join ^\w+ has joined$/filter filter-join/pattern add filter-part ^\w+ has left: .*$/filter filter-part
Note: The content of regular expression depends on your language.
1.8.7 Why can’t I login to my ZNC server?
According ZNC’s FAQ, way 2, supply your “user@phone/network:pass” (without quotes) in the server password field.Other as usual.
1.8. Frequently Asked Questions 33
Srain Documentation, Release 1.3.0
Note: Way 1 in ZNC’s FAQ requires username field can be set via connection panel, which will be supported bySrain in the future.
1.9 Change Log
• 2021-09-23 Version 1.3.0
• 2021-07-18 Version 1.2.4
• 2021-06-26 Version 1.2.3
• 2021-05-30 Version 1.2.2
• 2021-04-02 Version 1.2.1
• 2021-02-28 Version 1.2.0
• 2020-10-01 Version 1.1.3
• 2020-08-10 Version 1.1.2
• 2020-06-27 Version 1.1.1
• 2020-05-24 Version 1.1.0
• 2020-04-11 Version 1.0.2
• 2020-03-14 Version 1.0.1
• 2020-02-24 Version 1.0.0
• 2019-10-07 Version 1.0.0rc9999
• 2019-06-14 Version 1.0.0rc5
• 2019-05-13 Version 1.0.0rc4
• 2019-04-14 Version 1.0.0rc3
• 2019-01-24 Version 1.0.0rc2
• 2018-09-10 Version 1.0.0rc1
• 2018-02-28 Version 0.06.4
• 2017-12-22 Version 0.06.3
• 2017-09-12 Version 0.06.2
• 2017-08-18 Version 0.06.1
• 2017-07-29 Version 0.06
• 2016-09-19 Version 0.05.1
• 2016-08-27 Version 0.05
• 2016-04-30 Version 0.03
• 2016-04-13 Version 0.02
• 2016-04-07 Version 0.01
34 Chapter 1. All pages
Srain Documentation, Release 1.3.0
1.9.1 2021-09-23 Version 1.3.0
• Features:
– Implement ISUPPORT parsing + the UTF8ONLY IRCv3 specification (srain#331), thanks to @progval
– Add support for RPL_UMODEIS (srain#331), thanks to @progval
– Make nick completion case-insensitive (srain#333), thanks to @progval
– Add button for inserting emoji (srain#279)
• Bug fixes:
– Fix configuration syntax errors caused by trailing commas (srain#330), thanks to @progval
1.9.2 2021-07-18 Version 1.2.4
• Bug fixes:
– Fix bug casued by srain#316 (srain#319)
– Fix crach when URL preview async task failed (srain#322)
1.9.3 2021-06-26 Version 1.2.3
• Bug fixes:
– Eliminate GDK warning (srain#316)
1.9.4 2021-05-30 Version 1.2.2
• Changed:
– Add libera.chat IRC network (srain#311)
– Updated Dutch translation (b6830e9)
• Bug fixes:
– Fix windows build (srain#300, srain#303)
1.9.5 2021-04-02 Version 1.2.1
• Features:
– Add Ukrainian translations (srain#292), thanks to @andmizyk
• Bug fixes:
– Minor fixes (srain#290)
1.9. Change Log 35
Srain Documentation, Release 1.3.0
1.9.6 2021-02-28 Version 1.2.0
• Features:
– Switch build system from Make to Meson (srain#266)
– Add FreeBSD implementations for srn_get_executable_{path,dir}, thanks to @wahjava
– Add /quote command for sending special IRC commands, thanks to @hno (srain#283)
– Add support for hiding server buffer (srain#287)
• Bug fixes:
– Fix an use-after-free BUG (srain#267)
– Fix implicit declaration error on some systems, thanks to @lgbaldoni (srain#270)
1.9.7 2020-10-01 Version 1.1.3
• Bug fixes:
– Fix an use-after-free BUG (srain#267)
1.9.8 2020-08-10 Version 1.1.2
Note: This release contains only improvement for MS Windows, user of other platform can ignore it.
• Features:
– Binary for MS Windows now can automatically built via Github Actions, thanks to @lifeibiren(srain#259), please refer to Windows for more details
• Changes:
– For ease of running on windows, Srain’s executable path is added to the search paths of {configura-tion,data} file. Thanks to @lifeibiren (srain#259)
1.9.9 2020-06-27 Version 1.1.1
• Changes:
– Improve auto-scroll policy of message list (srain#255)
• Bug fixes:
– Fix TLS certificate verification error on glib-networking 2.64.3 (srain#251)
– Fix crash when connecting to an invalid host (srain#234)
1.9.10 2020-05-24 Version 1.1.0
• Features:
– Support multiple selection of message (srain#138)
– Support jump to mentioned message (srain#243)
36 Chapter 1. All pages
Srain Documentation, Release 1.3.0
– Nickname will be highlighted when mentioned (srain#243)
– Auto build deb package (srain#238)
• Changes:
– Improve fcous control of UI
– Replace appdata with metainfo (srain#240)
– Validate metainfo with appstream-util (srain#242)
• Bug fixes:
– Some implicit declarations fixes (srain#236)
– Some typo fixes (srain#239)
1.9.11 2020-04-11 Version 1.0.2
• Features:
– Add MAN documentation (deaf723)
– Add more predefined IRC networks: DALnet, EFnet, IRCnet, Undernet and QuakeNet (srain#228)
• Changes:
– Build: Allow setting CC variable via environment (srain#224)
– Add channel related messages to corresponding buffer as possible (srain#149)
– Improve widget focus control (srain#229)
– Drop unused icons (6239fe5)
– Provide clearer error message when connecting (srain#233)
– Update gentoo installation documentation Gentoo (ceb5ca3)
• Bug fixes:
– Truncate long message before sendisg (srain#227)
– Deal with invalid UTF-8 string (50e7757)
– Fix incorrect user number of channel user list (srain#230)
– Fix incorrect icon install path (9f07380)
1.9.12 2020-03-14 Version 1.0.1
• Features:
– Auto rename to original nick when ghost quit (srain#198)
– Add hackint IRC network (srain#201), thanks to @kpcyrd
– Add Dutch translation (srain#215), thanks to @Vistaus
– Add two FAQs to documentation (srain#217)
– Add debian pack script (srain-contrib#1), thanks to @tomac4t. Please refer to Debian to build a debpackage
• Changes:
1.9. Change Log 37
Srain Documentation, Release 1.3.0
– Move continuous integration from travis CI to github actions (srain#203, srain#204), thanks to @tomac4t
– Make header bar buttons repect default belief (srain#205, srain#218)
• Bug fixes:
– Fix case sensitivity issue for IRC messages (srain#202), thanks to @hhirtz
– Fix invalid changelog section of appdata file (srain#214)
– Fix missing dependences in documentation (srain#216), thanks to @avoidr
1.9.13 2020-02-24 Version 1.0.0
• Changes:
– Some code cleanup
– Update Quick Start documentation
• Bug fixes:
– Allow Srain runs without dbus secrets service (srain#195)
– Fix nick generation logical (39ced08)
Note: 1.0.0 is the first stable release of Srain, enjoy!
1.9.14 2019-10-07 Version 1.0.0rc9999
• Features:
– Activate corresponding buffer when channel URL is clicked (srain#190)
– Command alias support (srain#188)
– List predefined servers via command, see /server for details (656f3e5)
• Changes:
– Replace all icons with freedesktop standard icons (srain#120)
• Bug fixes:
– Fix wrong usage of GError (srain#179)
– Fix image preview problem when image is hard to detect type (srain#163)
– Fix memory leak of pattern filter (9464a9e)
– Fix the breaking “abort sending” icon (srain#144)
– Fix the invite menu of user (9f98cbb)
1.9.15 2019-06-14 Version 1.0.0rc5
• Added:
– Regular expression pattern management using /pattern command
– Add command /filter & /unfilter for filtering message via pattern
38 Chapter 1. All pages
Srain Documentation, Release 1.3.0
– Add command /render & /unrender for rendering message via pattern
• Changed:
– Refactor detector module and rename it to render
– Refactor filter module
– Change project description
• Removed:
– Drop command /rignore & /unrignore
– Drop command /relay & /unrelay
1.9.16 2019-05-13 Version 1.0.0rc4
• Added:
– New dependency libsecret
– Add password storage support
– Add command line options --no-auto, used to require Srain not to automatically connect to servers
– Add russian translation, thanks to @tim77
– Allow user send slash(/) prefixed message
• Removed:
– Drop all password fields in configuration file
• Changed:
– Enable CSD(Client-Side Decoration) by default
– Update chinese translation
1.9.17 2019-04-14 Version 1.0.0rc3
1.9.18 2019-01-24 Version 1.0.0rc2
1.9.19 2018-09-10 Version 1.0.0rc1
1.9.20 2018-02-28 Version 0.06.4
• Changed:
– Change default application ID to im.srain.Srain
• Added:
– CTCP support, including request & response CLIENTINFO, FINGER, PING, SOURCE, TIME, VER-SION, USERINFO messages. DCC message is not yet supported. Use command /ctcp for sending aCTCP request
– Login method support, you can specify it by configuration file option server.login_method:
* sasl_plain: SASL PLAIN authentication support, will use server.user.username as iden-tity, and use server.user.passwd as password
1.9. Change Log 39
Srain Documentation, Release 1.3.0
– Added documentation Support Tables used to show Srain’s features, inspried by https://ircv3.net/software/clients.html
– Added a semantic version parser, not yet used
– Added appdata file which requier by application store, thanks to @cpba
– openSUSE package is available, please refer to openSUSE for details, thanks to @alois
– Flatpak package is available, please refer to Fedora for details, thanks to @cpba
• Improved:
– Fixed a logical error in IRC message parser: all parameters are equal whether matched by <middle> or<trailing>, thanks to @DanielOaks
– Improved connection state control, you can smoothly disconnect/quit from server even it is unresponsive
– Fixed truncated message output by /server list subcommand
– Fixed crash at g_type_check_instance() under GLib 2.54.3+
– Fixed: Do not free a SrianServerBuffer which has non-empty buffer
– Ensure the QUIT message can be sent before application shutdown
– Removed entry from desktop file, thanks to @TingPing
– Fixed grammer of join message, thanks to @raindev
– Re-enable CI for Srain:
1.9.21 2017-12-22 Version 0.06.3
• Changed:
– Configurable file option tls_not_verify in irc block in server block is renamed totls_noverify, old option name is still supported
– Command option tls-not-verify for /server and /connect is renamed to tls-noverify, old op-tion name is still supported
• Added:
– Connect popover supports connect to predefined server
– Join popover supports channel search
• Improved:
– Modified margin and padding of some widgets
– Improved the style of unread message counter
– Fixed markup parse error of decorator
– Fixed crashing while connecting from connect popover
– Fixed use after free while removing user
– Improved the performance and extensibility of user list
– Improved compatibility with older versions of GTK(> 3.16)
– Refactor the code of chat panel, helpful for the next development
40 Chapter 1. All pages
Srain Documentation, Release 1.3.0
1.9.22 2017-09-12 Version 0.06.2
• Added:
– mIRC color support, can be disabled via setting render_mirc_color option in chat block inserver block to false
• Improved:
– Better error reporting while operating the UI
– IRC URL can be opened directly within the application
– Text in input entry, connection panel and join panel will not be cleared while operation is not successful
– Fixed: in some cases, nickname registration will case infinity loop
– Decorator and filter now can process xml message
– Imporved the handling of channel topic
1.9.23 2017-08-18 Version 0.06.1
• Added:
– Added GPL copyright statements
– RPL_CHANNEL_URL (328) message support
– Command line options support, type srain -h for help message
– Support for Creating server and joining channel from IRC URL
– New dependency libsoup
– Add reconnect timer: if connection fails, Srain will wait for 5 seconds then try to connect again. If it stillfails, waiting time will increase by 5 second
• Improved:
– Fixed the crash when QUIT
– Fixed: avoid sending empty password
– More empty parameters checks
– Imporve server connection status control
1.9.24 2017-07-29 Version 0.06
• Changed:
– The third time of refactor ;-)
– New command parser, for the syntax, refer to Syntax.
– Changed the format of Chat log
– The /relay & /unrelay command doesn’t support custom delimiter, this function will be implemented aspython plugin in the future
– Use reStructuredText for document instead of Markdown
• Added:
1.9. Change Log 41
Srain Documentation, Release 1.3.0
– Message filter: mechanism for filtering message
– Message Decorator: mechanism for changing message
– Install script for Gentoo, thanks to @rtlanceroad !
– New command /rignore & /unrignore for ignore message using regular expression, thanks to @zwindl !
– Config file support
– Configurable log module, more convenient for developing and reporting issue
– New Return value type, for more friendly error reporting
– New command /server for IRC servers management
– Srain home page is available at: https://srain.im
– Srain help documentation is available at: https://doc.srain.im
• Removed:
– Remove libircclient dependence
• Improved:
– Improve reconnection stuff: auto reconnect when ping time out
– More accurate message mention
– Display preview image in correct size
– Any number of image links in message can be previewed
– HTTP(and some other protocols) link, domain name, email address and IRC channel name in topic andmessages can be rendered as hyper link
– The sent message can be merged to last sent message
– Fixed some bugs
1.9.25 2016-09-19 Version 0.05.1
• Create missing directory: $XDG_CACHE_HOME/srain/avatars
1.9.26 2016-08-27 Version 0.05
• Changed:
– Port to libircclient
* SSL connection support
* Server password support
* Channel password support
• Added:
– Convenience GtkPopover for connecting and joining
– Nick popmenu
– Translations: zh_CN
– Forward message
42 Chapter 1. All pages
Srain Documentation, Release 1.3.0
– Chat log
– Colorful user list icon
– Mentioned highlight
– Desktop notification
• Improved:
– More friendly User interface
– Stronger {upload,avatar} plugin
– Fixed a lot of bugs
1.9.27 2016-04-30 Version 0.03
• New interface between UI and IRC module
• Multi-server support
• Channel name is not case sensitive now
• /quit command will close all SrainChan of a server
• Fix GTK-Warning when close a SrainCHan
Note: 0.03 is a pre-release, some functions are no completed yet. it also has some undetected bugs.
1.9.28 2016-04-13 Version 0.02
• Bugs fixed
• Port to GTK+-3.20
Note: 0.02 is a pre-release, some functions are no completed yet. it also has some undetected bugs.
1.9.29 2016-04-07 Version 0.01
• Implement basic functions of a IRC client
• Themes: Silver Rain (light)
• Simple python plugin support:
– Auto upload image to pastebin (img.vim-cn.org)
– Get github avatar according nickname
– NB: plugin will separated from this repo in the future
• Image preview from URL
• Relay bot message transfrom
• Nick auto completion
• Combine message from same person
1.9. Change Log 43
Srain Documentation, Release 1.3.0
Note: 0.01 is a pre-release, some functions are no completed yet. it also has some undetected bugs.
1.10 Support Tables
• Basic IRC Client Support
• Client-to-Client Protocol (CTCP) Support
• IRCv3 Client Support
1.10.1 Basic IRC Client Support
Function SupportAuto reconnect YesMultiple connection YesTLS connection YesNick completion YesIgnore and filter YesChat log YesConfiguration file YesCommand YesmIRC color YesPlugin Unavailable
1.10.2 Client-to-Client Protocol (CTCP) Support
Message SupportACTION YesCLIENTINFO YesDCC NoFINGER YesPING YesSOURCE YesTIME YesVERSION YesUSERINFO Yes
44 Chapter 1. All pages
Srain Documentation, Release 1.3.0
1.10.3 IRCv3 Client Support
Feature SupportCAP v3.1 YesCAP v3.2 Yescap-notify Yesaccount-notify Noaccount-tag Noaway-notify Nobatch Nochghost Noecho-message Noextended-join Noinvite-notify NoMonitor Nomulti-prefix NoSASL v3.1 PLAIN,ECDSA-NIST256P-CHALLENGESASL v3.2 PLAIN,ECDSA-NIST256P-CHALLENGEserver-time Nostarttls Nosts Nouserhost-in-names No
1.10. Support Tables 45
Srain Documentation, Release 1.3.0
46 Chapter 1. All pages
CHAPTER 2
Indices and Tables
• search
47