diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 55 |
1 files changed, 48 insertions, 7 deletions
@@ -1,3 +1,35 @@ +//! catinator is a general purpose irc bot making crate. +//! +//! Most of the heavy lifting is done by the [irc](https://docs.rs/irc) crate, +//! but catinator adds useful high level utilities to make the bot making easier. +//! +//! Example: +//! ```no_run +//! #[tokio::main] +//! async fn main() { +//! tracing_subscriber::fmt::init(); +//! +//! // Initialize the bot, loading the config and establishing the connection +//! let mut bot = catinator::Bot::new().await.unwrap(); +//! +//! // Setup any modules that require it. +//! let wolfram_alpha = catinator::hooks::wolfram_alpha::WolframAlpha::new(&bot) +//! .expect("failed to initialize WolframAlpha command"); +//! +//! // Call the catinator macro to setup the hooks, matchers and commands +//! catinator::catinator![ +//! // For example add the sasl hook to handle sasl authentication +//! hook("sasl", "Handle Authentication.", AUTHENTICATE, catinator::hooks::sasl), +//! +//! // Add a matcher that executes on a specific regex +//! matcher("shifty_eyes", ">.>", r"^\S{3}$", catinator::hooks::shifty_eyes), +//! +//! // Add an async command that calls a method on the previously instantiated struct. +//! async command("wa", "Returns Wolfram Alpha results for a query", wolfram_alpha.wa), +//! ]; +//! } +//! ``` + #![cfg_attr(all(test, feature = "bench"), feature(test))] #[cfg(all(test, feature = "bench"))] extern crate test; @@ -10,22 +42,24 @@ pub mod config; pub mod hooks; pub mod util; +// Rexport of the catinator proc macros pub use macros::catinator; -#[macro_export] -macro_rules! reply { - ( $msg:expr, $text:expr ) => { - bot.send_privmsg($msg.response_target().unwrap(), $text.as_str())?; - }; -} - +/// The struct handling bot actions and configuration pub struct Bot { + /// The base config of the bot pub config: config::Config, + /// The figment the config is extracted from pub figment: figment::Figment, + /// The irc client object, used to send messages etc + /// It is recommended to use the methods directly on the Bot struct instead. pub irc_client: irc::client::Client, } impl Bot { + /// Initializes the bot. + /// Loads configuration from `CATINATOR_` environment variables and the `config.toml` file + /// Starts the connection to the irc server. pub async fn new() -> Result<Bot> { let figment = config::Config::figment(); let config: config::Config = figment.extract().context("failed to extract config")?; @@ -46,10 +80,14 @@ impl Bot { Ok(bot) } + /// Get the bots figment to use when building your own configuration. + /// See [config] pub fn figment(&self) -> &figment::Figment { &self.figment } + /// Initialize a sasl connection, you usually don't need + /// to run this yourself as it is done during [Bot::new]. pub async fn sasl_init(&self) -> Result<()> { self.irc_client .send_cap_req(&vec![irc::client::prelude::Capability::Sasl])?; @@ -65,6 +103,7 @@ impl Bot { Ok(()) } + /// Send a privmsg to the target `#channel` or `user` pub fn send_privmsg( &self, target: &str, @@ -73,6 +112,7 @@ impl Bot { self.irc_client.send_privmsg(target, message) } + /// Send a notice to the target `#channel` or `user` pub fn send_notice( &self, target: &str, @@ -81,6 +121,7 @@ impl Bot { self.irc_client.send_notice(target, message) } + /// Send an action (`/me`) to the target `#channel` or `user` pub fn send_action( &self, target: &str, |