Struct tbot::types::parameters::Text

pub struct Text { /* private fields */ }

Represents input text, notably text messages or captions, potentially with HTML or Markdown{,V2} markup applied.

You probably won’t need to use this type explicitly: wherever tbot needs a Text instance, it takes impl Into<Text> as the argument. For example, any string, notably String and &str (and anything that implements Into<String>), can be used in place of Text if you just need a plain string without all this madness. Here’s an example:

use tbot::{prelude::*, types::message::From};

let mut bot = tbot::from_env!("BOT_TOKEN").event_loop();
bot.start(|context| async move {
    let sender_name = match &context.from {
        Some(From::User(sender)) => &sender.first_name,
        _ => return,
    };

    let result = context
        .send_message(format!("Hi, {}!", sender_name))
        .call()
        .await;
    if let Err(error) = result {
        dbg!(error);
    }
});

But if you really want to highlight something, you can choose any of HTML, MarkdownV2 and Markdown (the latter is not recommended now though). If you chose HTML or MarkdownV2, tbot’s got something for you: tbot::markup lets you build markup using either of those, automatically escaping all provided strings and ensuring that the resulting string is well-formed. Here’s a short example, see that module’s documentation for more:

use tbot::{markup::{bold, markdown_v2}, prelude::*};

bot.start(|context| async move {
    // ..

    let result = context
        .send_message(markdown_v2(("Hi, ", bold(sender_name), "!")))
        .call()
        .await;
    if let Err(error) = result {
        dbg!(error);
    }
});

So this is another case when you don’t need to use Text explicitly. There are cases when you may need to use it directly though. For example, if you want to mix markups for some reason:

use tbot::{markup::{markdown_v2, bold}, types::{message::From, parameters::Text}};

let response: Text = match context.from {
    Some(From::User(sender)) => markdown_v2(("Hi, ", bold(sender.first_name), "!")).into(),
    Some(_) => return,
    None => "Wow, I'm in a channel!".into(),
};

The latter transformation can also be replaced with Text::with_plain("Wow, I'm in a channel!"). Likewise, there are Text::with_markdown_v2, Text::with_html and Text::with_markdown just in case you want to use an already marked-up string. Remember that you need to maintain well-formness yourself in this case, so that’s why tbot encourages using tbot::markup for generating marked-up messages.

If you look closely at the Bot API docs, you’ll notice another way to provide markup without all these parse modes: by providing Vec<message::text::Entity>. So what about tbot’s support for this? Well, we decided that this feature is of low importance, especially since tbot has got you covered with a better feature here!

tbot::util::entities lets you parse messages with entities easily and without having to care about all that UTF-16 stuff:

use tbot::util::entities;

bot.text(|context| async move {
    for entity in entities(&context.text) {
        dbg!(entity);
        // an entity may a code block, or inline code, or a “semantic”
        // entity, e.g. a username, link or just text, that may have
        // different formatting applied to its different parts.
    }
});

What’s interesting for us in our case is that entities returns a value that can also be used with tbot::markup! Here’s an example:

use tbot::{util::entities, markup::markdown_v2, prelude::*};

bot.text(|context| async move {
    let entities = entities(&context.text);
    let echo = markdown_v2(entities);

    let result = context.send_message(echo).call().await;
    if let Err(error) = result {
        dbg!(error);
    }
});

The above is an example of echoing messages with preserving formatting! And that’s the basic usecase for specifying entities instead of parse_mode. Yet passing entities directly has a downside: if you want to amend the user’s message that’s being echoed, you have to be very careful that all offsets in the entities are shifted accordingly, otherwise the message will be misformatted or, worse, some offset will occur inside a character. This gets worse as the offsets are reported per UTF-16: this makes life easier for JavaScript people, but we Rustaceans use UTF-8, and the difference between them makes stuff a bit more complicated.

entities, on the other hand, already handles UTF-16 for you and returns a Vec which you can modify quite easily keeping all the formatting in place. Decorating user messages is even easier: entities can be used just like markup::bold or markup::link.

That being said, if you really, really need something like Text::with_entities, we’re accepting merge requests on our GitLab and GitHub repositories.

Implementations

impl Text

pub fn with_plain(text: impl Into<String>) -> Self

Constructs a Text instance with plain text, i.e. without any parse mode applied.

pub fn with_markdown(text: impl Into<String>) -> Self

Constructs a new Text instance with text using Markdown markup.

Note that it is your responsibility to provide well-formed Markdown text if you wish to use Markdown parse mode.

Telegram Bot API implemented a newer version of Markdown markup, MarkdownV2, which supports more formatting options and better works with escaping. If you want to use the newer version, call Text::with_markdown_v2 instead.

pub fn with_markdown_v2(text: impl Into<String>) -> Self

Constructs a new Text instance with text using MarkdownV2 markup.

Note that it is your responsibility to provide well-formed MarkdownV2 text if you wish to use MarkdownV2 parse mode and call this method directly. On the other hand, using tbot::markup::markdown_v2 ensures that your MarkdownV2 text is always well-formed, since it automatically escapes all strings. Its return value implements Into<Text>, and so can be used wherever a Text instance is expected.

If you want to use the older Markdown parse mode for some reason, look into Text::with_markdown instead.

pub fn with_html(text: impl Into<String>) -> Self

Constructs a new Text instance with text using HTML markup.

Note that it is your responsibility to provide well-formed HTML text if you wish to use HTML parse mode and call this method directly. On the other hand, using tbot::markup::html ensures that your HTML text is always well-formed, since it automatically escapes all strings. Its return value implements Into<Text>, and so can be used wherever a Text instance is expected.

pub const fn is_plain(&self) -> bool

Checks if no parse mode is set, i.e. this Text instance contains plain text.

pub const fn is_markdown_v2(&self) -> bool

Checks if the parse mode is set to MarkdownV2.

pub const fn is_markdown(&self) -> bool

Checks if the parse mode is set to Markdown.

pub const fn is_html(&self) -> bool

Checks if the parse mode is set to Html.

Trait Implementations

impl Clone for Text

fn clone(&self) -> Text

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Text

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Formattable> From<Html<T>> for Text

fn from(markup: Html<T>) -> Self

Converts to this type from the input type.

impl<T: Formattable> From<MarkdownV2<T>> for Text

fn from(markup: MarkdownV2<T>) -> Self

Converts to this type from the input type.

impl<T: Into<String>> From<T> for Text

fn from(text: T) -> Self

Converts to this type from the input type.

impl Hash for Text

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq<Text> for Text

fn eq(&self, other: &Text) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Text

impl StructuralEq for Text

impl StructuralPartialEq for Text