Configuration Manual

Srain uses Libconfig to process configuration file.

Configuration File

The path of system wide configuration file builtin.cfg depends on the compile flag --config-dir, default to be /etc/srain.

The path of user wide configuration file srain.cfg is $XDG_CONFIG_HOME/srain, usually it is ~/.config/srain.

The difference between system wide and user wide configuration file is the priority, The user wide configuration always overwrite the one in system wide configuration. For more details about priority, refer to Priority and Fallback.

Syntax

For the syntax of configuration file, please refer to Libconfig’s documentation: Configuration Files

For an example configuration, refer to All Configurable Items.

Priority and Fallback

A group is a collection of configurations. The same group in different place have different priority.

log: {}
application: {}
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 can appear at the top level of configuration file, or be an element of server-list list with a unique name. The top level server is often used to specify the global configuration, and server-list is used to specify specified IRC servers.

The configuration in server-list can overwrite the top level server, and if an option is not specified in server-list, It will fallback to server.

Another similar group is chat, chat contains configuration of chat panel, such as whether to show topic, whether to save chat log and etc. Every server group can contain a chat group and a chat-list list. Elements in chat-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 specified chat and has higher priority.

As mentioned above, The priority of user configuration is always higher than system’s, so we can get the priority sorting 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)

All Configurable Items

Here is the default system wide configuration file used by Srain, all configurable items are already listed here. you can make 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 remove it 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-list before using
# Srain built-in configuration file
# Application configuration.

version = "0.06.4"          # String; Every configuration file should have a
                            # version, altough it is not used yet
# id = "im.srain.Srain"       # The identifier for Srain
theme = "default-bubble"    # String; Theme; Available values: default
csd = false                 # Bool; Whether enable Client-Side Decoration
send-on-ctrl-enter = false  # Bool; Send messsage on CTRL+Enter pressed
auto-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 output
    prompt-file = false     # Bool; Display the filename of the file which log
                            # statement is located
    prompt-function = true  # Bool; As aboved, function name
    prompt-line = false     # Bool; As aboved, line number

    # String array; Specify the log level of a group of files
    debug-targets   = []    # Files with debug log level
    info-targets    = []    # Files with information log level
    warn-targets    = [""]  # Files with warning log level
    error-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
                                # - pass: Login with PASS command
                                # (TODO: not supported yet)
                                # - nickserv: Login with NICKSERV command
                                # (TODO: not supported yet)
                                # - msg-nickserv: Login with /msg NickServ identify
                                # (TODO: not supported yet)
                                # - sasl-plain: Login with SASL PLAIN mechanism

            # For method "pass"
            # pass-password = ""    # String; User password, default unset

            # For method "nickserv" and "msg-nickserv"
            # nickserv-password = ""    # String; User password, default unset

            # For method "sasl-plain"
            # sasl-identify = ""    # String; User password, default unset
            # sasl-password = ""    # String; User password, default unset
        }

        # Default messages for performing specified action
        part-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 storage
        notify = 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 topic
        show-avatar = false             # Bool; Show user avater
        show-user-list = true           # Bool; Show user list
        render-mirc-color = true        # Bool; Render mirc color
        nick-completion-suffix = ":"    # String; Suffix of completed nick name
                                        # e.g. "nick: msg"

        preview-url = true          # Bool; Show previewer for every URL
        auto-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 =
(
    {
        # ``name``, ``addresses`` are necessary for a ``server`` group
        # in ``server-list``, otherwise you can not connect to it.
        name = "freenode"           # String; The unique name of server
        addresses = [
            "irc.freenode.net:6697",
            "chat.freenode.net:6697",
            "irc.freenode.org:6697",
            "chat.freenode.org: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
        # password = ""             # String; Connection password, default unset
        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 = true
        encoding = "utf-8"
    },
    {
        name = "OFTC"
        addresses = ["irc.oftc.net:6697"]
        tls = true
        encoding = "utf-8"
    },
    {
        name = "Rizon"
        addresses = ["irc.rizon.net:6697"]

        tls = true
        encoding = "utf-8"
    },
    {
        name = "localhost"
        addresses = ["localhost:6667", "127.0.0.1:6667"]
        tls = false
    }

# TODO: More predefined servers
)