diff options
Diffstat (limited to 'src/config.rs')
| -rw-r--r-- | src/config.rs | 120 |
1 files changed, 118 insertions, 2 deletions
diff --git a/src/config.rs b/src/config.rs index 4429184..ec79591 100644 --- a/src/config.rs +++ b/src/config.rs @@ -1,3 +1,101 @@ +//! The bots main configuration is housed in the [Config] struct. +//! +//! The configuration is by default loaded from `config.toml` in the current directory, +//! or from the path that is set by the `CATINATOR_CONFIG` variable. Environment +//! variables prefixed with `CATINATOR_` will also be loaded as configuration. +//! +//! The configuration uses [figment](https://docs.rs/figment) for it's configuration. +//! +//! # Profiles +//! The configuration is setup to use different profiles depending on how it is compiled. +//! +//! The main configuration file `config.toml` specifies the `default` profile which +//! sets default variables for most things. The `release` profile is also specified +//! in `config.toml` and selected when being built with the `--release` flag. +//! Additional configuration to set a different user while testing can be set in +//! the `debug` profile, which is selected if built without the `--release` flag. +//! +//! When compiled in release mode only the the `config.toml` or `CATINATOR_CONFIG` +//! and environment variables will be loaded. +//! +//! When compiled in debug mode an additional `config.debug.toml` is loaded +//! from the current directory. You can use this to set different channels and +//! nickname for testing. +//! +//! While developing this library / bot the `config.debug.toml` is also ignored from git. +//! +//! # Example +//! ```toml +//! [default] +//! [default.user] +//! # The username used for sasl and nickserv authentication +//! username = "catinator" +//! realname = "moaw" +//! +//! [default.server] +//! hostname = "<host>" +//! port = 6697 +//! tls = true +//! +//! # Enabled sasl, also requires user.password to be set +//! sasl = true +//! +//! [default.settings] +//! # The prefix to use for commands +//! # Example: ":about" +//! prefix = ':' +//! +//! [release] +//! [release.user] +//! # The backslash has to be escaped here +//! nickname = "\\__{^-_-^}" +//! [release.server] +//! channels = ["<channel 1>", "<channel 2>"] +//! ``` +//! +//! # Configuration for hooks +//! +//! If you write hooks that require some configuration you can use the +//! [`Bot::figment`](crate::Bot::figment) function to retrieve the figment and extract your own +//! configuration. +//! +//! ## Example: +//! ``` +//! use serde::{Serialize, Deserialize}; +//! use anyhow::{Context, Result}; +//! use irc::client::prelude::*; +//! use figment::providers::Env; +//! +//! use catinator::Bot; +//! +//! // Define a struct to initialize that contains your configuration +//! // you need to derive serde's Serialize and Deserialize on it +//! #[derive(Clone, Debug, Deserialize, Serialize)] +//! pub struct WolframAlpha { +//! wa_api_key: String, +//! } +//! +//! impl WolframAlpha { +//! // Impl a `new()` function that gets passed a reference to the +//! // bot, or just a reference to the figment. +//! pub fn new(bot: &Bot) -> Result<WolframAlpha> { +//! // Get the figment, we have to clone it here to merge our own env var config in. +//! bot.figment +//! .clone() +//! .merge(Env::prefixed("CATINATOR_")) +//! // Extract the config into the return type of this function +//! .extract() +//! .context("failed to extract wolfram alpha config") +//! } +//! +//! pub async fn wa(&self, bot: &Bot, msg: Message) -> Result<()> { +//! // Impl your command, hook or matcher here to allow it to access it's configuration +//! +//! Ok(()) +//! } +//! } +//! ``` + use serde::{Deserialize, Serialize}; use figment::{ @@ -7,10 +105,14 @@ use figment::{ }; use tracing::debug; +/// Configuration for the Bot #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Deserialize, Serialize)] pub struct Config { + /// Settings related to the [User] pub user: User, + /// Settings related to the [Server] pub server: Server, + /// General bot related [Settings] pub settings: Settings, } @@ -30,24 +132,36 @@ impl From<Config> for irc::client::prelude::Config { } } +/// User related configuration #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Deserialize, Serialize)] pub struct User { + /// The displayed nickname of the bot pub nickname: String, + /// The username used for authentication pub username: String, + /// The password used for authentication + /// Defaults to None #[serde(default)] pub password: Option<String>, + /// The bots realname pub realname: String, } +/// Connection info for the irc server #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Deserialize, Serialize)] pub struct Server { + /// Hostname to connect to pub hostname: String, + /// Port to connect to (default: 6697 TLS) #[serde(default = "default_port")] pub port: u16, + /// Wether or not to use TLS (default: true) #[serde(default = "default_tls")] pub tls: bool, + /// Enable or disable sasl authentication (default: false) #[serde(default)] pub sasl: bool, + /// Channels to join (default: []) #[serde(default)] pub channels: Vec<String>, } @@ -60,8 +174,10 @@ const fn default_tls() -> bool { true } +/// General settings for the bot #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Deserialize, Serialize)] pub struct Settings { + /// The prefix used for commands like `:about` (default: ':') #[serde(default = "default_prefix")] pub prefix: char, // pub wa_api_key: String, @@ -72,12 +188,12 @@ const fn default_prefix() -> char { } impl Config { - // Allow the configuration to be extracted from any `Provider`. + /// Allow the configuration to be extracted from any [`figment::Provider`]. pub fn from<T: Provider>(provider: T) -> Result<Config, Error> { Figment::from(provider).extract() } - // Provide a default provider, a `Figment`. + /// Provide a default provider, a `Figment`. pub fn figment() -> Figment { use figment::providers::Env; |