Struct Handler 

pub struct Handler<'a, Output, Descr = Unspecified> { /* private fields */ }

An instance that receives an input and decides whether to break a chain or pass the value further.

In order to create this structure, you can use the predefined functions from crate.

The difference between chaining and branching

Handlers can be chained via Handler::chain and branched via Handler::branch. To understand the difference between the two, consider the following examples: a.chain(b).c and a.branch(b).c.

In a.chain(b).c, the handler a is given the rest of the handler chain, b and c; if a decides to pass the value further, it invokes b. Then, if b decides to pass the value further, it invokes c. Thus, the handler chain is linear.

In a.branch(b).c, if a decides to pass the value further, it invokes b. But since b is “branched”, it receives an empty chain, so it cannot invoke c. Instead, if b decides to continue execution (ControlFlow::Continue), a invokes c; otherwise (ControlFlow::Break), the process is terminated. The handler chain is nested.

To sum up, chaining looks like this:

a -> b -> c

And branching looks like this:

a -> b
  -> c

This is very crucial when b is a filter: if it is chained, it decides whether or not to call c, but when it is branched, whether c is called depends solely on a.

Implementations

impl<'a, Output, Descr> Handler<'a, Output, Descr>

where Output: 'a, Descr: HandlerDescription,

pub fn chain( self, next: Handler<'a, Output, Descr>, ) -> Handler<'a, Output, Descr>

Chain two handlers to form a chain of responsibility.

Chaining is different from branching. See “The difference between chaining and branching”.

This method makes use of HandlerSignature (stored in every handler) to perform run-time type inference of the resulting handler signature; this information is used by crate::type_check to make sure that all required types are provided before execution.

Examples

use dptree::prelude::*;

let handler: Handler<_> =
    dptree::filter(|x: i32| x > 0).chain(dptree::endpoint(|| async { "done" }));

assert_eq!(handler.dispatch(dptree::deps![10]).await, ControlFlow::Break("done"));
assert_eq!(
    handler.dispatch(dptree::deps![-10]).await,
    ControlFlow::Continue(dptree::deps![-10])
);

pub fn branch( self, next: Handler<'a, Output, Descr>, ) -> Handler<'a, Output, Descr>

where Output: Send,

Chain two handlers to make a tree of responsibility.

Chaining is different from branching. See “The difference between chaining and branching”.

This method makes use of HandlerSignature (stored in every handler) to perform run-time type inference of the resulting handler signature; this information is used by crate::type_check to make sure that all required types are provided before execution.

Examples

use dptree::prelude::*;


#[derive(Debug, PartialEq)]
enum Output {
    Five,
    One,
    GT,
}

let dispatcher: Handler<_> = dptree::entry()
    .branch(dptree::filter(|num: i32| num == 5).endpoint(|| async move { Output::Five }))
    .branch(dptree::filter(|num: i32| num == 1).endpoint(|| async move { Output::One }))
    .branch(dptree::filter(|num: i32| num > 2).endpoint(|| async move { Output::GT }));

assert_eq!(dispatcher.dispatch(dptree::deps![5]).await, ControlFlow::Break(Output::Five));
assert_eq!(dispatcher.dispatch(dptree::deps![1]).await, ControlFlow::Break(Output::One));
assert_eq!(dispatcher.dispatch(dptree::deps![3]).await, ControlFlow::Break(Output::GT));
assert_eq!(
    dispatcher.dispatch(dptree::deps![0]).await,
    ControlFlow::Continue(dptree::deps![0])
);

Examples found in repository

examples/buttons.rs (line 31)

async fn main() -> Result<(), Box<dyn Error>> {
    pretty_env_logger::init();
    log::info!("Starting buttons bot...");

    let bot = Bot::from_env();

    let handler = dptree::entry()
        .branch(Update::filter_message().endpoint(message_handler))
        .branch(Update::filter_callback_query().endpoint(callback_handler))
        .branch(Update::filter_inline_query().endpoint(inline_query_handler));

    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;
    Ok(())
}

examples/deep_linking.rs (lines 47-51)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting deep linking bot...");

    let bot = Bot::from_env();

    let handler = dialogue::enter::<Update, InMemStorage<State>, State, _>()
        .branch(
            Update::filter_message()
                .filter_command::<StartCommand>()
                .branch(case![StartCommand::Start(start)].endpoint(start)),
        )
        .branch(
            Update::filter_message()
                .branch(case![State::WriteToSomeone { id }].endpoint(send_message)),
        );

    Dispatcher::builder(bot, handler)
        .dependencies(deps![InMemStorage::<State>::new()])
        .enable_ctrlc_handler()
        .build()
        .dispatch()
        .await;
}

examples/dialogue.rs (line 46)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting dialogue bot...");

    let bot = Bot::from_env();

    Dispatcher::builder(
        bot,
        Update::filter_message()
            .enter_dialogue::<Message, InMemStorage<State>, State>()
            .branch(dptree::case![State::Start].endpoint(start))
            .branch(dptree::case![State::ReceiveFullName].endpoint(receive_full_name))
            .branch(dptree::case![State::ReceiveAge { full_name }].endpoint(receive_age))
            .branch(
                dptree::case![State::ReceiveLocation { full_name, age }].endpoint(receive_location),
            ),
    )
    .dependencies(dptree::deps![InMemStorage::<State>::new()])
    .enable_ctrlc_handler()
    .build()
    .dispatch()
    .await;
}

examples/purchase.rs (lines 66-70)

fn schema() -> UpdateHandler<Box<dyn std::error::Error + Send + Sync + 'static>> {
    use dptree::case;

    let command_handler = ronami::filter_command::<Command, _>()
        .branch(
            case![State::Start]
                .branch(case![Command::Help].endpoint(help))
                .branch(case![Command::Start].endpoint(start)),
        )
        .branch(case![Command::Cancel].endpoint(cancel));

    let message_handler = Update::filter_message()
        .branch(command_handler)
        .branch(case![State::ReceiveFullName].endpoint(receive_full_name))
        .branch(dptree::endpoint(invalid_state));

    let callback_query_handler = Update::filter_callback_query().branch(
        case![State::ReceiveProductChoice { full_name }].endpoint(receive_product_selection),
    );

    dialogue::enter::<Update, InMemStorage<State>, State, _>()
        .branch(message_handler)
        .branch(callback_query_handler)
}

examples/db_remember.rs (line 49)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting DB remember bot...");

    let bot = Bot::from_env();

    let storage: MyStorage = if std::env::var("DB_REMEMBER_REDIS").is_ok() {
        RedisStorage::open("redis://127.0.0.1:6379", Bincode).await.unwrap().erase()
    } else {
        SqliteStorage::open("db.sqlite", Json).await.unwrap().erase()
    };

    let handler = Update::filter_message()
        .enter_dialogue::<Message, ErasedStorage<State>, State>()
        .branch(dptree::case![State::Start].endpoint(start))
        .branch(
            dptree::case![State::GotNumber(n)]
                .branch(dptree::entry().filter_command::<Command>().endpoint(got_number))
                .branch(dptree::endpoint(invalid_command)),
        );

    Dispatcher::builder(bot, handler)
        .dependencies(dptree::deps![storage])
        .enable_ctrlc_handler()
        .build()
        .dispatch()
        .await;
}

examples/chat_member_updates.rs (lines 28-42)

async fn main() -> ResponseResult<()> {
    pretty_env_logger::init();

    // We specify default parse mode to be `Html`, so that later we can use
    // `html::user_mention`
    let bot = ronami::Bot::from_env().parse_mode(ParseMode::Html);

    // Create a handler for our bot, that will process updates from Telegram
    let handler = dptree::entry()
        .inspect(|u: Update| {
            eprintln!("{u:#?}"); // Print the update to the console with inspect
        })
        .branch(
            Update::filter_chat_member()
                .branch(
                    dptree::filter(|m: ChatMemberUpdated| {
                        m.old_chat_member.is_left() && m.new_chat_member.is_present()
                    })
                    .endpoint(new_chat_member),
                )
                .branch(
                    dptree::filter(|m: ChatMemberUpdated| {
                        m.old_chat_member.is_present() && m.new_chat_member.is_left()
                    })
                    .endpoint(left_chat_member),
                ),
        );

    // Create a dispatcher for our bot
    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;

    Ok(())
}

Additional examples can be found in:

• examples/inline.rs
• examples/dispatching_features.rs

pub async fn execute<Cont, ContFut>( self, input: DependencyMap, cont: Cont, ) -> ControlFlow<Output, DependencyMap>

where Cont: FnOnce(DependencyMap) -> ContFut + Send + Sync + 'a, ContFut: Future<Output = ControlFlow<Output, DependencyMap>> + Send + 'a,

Executes this handler with a continuation.

Usually, you do not want to call this method by yourself, if you do not write your own handler implementation. If you wish to execute handler without a continuation, take a look at the Handler::dispatch method.

NOTE: If you are using DependencyMap, you should first call crate::type_check to type-check your handler against a container; otherwise, type checking will be delayed until the actual execution, which can make things harder to debug.

Examples

use dptree::prelude::*;

let handler: Handler<_> = dptree::filter(|x: i32| x > 0);

let output = handler.execute(dptree::deps![10], |_| async { ControlFlow::Break("done") }).await;
assert_eq!(output, ControlFlow::Break("done"));

pub async fn dispatch( &self, input: DependencyMap, ) -> ControlFlow<Output, DependencyMap>

Executes this handler.

Returns ControlFlow::Break when executed successfully, ControlFlow::Continue otherwise.

NOTE: If you are using DependencyMap, you should first call crate::type_check to type-check your handler against a container; otherwise, type checking will be delayed until the actual execution, which can make things harder to debug.

pub fn description(&self) -> &Descr

Returns the set of updates that can be processed by this handler.

pub fn sig(&self) -> &HandlerSignature

Returns this handler’s run-time type signature.

impl<'a, Output, Descr> Handler<'a, Output, Descr>

where Output: 'a, Descr: HandlerDescription,

pub fn filter<Pred, FnArgs>(self, pred: Pred) -> Handler<'a, Output, Descr>

where Asyncify<Pred>: Injectable<bool, FnArgs> + Send + Sync + 'a,

Chain this handler with the filter predicate pred.

Examples found in repository

examples/middlewares_fallible.rs (lines 19-28)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting middlewares_fallible bot...");

    let bot = Bot::from_env();

    let handler = Update::filter_message()
        // Executes before the endpoint.
        .inspect(|msg: Message| println!("Before (message #{}).", msg.id))
        // Our "endpoint".
        .map_async(my_endpoint)
        // Executes after the endpoint. If the endpoint failed, print an error message and stop
        // execution; if not, continue.
        .filter(|result: HandlerResult, msg: Message| {
            println!("In-between (message #{}).", msg.id);
            match result {
                Ok(()) => true,
                Err(err) => {
                    eprintln!("Our endpoint failed: {err}");
                    false
                }
            }
        })
        // Executes only if the endpoint succeeded.
        .endpoint(|msg: Message| async move {
            println!("After (message #{}).", msg.id);
            HandlerResult::Ok(())
        });

    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;
}

pub fn filter_async<Pred, FnArgs>( self, pred: Pred, ) -> Handler<'a, Output, Descr>

where Pred: Injectable<bool, FnArgs> + Send + Sync + 'a,

Chain this handler with the async filter predicate pred.

pub fn filter_map<Proj, NewType, Args>( self, proj: Proj, ) -> Handler<'a, Output, Descr>

where Asyncify<Proj>: Injectable<Option<NewType>, Args> + Send + Sync + 'a, NewType: Send + Sync + 'static,

Chain this handler with the filter projection proj.

pub fn filter_map_async<Proj, NewType, Args>( self, proj: Proj, ) -> Handler<'a, Output, Descr>

where Proj: Injectable<Option<NewType>, Args> + Send + Sync + 'a, NewType: Send + Sync + 'static,

Chain this handler with the async filter projection proj.

pub fn map<Proj, NewType, Args>(self, proj: Proj) -> Handler<'a, Output, Descr>

where Asyncify<Proj>: Injectable<NewType, Args> + Send + Sync + 'a, NewType: Send + Sync + 'static,

Chain this handler with the map projection proj.

pub fn map_async<Proj, NewType, Args>( self, proj: Proj, ) -> Handler<'a, Output, Descr>

where Proj: Injectable<NewType, Args> + Send + Sync + 'a, NewType: Send + Sync + 'static,

Chain this handler with the async map projection proj.

Examples found in repository

examples/middlewares.rs (line 16)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting middlewares bot...");

    let bot = Bot::from_env();

    let handler = Update::filter_message()
        // Executes before the endpoint.
        .inspect(|msg: Message| println!("Before (message #{}).", msg.id))
        // Our "endpoint".
        .map_async(my_endpoint)
        // Executes after the endpoint (even if it fails).
        .inspect(|msg: Message| {
            println!("After (message #{}).", msg.id);
        })
        // Retrieve the result of the endpoint and pass it to the dispatcher.
        .endpoint(|result: HandlerResult| async move {
            // Alternatively, we could also pattern-match on this value for more
            // fine-grained behaviour.
            result
        });

    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;
}

examples/middlewares_fallible.rs (line 16)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting middlewares_fallible bot...");

    let bot = Bot::from_env();

    let handler = Update::filter_message()
        // Executes before the endpoint.
        .inspect(|msg: Message| println!("Before (message #{}).", msg.id))
        // Our "endpoint".
        .map_async(my_endpoint)
        // Executes after the endpoint. If the endpoint failed, print an error message and stop
        // execution; if not, continue.
        .filter(|result: HandlerResult, msg: Message| {
            println!("In-between (message #{}).", msg.id);
            match result {
                Ok(()) => true,
                Err(err) => {
                    eprintln!("Our endpoint failed: {err}");
                    false
                }
            }
        })
        // Executes only if the endpoint succeeded.
        .endpoint(|msg: Message| async move {
            println!("After (message #{}).", msg.id);
            HandlerResult::Ok(())
        });

    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;
}

pub fn inspect<F, Args>(self, f: F) -> Handler<'a, Output, Descr>

where Asyncify<F>: Injectable<(), Args> + Send + Sync + 'a,

Chain this handler with the inspection function f.

Examples found in repository

examples/middlewares.rs (line 14)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting middlewares bot...");

    let bot = Bot::from_env();

    let handler = Update::filter_message()
        // Executes before the endpoint.
        .inspect(|msg: Message| println!("Before (message #{}).", msg.id))
        // Our "endpoint".
        .map_async(my_endpoint)
        // Executes after the endpoint (even if it fails).
        .inspect(|msg: Message| {
            println!("After (message #{}).", msg.id);
        })
        // Retrieve the result of the endpoint and pass it to the dispatcher.
        .endpoint(|result: HandlerResult| async move {
            // Alternatively, we could also pattern-match on this value for more
            // fine-grained behaviour.
            result
        });

    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;
}

examples/middlewares_fallible.rs (line 14)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting middlewares_fallible bot...");

    let bot = Bot::from_env();

    let handler = Update::filter_message()
        // Executes before the endpoint.
        .inspect(|msg: Message| println!("Before (message #{}).", msg.id))
        // Our "endpoint".
        .map_async(my_endpoint)
        // Executes after the endpoint. If the endpoint failed, print an error message and stop
        // execution; if not, continue.
        .filter(|result: HandlerResult, msg: Message| {
            println!("In-between (message #{}).", msg.id);
            match result {
                Ok(()) => true,
                Err(err) => {
                    eprintln!("Our endpoint failed: {err}");
                    false
                }
            }
        })
        // Executes only if the endpoint succeeded.
        .endpoint(|msg: Message| async move {
            println!("After (message #{}).", msg.id);
            HandlerResult::Ok(())
        });

    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;
}

examples/chat_member_updates.rs (lines 25-27)

async fn main() -> ResponseResult<()> {
    pretty_env_logger::init();

    // We specify default parse mode to be `Html`, so that later we can use
    // `html::user_mention`
    let bot = ronami::Bot::from_env().parse_mode(ParseMode::Html);

    // Create a handler for our bot, that will process updates from Telegram
    let handler = dptree::entry()
        .inspect(|u: Update| {
            eprintln!("{u:#?}"); // Print the update to the console with inspect
        })
        .branch(
            Update::filter_chat_member()
                .branch(
                    dptree::filter(|m: ChatMemberUpdated| {
                        m.old_chat_member.is_left() && m.new_chat_member.is_present()
                    })
                    .endpoint(new_chat_member),
                )
                .branch(
                    dptree::filter(|m: ChatMemberUpdated| {
                        m.old_chat_member.is_present() && m.new_chat_member.is_left()
                    })
                    .endpoint(left_chat_member),
                ),
        );

    // Create a dispatcher for our bot
    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;

    Ok(())
}

pub fn inspect_async<F, Args>(self, f: F) -> Handler<'a, Output, Descr>

where F: Injectable<(), Args> + Send + Sync + 'a,

Chain this handler with the async inspection function f.

pub fn endpoint<F, FnArgs>(self, f: F) -> Handler<'a, Output, Descr>

where F: Injectable<Output, FnArgs> + Send + Sync + 'a, Output: 'static,

Chain this handler with the endpoint handler f.

Examples found in repository

examples/buttons.rs (line 31)

async fn main() -> Result<(), Box<dyn Error>> {
    pretty_env_logger::init();
    log::info!("Starting buttons bot...");

    let bot = Bot::from_env();

    let handler = dptree::entry()
        .branch(Update::filter_message().endpoint(message_handler))
        .branch(Update::filter_callback_query().endpoint(callback_handler))
        .branch(Update::filter_inline_query().endpoint(inline_query_handler));

    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;
    Ok(())
}

examples/deep_linking.rs (line 50)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting deep linking bot...");

    let bot = Bot::from_env();

    let handler = dialogue::enter::<Update, InMemStorage<State>, State, _>()
        .branch(
            Update::filter_message()
                .filter_command::<StartCommand>()
                .branch(case![StartCommand::Start(start)].endpoint(start)),
        )
        .branch(
            Update::filter_message()
                .branch(case![State::WriteToSomeone { id }].endpoint(send_message)),
        );

    Dispatcher::builder(bot, handler)
        .dependencies(deps![InMemStorage::<State>::new()])
        .enable_ctrlc_handler()
        .build()
        .dispatch()
        .await;
}

examples/dialogue.rs (line 46)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting dialogue bot...");

    let bot = Bot::from_env();

    Dispatcher::builder(
        bot,
        Update::filter_message()
            .enter_dialogue::<Message, InMemStorage<State>, State>()
            .branch(dptree::case![State::Start].endpoint(start))
            .branch(dptree::case![State::ReceiveFullName].endpoint(receive_full_name))
            .branch(dptree::case![State::ReceiveAge { full_name }].endpoint(receive_age))
            .branch(
                dptree::case![State::ReceiveLocation { full_name, age }].endpoint(receive_location),
            ),
    )
    .dependencies(dptree::deps![InMemStorage::<State>::new()])
    .enable_ctrlc_handler()
    .build()
    .dispatch()
    .await;
}

examples/shared_state.rs (lines 18-25)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting shared state bot...");

    let bot = Bot::from_env();
    let messages_total = Arc::new(AtomicU64::new(0));

    let handler = Update::filter_message().endpoint(
        |bot: Bot, messages_total: Arc<AtomicU64>, msg: Message| async move {
            let previous = messages_total.fetch_add(1, Ordering::Relaxed);
            bot.send_message(msg.chat.id, format!("I received {previous} messages in total."))
                .await?;
            respond(())
        },
    );

    Dispatcher::builder(bot, handler)
        // Pass the shared state to the handler as a dependency.
        .dependencies(dptree::deps![messages_total])
        .enable_ctrlc_handler()
        .build()
        .dispatch()
        .await;
}

examples/middlewares.rs (lines 22-26)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting middlewares bot...");

    let bot = Bot::from_env();

    let handler = Update::filter_message()
        // Executes before the endpoint.
        .inspect(|msg: Message| println!("Before (message #{}).", msg.id))
        // Our "endpoint".
        .map_async(my_endpoint)
        // Executes after the endpoint (even if it fails).
        .inspect(|msg: Message| {
            println!("After (message #{}).", msg.id);
        })
        // Retrieve the result of the endpoint and pass it to the dispatcher.
        .endpoint(|result: HandlerResult| async move {
            // Alternatively, we could also pattern-match on this value for more
            // fine-grained behaviour.
            result
        });

    Dispatcher::builder(bot, handler).enable_ctrlc_handler().build().dispatch().await;
}

examples/purchase.rs (line 68)

fn schema() -> UpdateHandler<Box<dyn std::error::Error + Send + Sync + 'static>> {
    use dptree::case;

    let command_handler = ronami::filter_command::<Command, _>()
        .branch(
            case![State::Start]
                .branch(case![Command::Help].endpoint(help))
                .branch(case![Command::Start].endpoint(start)),
        )
        .branch(case![Command::Cancel].endpoint(cancel));

    let message_handler = Update::filter_message()
        .branch(command_handler)
        .branch(case![State::ReceiveFullName].endpoint(receive_full_name))
        .branch(dptree::endpoint(invalid_state));

    let callback_query_handler = Update::filter_callback_query().branch(
        case![State::ReceiveProductChoice { full_name }].endpoint(receive_product_selection),
    );

    dialogue::enter::<Update, InMemStorage<State>, State, _>()
        .branch(message_handler)
        .branch(callback_query_handler)
}

Additional examples can be found in:

• examples/db_remember.rs
• examples/middlewares_fallible.rs
• examples/chat_member_updates.rs
• examples/dispatching_features.rs

Trait Implementations

impl<Output, Descr> Clone for Handler<'_, Output, Descr>

fn clone(&self) -> Handler<'_, Output, Descr>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Output> HandlerExt<Output> for Handler<'static, Output, DpHandlerDescription>

where Output: Send + Sync + 'static,

fn filter_command<C>(self) -> Self

where C: BotCommands + Send + Sync + 'static,

Returns a handler that accepts a parsed command C.

fn filter_mention_command<C>(self) -> Self

where C: BotCommands + Send + Sync + 'static,

Returns a handler that accepts a parsed command C if the command contains a bot mention, for example /start@my_bot.

fn enter_dialogue<Upd, S, D>(self) -> Self

where S: Storage<D> + ?Sized + Send + Sync + 'static, <S as Storage<D>>::Error: Debug + Send, D: Default + Clone + Send + Sync + 'static, Upd: GetChatId + Clone + Send + Sync + 'static,

Passes Dialogue<D, S> and D as handler dependencies.