feat: add filter::command with parameter extraction

- add command() filter supporting :param, :param?, *param, *param? patterns
- add router module with CommandParams for extracted parameters
- convert ferogram-macros to proc-macro crate (syn, quote)
- export Resource and CommandParams in prelude

Author: AndrielFR

ferogram-macros/Cargo.toml

@@ -10,4 +10,9 @@ repository.workspace = true
 keywords.workspace = true
 edition.workspace = true
 
+[lib]
+proc-macro = true
+
 [dependencies]
+syn = "2.0"
+quote = "1.0"

ferogram-macros/src/lib.rs

@@ -1,14 +1 @@
-pub fn add(left: u64, right: u64) -> u64 {
-    left + right
-}
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn it_works() {
-        let result = add(2, 2);
-        assert_eq!(result, 4);
-    }
-}

ferogram/examples/dispatcher.rs

@@ -11,8 +11,8 @@
 
 use std::error::Error;
 
-use ferogram::{Dispatcher, filter, handler, prelude::ConnectionExt};
-use grammers::{Client, client::UpdatesConfiguration, update::Message};
+use ferogram::prelude::*;
+use grammers::{Client, client::UpdatesConfiguration, message::InputMessage, update::Message};
 
 #[tokio::main(flavor = "multi_thread")]
 async fn main() -> Result<(), Box<dyn Error>> {
@@ -23,13 +23,24 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
     // Build and run the dispatcher.
     Dispatcher::builder()
-        .add_handler(
-            handler::new_message(filter::text("hi")).then(|message: Message| async move {
-                message.reply(message.text()).await?;
+        .add_handler(handler::new_message(filter::command("/start :id")).then(
+            |message: Message, params: CommandParams| async move {
+                let Ok(id) = params.get_parsed::<i64>("id") else {
+                    let id = params.get("id").unwrap();
+
+                    message
+                        .reply(InputMessage::new().text(format!("Invalid id: {id}")))
+                        .await?;
+                    return Ok(());
+                };
+
+                message
+                    .reply(InputMessage::new().text(id.to_string()))
+                    .await?;
 
                 Ok(())
-            }),
-        )
+            },
+        ))
         .build()
         .run(
             pool,

ferogram/src/filter/default.rs

@@ -5,9 +5,12 @@
 
 //! Default and useful filters.
 
+use std::collections::HashMap;
+
 use grammers::{Client, media::Media, peer::Peer, tl, update::Update};
 
 use super::{AsyncMarker, FilterExt, Flow, IntoFilter, SyncMarker};
+use crate::router::CommandParams;
 
 /// Always passing filter, it doesn't check for anything.
 pub fn always(_: Client, _: Update) -> bool {
@@ -41,45 +44,162 @@ pub fn not<Marker>(filter: impl IntoFilter<Marker>) -> impl IntoFilter<AsyncMark
 }
 
 /// Pass if the message text contains the specified pattern.
-pub fn text(pat: &'static str) -> impl IntoFilter<SyncMarker> {
+pub fn text(pattern: &'static str) -> impl IntoFilter<SyncMarker> {
     move |_, update| match update {
         Update::NewMessage(message) | Update::MessageEdited(message) => {
-            message.text().contains(pat)
+            message.text().contains(pattern)
         }
         _ => false,
     }
 }
 
 /// Pass if the message text or query data matches the specified pattern.
-pub fn regex(pat: &'static str) -> impl IntoFilter<SyncMarker> {
+pub fn regex(pattern: &'static str) -> impl IntoFilter<SyncMarker> {
     move |_, update| match update {
         Update::NewMessage(message) | Update::MessageEdited(message) => {
-            let re = regex::Regex::new(pat).unwrap();
-
+            let re = regex::Regex::new(pattern).unwrap();
             re.is_match(message.text())
         }
         Update::CallbackQuery(query) => {
-            let re = regex::bytes::Regex::new(pat).unwrap();
-
+            let re = regex::bytes::Regex::new(pattern).unwrap();
             re.is_match(query.data())
         }
         Update::InlineQuery(query) => {
-            let re = regex::Regex::new(pat).unwrap();
-
+            let re = regex::Regex::new(pattern).unwrap();
             re.is_match(query.text())
         }
         _ => false,
     }
 }
 
+/// Pass if the message text matches the specified command pattern.
+///
+/// It supports parameters, which are:
+/// - `:param`: a one-word required parameter.
+/// - `:param?`: a one-word optional parameter.
+/// - `*param`: a multiple-word required parameter.
+/// - `*param?`: a multiple-word optional parameter.
+///
+/// Note: optional parameters (those ending in `?`) can only be added at the
+/// end of patterns, which also means that required parameters cannot follow
+/// optional parameters, otherwise it'll panic.
+///
+/// # Injects:
+/// * [`CommandParams`]: extracted params.
+///
+/// # Examples
+///
+/// ```
+/// use ferogram::prelude::*;
+/// handler::new_message(filter::command("/profile :id?"))
+/// ```
+pub fn command(pattern: &'static str) -> impl IntoFilter<SyncMarker> {
+    let parts = pattern.split_whitespace().collect::<Vec<_>>();
+    if parts.is_empty() {
+        panic!("Invalid pattern '{pattern}': it needs to have at least one word");
+    }
+
+    let mut pat = format!("^{}", regex::escape(parts[0]));
+
+    let mut seen_multiple = false;
+    let mut seen_optional = false;
+
+    for part in &parts[1..] {
+        let is_optional = part.ends_with('?');
+
+        if seen_multiple {
+            panic!(
+                "Invalid pattern '{pattern}': parameter '{part}' cannot follow a multiple parameter"
+            );
+        }
+
+        if let Some(stripped) = part.strip_prefix(':') {
+            if is_optional {
+                seen_optional = true;
+
+                let name = &stripped[..stripped.len() - 1];
+                pat.push_str(&format!(r"(?:\s+(?P<{name}>\S+))?"));
+            } else {
+                if seen_optional {
+                    panic!(
+                        "Invalid pattern '{pattern}': mandatory parameter '{part}' cannot follow an optional parameter"
+                    );
+                }
+
+                let name = stripped;
+                pat.push_str(&format!(r"\s+(?P<{name}>\S+)"));
+            }
+        } else if let Some(stripped) = part.strip_prefix('*') {
+            seen_multiple = true;
+
+            if is_optional {
+                seen_optional = true;
+
+                let name = &stripped[..stripped.len() - 1];
+                pat.push_str(&format!(r"(?:\s+(?P<{name}>.*))?"));
+            } else {
+                if seen_optional {
+                    panic!(
+                        "Invalid pattern '{pattern}': mandatory parameter '{part}' cannot follow an optional parameter"
+                    );
+                }
+
+                let name = stripped;
+                pat.push_str(&format!(r"\s+(?P<{name}>.*)"));
+            }
+        } else {
+            if seen_optional {
+                panic!(
+                    "Invalid pattern '{pattern}': literal word '{part}' cannot follow an optional parameter"
+                );
+            }
+
+            pat.push_str(&format!(r"\s+{}", regex::escape(part)));
+        }
+    }
+
+    let re = regex::Regex::new(&pat).unwrap();
+
+    fn extract_params(text: &str, re: &regex::Regex) -> Flow {
+        if let Some(captures) = re.captures(text) {
+            let mut params = HashMap::new();
+            for name in re.capture_names().flatten() {
+                if let Some(m) = captures.name(name) {
+                    params.insert(name.to_string(), m.as_str().to_string());
+                }
+            }
+
+            super::proceed_with(CommandParams(params))
+        } else if re.is_match(text) {
+            super::proceed()
+        } else {
+            super::stop()
+        }
+    }
+
+    move |_, update| match update {
+        Update::NewMessage(message) => {
+            let text = message.text();
+
+            extract_params(text, &re)
+        }
+        Update::CallbackQuery(query) => {
+            let data = String::from_utf8_lossy(query.data()).to_string();
+
+            extract_params(&data, &re)
+        }
+        _ => super::stop(),
+    }
+}
+
 /// Pass if the message has a URL.
 ///
 /// It extracts URLs directly from message's format entities, [`tl::enums::MessageEntity::Url`].
 ///
 /// Note: if the `url` feature is enabled, it will also extracts URLs that weren't converted to format
 /// entities, which can happen when using a broken client.
 ///
-/// Injects:
+/// # Injects:
 /// * `Vec<String>`: extracted urls.
 pub fn has_url(_: Client, update: Update) -> Flow {
     match update {
@@ -128,7 +248,7 @@ pub fn has_url(_: Client, update: Update) -> Flow {
 
 /// Pass if the message has a dice attached to it.
 ///
-/// Injects:
+/// # Injects:
 /// * [`grammers::message::Dice`][]: dice.
 pub fn has_dice(_: Client, update: Update) -> Flow {
     match update {

ferogram/src/lib.rs

@@ -7,17 +7,18 @@
 
 pub mod client;
 mod context;
-mod di;
+pub mod di;
 mod dispatcher;
 pub mod error;
 pub mod filter;
 pub mod handler;
+pub mod router;
 mod utils;
 
 use std::error::Error;
 
 pub use context::Context;
-pub use di::{Injector, Resource};
+use di::Injector;
 pub use dispatcher::Dispatcher;
 use dispatcher::{DISPATCHER_STOPPED, STOP_DISPATCHER};
 pub use handler::Handler;
@@ -27,8 +28,10 @@ pub mod prelude {
     pub use grammers_session as session;
 
     pub use super::{
-        client::*,
-        filter::{AsyncMarker, Filter, IntoFilter, SyncMarker},
+        client::ConnectionExt,
+        di::Resource,
+        filter::{self, AsyncMarker, Filter, FilterExt, IntoFilter, SyncMarker},
+        router::CommandParams,
         *,
     };
 }