Struct irc::client::data::config::Config

pub struct Config {
    pub owners: Vec<String>,
    pub nickname: Option<String>,
    pub nick_password: Option<String>,
    pub alt_nicks: Vec<String>,
    pub username: Option<String>,
    pub realname: Option<String>,
    pub server: Option<String>,
    pub port: Option<u16>,
    pub password: Option<String>,
    pub use_tls: Option<bool>,
    pub cert_path: Option<String>,
    pub client_cert_path: Option<String>,
    pub client_cert_pass: Option<String>,
    pub encoding: Option<String>,
    pub channels: Vec<String>,
    pub umodes: Option<String>,
    pub user_info: Option<String>,
    pub version: Option<String>,
    pub source: Option<String>,
    pub ping_time: Option<u32>,
    pub ping_timeout: Option<u32>,
    pub burst_window_length: Option<u32>,
    pub max_messages_in_burst: Option<u32>,
    pub should_ghost: bool,
    pub ghost_sequence: Option<Vec<String>>,
    pub use_mock_connection: bool,
    pub mock_initial_value: Option<String>,
    pub channel_keys: HashMap<String, String>,
    pub options: HashMap<String, String>,
    // some fields omitted
}

Configuration for IRC clients.

Building a configuration programmatically

For some use cases, it may be useful to build configurations programmatically. Since Config is an ordinary struct with public fields, this should be rather straightforward. However, it is important to note that the use of Config::default() is important, even when specifying all visible fields because Config keeps track of whether it was loaded from a file or programmatically defined, in order to produce better error messages. Using Config::default() as below will ensure that this process is handled correctly.

use irc::client::prelude::Config;

let config = Config {
    nickname: Some("test".to_owned()),
    server: Some("irc.example.com".to_owned()),
    ..Config::default()
};

Loading a configuration from a file

The standard method of using a configuration is to load it from a TOML file. You can find an example TOML configuration in the README, as well as a minimal example with code for loading the configuration below.

TOML (config.toml)

nickname = "test"
server = "irc.example.com"

Rust

use irc::client::prelude::Config;

let config = Config::load("config.toml").unwrap();

Fields

owners: Vec<String>

A list of the owners of the client by nickname (for bots).

nickname: Option<String>

The client's nickname.

nick_password: Option<String>

The client's NICKSERV password.

alt_nicks: Vec<String>

Alternative nicknames for the client, if the default is taken.

username: Option<String>

The client's username.

realname: Option<String>

The client's real name.

server: Option<String>

The server to connect to.

port: Option<u16>

The port to connect on.

password: Option<String>

The password to connect to the server.

use_tls: Option<bool>

Whether or not to use TLS. Clients will automatically panic if this is enabled without TLS support.

cert_path: Option<String>

The path to the TLS certificate for this server in DER format.

client_cert_path: Option<String>

The path to a TLS certificate to use for CertFP client authentication in DER format.

client_cert_pass: Option<String>

The password for the certificate to use in CertFP authentication.

encoding: Option<String>

The encoding type used for this connection. This is typically UTF-8, but could be something else.

channels: Vec<String>

A list of channels to join on connection.

umodes: Option<String>

User modes to set on connect. Example: "+RB -x"

user_info: Option<String>

The text that'll be sent in response to CTCP USERINFO requests.

version: Option<String>

The text that'll be sent in response to CTCP VERSION requests.

source: Option<String>

The text that'll be sent in response to CTCP SOURCE requests.

ping_time: Option<u32>

The amount of inactivity in seconds before the client will ping the server.

ping_timeout: Option<u32>

The amount of time in seconds for a client to reconnect due to no ping response.

burst_window_length: Option<u32>

The length in seconds of a rolling window for message throttling. If more than max_messages_in_burst messages are sent within burst_window_length seconds, additional messages will be delayed automatically as appropriate. In particular, in the past burst_window_length seconds, there will never be more than max_messages_in_burst messages sent.

max_messages_in_burst: Option<u32>

The maximum number of messages that can be sent in a burst window before they'll be delayed. Messages are automatically delayed as appropriate.

should_ghost: bool

Whether the client should use NickServ GHOST to reclaim its primary nickname if it is in use. This has no effect if nick_password is not set.

ghost_sequence: Option<Vec<String>>

The command(s) that should be sent to NickServ to recover a nickname. The nickname and password will be appended in that order after the command. E.g. ["RECOVER", "RELEASE"] means RECOVER nick pass and RELEASE nick pass will be sent in that order.

use_mock_connection: bool

Whether or not to use a fake connection for testing purposes. You probably will never want to enable this, but it is used in unit testing for the irc crate.

mock_initial_value: Option<String>

The initial value used by the fake connection for testing. You probably will never need to set this, but it is used in unit testing for the irc crate.

channel_keys: HashMap<String, String>

A mapping of channel names to keys for join-on-connect.

options: HashMap<String, String>

A map of additional options to be stored in config.

Implementations

impl Config

pub fn load<P: AsRef<Path>>(path: P) -> Result<Config>

Loads a configuration from the desired path. This will use the file extension to detect which format to parse the file as (json, toml, or yaml). Using each format requires having its respective crate feature enabled. Only json is available by default.

pub fn save<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Saves a configuration to the desired path. This will use the file extension to detect which format to parse the file as (json, toml, or yaml). Using each format requires having its respective crate feature enabled. Only json is available by default.

pub fn is_owner(&self, nickname: &str) -> bool

Determines whether or not the nickname provided is the owner of the bot.

pub fn nickname(&self) -> Result<&str>

Gets the nickname specified in the configuration.

pub fn nick_password(&self) -> &str

Gets the bot's nickserv password specified in the configuration. This defaults to an empty string when not specified.

pub fn alternate_nicknames(&self) -> &[String]

Gets the alternate nicknames specified in the configuration. This defaults to an empty vector when not specified.

pub fn username(&self) -> &str

Gets the username specified in the configuration. This defaults to the user's nickname when not specified.

pub fn real_name(&self) -> &str

Gets the real name specified in the configuration. This defaults to the user's nickname when not specified.

pub fn server(&self) -> Result<&str>

Gets the address of the server specified in the configuration.

pub fn port(&self) -> u16

Gets the port of the server specified in the configuration. This defaults to 6697 (or 6667 if use_tls is specified as false) when not specified.

pub fn password(&self) -> &str

Gets the server password specified in the configuration. This defaults to an empty string when not specified.

pub fn use_tls(&self) -> bool

Gets whether or not to use TLS with this connection. This defaults to true when not specified.

pub fn cert_path(&self) -> Option<&str>

Gets the path to the TLS certificate in DER format if specified.

pub fn client_cert_path(&self) -> Option<&str>

Gets the path to the client authentication certificate in DER format if specified.

pub fn client_cert_pass(&self) -> &str

Gets the password to the client authentication certificate.

pub fn encoding(&self) -> &str

Gets the encoding to use for this connection. This requires the encode feature to work. This defaults to UTF-8 when not specified.

pub fn channels(&self) -> &[String]

Gets the channels to join upon connection. This defaults to an empty vector if it's not specified.

pub fn channel_key(&self, chan: &str) -> Option<&str>

Gets the key for the specified channel if it exists in the configuration.

pub fn umodes(&self) -> &str

Gets the user modes to set on connect specified in the configuration. This defaults to an empty string when not specified.

pub fn user_info(&self) -> &str

Gets the string to be sent in response to CTCP USERINFO requests. This defaults to an empty string when not specified.

pub fn version(&self) -> &str

Gets the string to be sent in response to CTCP VERSION requests. This defaults to irc:version:env when not specified. For example, irc:0.12.0:Compiled with rustc

pub fn source(&self) -> &str

Gets the string to be sent in response to CTCP SOURCE requests. This defaults to https://github.com/aatxe/irc when not specified.

pub fn ping_time(&self) -> u32

Gets the amount of time in seconds for the interval at which the client pings the server. This defaults to 180 seconds when not specified.

pub fn ping_timeout(&self) -> u32

Gets the amount of time in seconds for the client to disconnect after not receiving a ping response. This defaults to 10 seconds when not specified.

pub fn burst_window_length(&self) -> u32

The amount of time in seconds to consider a window for burst messages. The message throttling system maintains the invariant that in the past burst_window_length seconds, the maximum number of messages sent is max_messages_in_burst. This defaults to 8 seconds when not specified.

pub fn max_messages_in_burst(&self) -> u32

The maximum number of messages that can be sent in a burst window before they'll be delayed. Messages are automatically delayed until the start of the next window. The message throttling system maintains the invariant that in the past burst_window_length seconds, the maximum number of messages sent is max_messages_in_burst. This defaults to 15 messages when not specified.

pub fn should_ghost(&self) -> bool

Gets whether or not to attempt nickname reclamation using NickServ GHOST. This defaults to false when not specified.

pub fn ghost_sequence(&self) -> Option<&[String]>

Gets the NickServ command sequence to recover a nickname. This defaults to ["GHOST"] when not specified.

pub fn get_option(&self, option: &str) -> Option<&str>

Looks up the specified string in the options map.

pub fn use_mock_connection(&self) -> bool

Gets whether or not to use a mock connection for testing. This defaults to false when not specified.

pub fn mock_initial_value(&self) -> &str

Gets the initial value for the mock connection. This defaults to false when not specified. This has no effect if use_mock_connection is not true.

Trait Implementations

impl Clone for Config

pub fn clone(&self) -> Config

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Config

pub fn default() -> Config

Returns the "default value" for a type.

impl<'de> Deserialize<'de> for Config

pub fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<Config> for Config

pub fn eq(&self, other: &Config) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &Config) -> bool

This method tests for !=.

impl Serialize for Config

pub fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Config