Preferences 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

# Every configuration file should have a version, altough it is not used yet.
version = "0.06.3"

# Terminal log configuration, which is user doesn't need to care about.
# 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 "info" log level
    warn_targets    = [""]  # Files with "warn" log level
    error_targets   = []    # Files with "error" log level
}

# Application configuration.
application:
{
    theme = "default"   # String; Theme; Available values: "default"
}

# IRC Server configuration, this group can also appear in server_list.
server:
{
    # User information
    user =
    {
        nickname = "Zaidan"
        username = "Srain"
        realname = "Can you can a can?"
        # passwd = "yourpassword"   # String, User password
    }

    # Default messages for performing specified action
    default_messages =
    {
        part = "Leaving"
        kick = "Kick"
        away = "Away"
        quit = "El Psy Congroo."
    }

    # IRC configuration
    irc =
    {
        tls = false             # 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
        # ipv6 = false
        # sasl = false
        encoding = "utf-8"      # String; Encoding of IRC server, to get
                                # all available value of encoding, check the
                                # output of ``iconv --list``.
    }

    # Chat configuration, this group can also appear in chat_list.
    chat =
    {
        notify = true               # Bool; Enable desktop notification
        show_topic = true           # Bool; Show topic
        show_avatar = false         # Bool; Show user avater
        show_user_list = true       # Bool; Show user list
        preview_image = false       # Bool; Auto preview image from URL, WARNING:
                                    # This option may EXPOSE your IP address
        render_mirc_color = true    # Bool; Render mirc color
        # log = true                # Bool; Save chat log
    }

    # Specified chat configuration, every element in list should have a unique
    # "name".
    chat_list =
        (
            {
                # ``name`` are 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``, ``host``, ``port`` are necessary for a ``server`` group
        # in ``server_list``, otherwise you can not connect to it.
        name = "freenode"          # String; The unique name of server
        host = "irc.freenode.org"  # String; Host of IRC server
        port = 6697                # Integer; Port of IRC Server
        # passwd = ""              # String; Connection password, default unset  or empty

        irc =
        {
            tls = true
            encoding = "utf-8"
        }
    },
    {
        name = "GIMPNet"
        host = "irc.gimp.org"
        port = 6697

        irc =
        {
            tls = true
            encoding = "utf-8"
        }
    },
    {
        name = "OFTC"
        host = "irc.oftc.net"
        port = 6697

        irc =
        {
            tls = true
            encoding = "utf-8"
        }
    },
    {
        name = "Rizon"
        host = "irc.rizon.net"
        port = 6697

        irc =
        {
            tls = true
            encoding = "utf-8"
        }
    },
    {
        name = "localhost"
        host = "localhost"
        port = 6667

        irc =
        {
            tls = false
        }
    }

# TODO: More predefined servers
)