diff options
Diffstat (limited to '')
| -rw-r--r-- | macros/Cargo.toml | 9 | ||||
| -rw-r--r-- | macros/src/lib.rs | 81 | ||||
| -rw-r--r-- | macros/src/macro_types/mod.rs | 4 |
3 files changed, 90 insertions, 4 deletions
diff --git a/macros/Cargo.toml b/macros/Cargo.toml index 30019d7..a833e36 100644 --- a/macros/Cargo.toml +++ b/macros/Cargo.toml @@ -10,3 +10,12 @@ proc-macro = true syn = { version = "1", features = ["parsing"] } proc-macro2 = "1" quote = "1" + +[dev-dependencies] +tokio = "*" +futures = "*" +irc = { version = "0.15", features = ["json", "tls-rust"], default_features = false } +tracing = "*" +anyhow = "*" +regex = "*" +catinator = { path = "../" } diff --git a/macros/src/lib.rs b/macros/src/lib.rs index 5ccf1bb..0ec317e 100644 --- a/macros/src/lib.rs +++ b/macros/src/lib.rs @@ -58,6 +58,69 @@ fn generate_help(items: &Items) -> proc_macro2::TokenStream { gen.into() } +/// Main entrypoint to the bot +/// +/// ```no_run +/// # extern crate tokio; +/// # use macros::catinator; +/// # use anyhow::Result; +/// # +/// # fn function(bot: &catinator::Bot, msg: irc::client::prelude::Message) -> Result<()> { +/// # Ok(()) +/// # } +/// # +/// #[tokio::main] +/// async fn main() { +/// catinator!( +/// hook("name", "A short description", PRIVMSG, function) +/// command("name", "A short description", function) +/// matcher("name", "A short description", r"^\[.*?\]$", function) +/// ); +/// } +/// ``` +/// +/// # Functions +/// All the functions share a similar pattern, +/// The first two arguments are the name and description respectively, +/// the last argument is the function that gets executed. +/// +/// The function must of of the following type: +/// ``` +/// fn hook(bot: &catinator::Bot, msg: irc::client::prelude::Message) -> anyhow::Result<()> { +/// Ok(()) +/// } +/// ``` +/// +/// ## hook +/// Hooks execute a function when a specific IRC Command is received, +/// this allows for great flexibility in hooking into IRC for Authentication and the likes. +/// +/// ```ignore +/// hook("name", "description", COMMAND, function) +/// ``` +/// +/// PRIVMSG is an IRC Command like PRIVMSG or AUTHENTICATE +/// Any of the enum variants of [the irc crate](https://docs.rs/irc/0.15.0/irc/client/prelude/enum.Command.html) +/// should work. +/// +/// ## command +/// A Command is command that can be executed in any PRIVMSG and is +/// prefixed with the prefix configured in the config.toml file +/// +/// ```ignore +/// command("name", "description", function) +/// ``` +/// Would be ":name <whatever>" in an irc channel or private message. +/// +/// ## matcher +/// A matcher matches on a PRIVMSG using regex. +/// +/// ```ignore +/// matcher("name", "description", r"regex", function) +/// ``` +/// +/// The [regex crate](https://docs.rs/regex) is used for matching, see it's documentation for details. +/// #[proc_macro] pub fn catinator(tokens: TokenStream) -> TokenStream { let items = parse_macro_input!(tokens as Items); @@ -156,6 +219,24 @@ pub fn catinator(tokens: TokenStream) -> TokenStream { return gen.into(); } + +/// Match on a privmsg and execute the function block on it +/// +/// # Examples +/// ``` +/// # use anyhow::Result; +/// # use irc::client::prelude::*; +/// # use macros::privmsg; +/// # +/// # pub fn hook(bot: &catinator::Bot, msg: Message) -> Result<()> { +/// privmsg!(msg, { +/// bot.send_privmsg( +/// msg.response_target().unwrap(), +/// "bla", +/// )?; +/// }) +/// # } +/// ``` #[proc_macro] pub fn privmsg(tokens: TokenStream) -> TokenStream { use crate::macro_types::privmsg::Item; diff --git a/macros/src/macro_types/mod.rs b/macros/src/macro_types/mod.rs index 818cea7..0e55dc4 100644 --- a/macros/src/macro_types/mod.rs +++ b/macros/src/macro_types/mod.rs @@ -35,7 +35,6 @@ impl Parse for Items { } } -#[derive(Debug)] pub enum Item { Command(Command), Hook(Hook), @@ -61,7 +60,6 @@ impl Parse for Item { } } -#[derive(Debug)] pub struct Command { pub name: LitStr, pub description: LitStr, @@ -111,7 +109,6 @@ impl Parse for Command { } } -#[derive(Debug)] pub struct Hook { pub name: LitStr, pub description: LitStr, @@ -193,7 +190,6 @@ impl Parse for Hook { } } -#[derive(Debug)] pub struct Matcher { pub name: LitStr, pub description: LitStr, |