Struct serenity::utils::MessageBuilder

pub struct MessageBuilder(pub String);

The Message Builder is an ergonomic utility to easily build a message, by adding text and mentioning mentionable structs.

The finalized value can be accessed via build or the inner value.

Examples

Build a message, mentioning a user and an emoji, and retrieving the value:

use serenity::utils::MessageBuilder;

// assuming an `emoji` and `user` have already been bound

let content = MessageBuilder::new()
    .push("You sent a message, ")
    .mention(&user)
    .push("! ")
    .mention(&emoji)
    .build();

Methods

impl MessageBuilder

pub fn new() -> MessageBuilder

Creates a new, empty builder.

Examples

Create a new MessageBuilder:

use serenity::utils::MessageBuilder;

let message = MessageBuilder::new();

// alternatively:
let message = MessageBuilder::default();

pub fn build(self) -> String

Pulls the inner value out of the builder.

Examples

Create a string mentioning a channel by Id, and then suffixing "!", and finally building it to retrieve the inner String:

use serenity::model::id::ChannelId;
use serenity::utils::MessageBuilder;

let channel_id = ChannelId(81384788765712384);

let content = MessageBuilder::new()
    .channel(channel_id)
    .push("!")
    .build();

assert_eq!(content, "<#81384788765712384>!");

This is equivalent to simply retrieving the tuple struct's first value:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new().push("test").0;

assert_eq!(content, "test");

pub fn channel<C: Into<ChannelId>>(self, channel: C) -> Self

Mentions the GuildChannel in the built message.

This accepts anything that converts into a ChannelId. Refer to ChannelId's documentation for more information.

Refer to ChannelId's Display implementation for more information on how this is formatted.

Examples

Mentioning a Channel by Id:

use serenity::model::id::ChannelId;
use serenity::utils::MessageBuilder;

let channel_id = ChannelId(81384788765712384);

let content = MessageBuilder::new()
    .push("The channel is: ")
    .channel(channel_id)
    .build();

assert_eq!(content, "The channel is: <#81384788765712384>");

pub fn emoji(self, emoji: &Emoji) -> Self

Displays the given emoji in the built message.

Refer to Emojis Display implementation for more information on how this is formatted.

Examples

Mention an emoji in a message's content:

use serenity::model::guild::Emoji;
use serenity::model::id::EmojiId;
use serenity::utils::MessageBuilder;

let emoji = Emoji {
    animated: false,
    id: EmojiId(302516740095606785),
    managed: true,
    name: "smugAnimeFace".to_string(),
    require_colons: true,
    roles: vec![],
};

let message = MessageBuilder::new()
    .push("foo ")
    .emoji(&emoji)
    .push(".")
    .build();

assert_eq!(message, "foo <:smugAnimeFace:302516740095606785>.");

pub fn mention<M: Mentionable>(self, item: &M) -> Self

Mentions something that implements the Mentionable trait.

pub fn push<D: I>(self, content: D) -> Self

Pushes a string to the internal message content.

Note that this does not mutate either the given data or the internal message content in anyway prior to appending the given content to the internal message.

Examples

use serenity::utils::MessageBuilder;

let message = MessageBuilder::new().push("test");

assert_eq!(message.push("ing").0, "testing");

pub fn push_codeblock<D: I>(self, content: D, language: Option<&str>) -> Self

Pushes a codeblock to the content, with optional syntax highlighting.

Examples

Pushing a Rust codeblock:

use serenity::utils::MessageBuilder;

let code = r#"
fn main() {
    println!("Hello, world!");
}
"#;

let content = MessageBuilder::new()
    .push_codeblock(code, Some("rust"))
    .build();

let expected = r#"```rust
fn main() {
    println!("Hello, world!");
}
```"#;

assert_eq!(content, expected);

Pushing a codeblock without a language:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new()
    .push_codeblock("hello", None)
    .build();

assert_eq!(content, "```\nhello\n```");

pub fn push_mono<D: I>(self, content: D) -> Self

Pushes inlined monospaced text to the content.

Examples

Display a server configuration value to the user:

use serenity::utils::MessageBuilder;

let key = "prefix";
let value = "&";

let content = MessageBuilder::new()
    .push("The setting ")
    .push_mono(key)
    .push(" for this server is ")
    .push_mono(value)
    .push(".")
    .build();

let expected = format!("The setting `{}` for this server is `{}`.",
                       key,
                       value);

assert_eq!(content, expected);

pub fn push_italic<D: I>(self, content: D) -> Self

Pushes inlined italicized text to the content.

Examples

Emphasize information to the user:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new()
    .push("You don't ")
    .push_italic("always need")
    .push(" to italicize ")
    .push_italic("everything")
    .push(".")
    .build();

let expected = "You don't _always need_ to italicize _everything_.";

assert_eq!(content, expected);

pub fn push_bold<D: I>(self, content: D) -> Self

Pushes an inline bold text to the content.

pub fn push_underline<D: I>(self, content: D) -> Self

Pushes an underlined inline text to the content.

pub fn push_strike<D: I>(self, content: D) -> Self

Pushes a strikethrough inline text to the content.

pub fn push_line<D: I>(self, content: D) -> Self

Pushes the given text with a newline appended to the content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new().push_line("hello").push("world").build();

assert_eq!(content, "hello\nworld");

pub fn push_mono_line<D: I>(self, content: D) -> Self

Pushes inlined monospace text with an added newline to the content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new().push_mono_line("hello").push("world").build();

assert_eq!(content, "`hello`\nworld");

pub fn push_italic_line<D: I>(self, content: D) -> Self

Pushes an inlined italicized text with an added newline to the content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new().push_italic_line("hello").push("world").build();

assert_eq!(content, "_hello_\nworld");

pub fn push_bold_line<D: I>(self, content: D) -> Self

Pushes an inline bold text with an added newline to the content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new().push_bold_line("hello").push("world").build();

assert_eq!(content, "**hello**\nworld");

pub fn push_underline_line<D: I>(self, content: D) -> Self

Pushes an underlined inline text with an added newline to the content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new().push_underline_line("hello").push("world").build();

assert_eq!(content, "__hello__\nworld");

pub fn push_strike_line<D: I>(self, content: D) -> Self

Pushes a strikethrough inline text with a newline added to the content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new().push_strike_line("hello").push("world").build();

assert_eq!(content, "~~hello~~\nworld");

pub fn push_safe<C: I>(self, content: C) -> Self

Pushes text to your message, but normalizing content - that means ensuring that there's no unwanted formatting, mention spam etc.

pub fn push_codeblock_safe<D: I>(     self,     content: D,     language: Option<&str> ) -> Self

Pushes a code-block to your message normalizing content.

pub fn push_mono_safe<D: I>(self, content: D) -> Self

Pushes an inline monospaced text to the content normalizing content.

pub fn push_italic_safe<D: I>(self, content: D) -> Self

Pushes an inline italicized text to the content normalizing content.

pub fn push_bold_safe<D: I>(self, content: D) -> Self

Pushes an inline bold text to the content normalizing content.

pub fn push_underline_safe<D: I>(self, content: D) -> Self

Pushes an underlined inline text to the content normalizing content.

pub fn push_strike_safe<D: I>(self, content: D) -> Self

Pushes a strikethrough inline text to the content normalizing content.

pub fn push_line_safe<D: I>(self, content: D) -> Self

Pushes text with a newline appended to the content normalizing content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new().push_line_safe("Hello @everyone")
                                   .push("How are you?")
                                   .build();

assert_eq!(content, "Hello @\u{200B}everyone\nHow are you?");

pub fn push_mono_line_safe<D: I>(self, content: D) -> Self

Pushes an inline monospaced text with added newline to the content normalizing content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new()
                .push_mono_line_safe("`hello @everyone`")
                .push("world").build();

assert_eq!(content, "`'hello @\u{200B}everyone'`\nworld");

pub fn push_italic_line_safe<D: I>(self, content: D) -> Self

Pushes an inline italicized text with added newline to the content normalizing content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new()
                .push_italic_line_safe("@everyone")
                .push("Isn't a mention.").build();

assert_eq!(content, "_@\u{200B}everyone_\nIsn't a mention.");

pub fn push_bold_line_safe<D: I>(self, content: D) -> Self

Pushes an inline bold text with added newline to the content normalizing content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new()
                .push_bold_line_safe("@everyone")
                .push("Isn't a mention.").build();

assert_eq!(content, "**@\u{200B}everyone**\nIsn't a mention.");

pub fn push_underline_line_safe<D: I>(self, content: D) -> Self

Pushes an underlined inline text with added newline to the content normalizing content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new()
                .push_underline_line_safe("@everyone")
                .push("Isn't a mention.").build();

assert_eq!(content, "__@\u{200B}everyone__\nIsn't a mention.");

pub fn push_strike_line_safe<D: I>(self, content: D) -> Self

Pushes a strikethrough inline text with added newline to the content normalizing content.

Examples

Push content and then append a newline:

use serenity::utils::MessageBuilder;

let content = MessageBuilder::new()
                .push_strike_line_safe("@everyone")
                .push("Isn't a mention.").build();

assert_eq!(content, "~~@\u{200B}everyone~~\nIsn't a mention.");

pub fn role<R: Into<RoleId>>(self, role: R) -> Self

Mentions the Role in the built message.

This accepts anything that converts into a RoleId. Refer to RoleId's documentation for more information.

Refer to RoleId's Display implementation for more information on how this is formatted.

pub fn user<U: Into<UserId>>(self, user: U) -> Self

Mentions the User in the built message.

This accepts anything that converts into a UserId. Refer to UserId's documentation for more information.

Refer to UserId's Display implementation for more information on how this is formatted.

Trait Implementations

impl Default for MessageBuilder

fn default() -> MessageBuilder

Returns the "default value" for a type.

impl Clone for MessageBuilder

fn clone(&self) -> MessageBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MessageBuilder

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

Formats the value using the given formatter.

impl Display for MessageBuilder

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

Formats the message builder into a string.

This is done by simply taking the internal value of the tuple-struct and writing it into the formatter.

Examples

Create a message builder, and format it into a string via the format! macro:

use serenity::utils::MessageBuilder;