Struct serenity::framework::standard::Args

source ·

pub struct Args { /* private fields */ }

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Available on crate features framework and standard_framework only.

Expand description

A utility struct for handling “arguments” of a command.

An “argument” is a part of the message up that ends at one of the specified delimiters, or the end of the message.

§Example

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("hello world!", &[Delimiter::Single(' ')]); // A space is our delimiter.

// Parse our argument as a `String` and assert that it's the "hello" part of the message.
assert_eq!(args.single::<String>().unwrap(), "hello");
// Same here.
assert_eq!(args.single::<String>().unwrap(), "world!");

We can also parse “quoted arguments” (no pun intended):

use serenity::framework::standard::{Args, Delimiter};

// Let us imagine this scenario:
// You have a `photo` command that grabs the avatar url of a user. This command accepts names only.
// Now, one of your users wants the avatar of a user named Princess Zelda.
// Problem is, her name contains a space; our delimiter. This would result in two arguments, "Princess" and "Zelda".
// So how shall we get around this? Through quotes! By surrounding her name in them we can perceive it as one single argument.
let mut args = Args::new(r#""Princess Zelda""#, &[Delimiter::Single(' ')]);

// Hooray!
assert_eq!(args.single_quoted::<String>().unwrap(), "Princess Zelda");

In case of a mistake, we can go back in time… er I mean, one step (or entirely):

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("4 2", &[Delimiter::Single(' ')]);

assert_eq!(args.single::<u32>().unwrap(), 4);

// Oh wait, oops, meant to double the 4.
// But I won't able to access it now...
// oh wait, I can `rewind`.
args.rewind();

assert_eq!(args.single::<u32>().unwrap() * 2, 8);

// And the same for the 2
assert_eq!(args.single::<u32>().unwrap() * 2, 4);

// WAIT, NO. I wanted to concatenate them into a "42" string...
// Argh, what should I do now????
// ....
// oh, `restore`
args.restore();

let res = format!("{}{}", args.single::<String>().unwrap(), args.single::<String>().unwrap());

// Yay.
assert_eq!(res, "42");

Hmm, taking a glance at the prior example, it seems we have an issue with reading the same argument over and over. Is there a more sensible solution than rewinding…? Actually, there is! The Self::current and Self::parse methods:

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("trois cinq quatre six", &[Delimiter::Single(' ')]);

assert_eq!(args.parse::<String>().unwrap(), "trois");

// It might suggest we've lost the `trois`. But in fact, we didn't! And not only that, we can do it an infinite amount of times!
assert_eq!(args.parse::<String>().unwrap(), "trois");
assert_eq!(args.current(), Some("trois"));
assert_eq!(args.parse::<String>().unwrap(), "trois");
assert_eq!(args.current(), Some("trois"));

// Only if we use its brother method we'll then lose it.
assert_eq!(args.single::<String>().unwrap(), "trois");
assert_eq!(args.single::<String>().unwrap(), "cinq");
assert_eq!(args.single::<String>().unwrap(), "quatre");
assert_eq!(args.single::<String>().unwrap(), "six");

Implementations§

source §

impl Args

source

pub fn new(message: &str, possible_delimiters: &[Delimiter]) -> Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Create a new instance of Args for parsing arguments.

For more reference, look at Args’s struct documentation.

§Example

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new(
// Our message from which we'll parse over.
"the quick brown fox jumps over the lazy",

// The "delimiters", or aka the separators. They denote how we distinguish arguments as their own.
// For this example, we'll use one delimiter, the space (`0x20`), which will separate the message.
&[Delimiter::Single(' ')],
);

assert_eq!(args.single::<String>().unwrap(), "the");
assert_eq!(args.single::<String>().unwrap(), "quick");
assert_eq!(args.single::<String>().unwrap(), "brown");

// We shall not see `the quick brown` again.
assert_eq!(args.rest(), "fox jumps over the lazy");

source

pub fn advance(&mut self) -> &mut Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Move to the next argument. This increments the offset pointer.

Does nothing if the message is empty.

source

pub fn rewind(&mut self) -> &mut Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Go one step behind. This decrements the offset pointer.

Does nothing if the offset pointer is 0.

source

pub fn restore(&mut self)

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Go back to the starting point.

source

pub fn current(&self) -> Option<&str>

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Retrieve the current argument.

Applies modifications set by Self::trimmed and Self::quoted.

§Note

This borrows Args for the entire lifetime of the returned argument.

§Examples

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("4 2", &[Delimiter::Single(' ')]);

assert_eq!(args.current(), Some("4"));
args.advance();
assert_eq!(args.current(), Some("2"));
args.advance();
assert_eq!(args.current(), None);

source

pub fn trimmed(&mut self) -> &mut Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Apply trimming of whitespace to all arguments.

§Examples

use serenity::framework::standard::Args;

let mut args = Args::new("     42     ", &[]);

// trimmed lasts for the whole lifetime of `Args`
args.trimmed();
assert_eq!(args.current(), Some("42"));
// or until we decide ourselves
args.untrimmed();
assert_eq!(args.current(), Some("     42     "));
assert_eq!(args.message(), "     42     ");

source

pub fn untrimmed(&mut self) -> &mut Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Halt trimming of whitespace to all arguments.

§Examples

Refer to Self::trimmed’s examples.

source

pub fn quoted(&mut self) -> &mut Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Remove quotations surrounding all arguments.

Note that only the quotes of the argument are taken into account. The quotes in the message are preserved.

§Examples

use serenity::framework::standard::Args;

let mut args = Args::new("\"42\"", &[]);

// `quoted` lasts the whole lifetime of `Args`
args.quoted();
assert_eq!(args.current(), Some("42"));
// or until we decide
args.unquoted();
assert_eq!(args.current(), Some("\"42\""));
assert_eq!(args.message(), "\"42\"");

source

pub fn unquoted(&mut self) -> &mut Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Stop removing quotations of all arguments.

§Examples

Refer to Self::quoted’s examples.

source

pub fn parse<T: FromStr>(&self) -> Result<T, Error<T::Err>>

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Parse the current argument.

Modifications of Self::trimmed and Self::quoted are also applied if they were called.

§Examples

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("4 2", &[Delimiter::Single(' ')]);

assert_eq!(args.parse::<u32>().unwrap(), 4);
assert_eq!(args.current(), Some("4"));

§Errors

May return either Error::Parse if a parse error occurs, or Error::Eos if there are no further remaining args.

source

pub fn single<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Parse the current argument and advance.

Shorthand for calling Self::parse, storing the result, calling Self::advance and returning the result.

§Examples

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("4 2", &[Delimiter::Single(' ')]);

assert_eq!(args.single::<u32>().unwrap(), 4);

// `4` is now out of the way. Next we have `2`
assert_eq!(args.single::<u32>().unwrap(), 2);
assert!(args.is_empty());

§Errors

May return the same errors as parse.

source

pub fn single_quoted<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Remove surrounding quotations, if present, from the argument; parse it and advance.

Shorthand for .quoted().single::<T>()

§Examples

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new(r#""4" "2""#, &[Delimiter::Single(' ')]);

assert_eq!(args.single_quoted::<String>().unwrap(), "4");
assert_eq!(args.single_quoted::<u32>().unwrap(), 2);
assert!(args.is_empty());

§Errors

May return the same errors as Self::parse.

source

pub fn iter<T: FromStr>(&mut self) -> Iter<'_, T> ⓘ

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

By starting from the current offset, iterate over any available arguments until there are none.

Modifications of Iter::trimmed and Iter::quoted are also applied to all arguments if they were called.

§Examples

Assert that all of the numbers in the message are even.

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("4 2", &[Delimiter::Single(' ')]);

for arg in args.iter::<u32>() {
    // Zero troubles, zero worries.
    let arg = arg.unwrap_or(0);
    assert!(arg % 2 == 0);
}

assert!(args.is_empty());

source

pub fn raw(&self) -> RawArguments<'_> ⓘ

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Return an iterator over all unmodified arguments.

§Examples

Join the arguments by a comma and a space.

use serenity::framework::standard::{Args, Delimiter};

let args = Args::new("Harry Hermione Ronald", &[Delimiter::Single(' ')]);

let protagonists = args.raw().collect::<Vec<&str>>().join(", ");

assert_eq!(protagonists, "Harry, Hermione, Ronald");

source

pub fn raw_quoted(&self) -> RawArguments<'_> ⓘ

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Return an iterator over all arguments, stripped of their quotations if any were present.

§Examples

use serenity::framework::standard::{Args, Delimiter};

let args = Args::new("Saw \"The Mist\" \"A Quiet Place\"", &[Delimiter::Single(' ')]);

let horror_movies = args.raw_quoted().collect::<Vec<&str>>();

assert_eq!(&*horror_movies, &["Saw", "The Mist", "A Quiet Place"]);

source

pub fn find<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Search for any available argument that can be parsed, and remove it from the arguments queue.

§Note

The removal is irreversible. And happens after the search and the parse were successful.

§Note 2

“Arguments queue” is the list which contains all arguments that were deemed unique as defined by quotations and delimiters. The ‘removed’ argument can be, likewise, still accessed via Self::message.

§Examples

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("c4 2", &[Delimiter::Single(' ')]);

assert_eq!(args.find::<u32>().unwrap(), 2);
assert_eq!(args.single::<String>().unwrap(), "c4");
assert!(args.is_empty());

§Errors

Returns Error::Eos if no argument can be parsed.

source

pub fn find_n<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Search for any available argument that can be parsed.

§Examples

use serenity::framework::standard::{Args, Delimiter};

let mut args = Args::new("c4 2", &[Delimiter::Single(' ')]);

assert_eq!(args.find_n::<u32>().unwrap(), 2);

// The `2` is still here, so let's parse it again.
assert_eq!(args.single::<String>().unwrap(), "c4");
assert_eq!(args.single::<u32>().unwrap(), 2);
assert!(args.is_empty());

§Errors

Returns Error::Eos if no argument can be parsed.

source

pub fn message(&self) -> &str

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Get the original, unmodified message passed to the command.

source

pub fn rest(&self) -> &str

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Starting from the offset, return the remainder of available arguments.

source

pub fn remains(&self) -> Option<&str>

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Starting from the offset, return the remainder of available arguments.

Returns None if there are no remaining arguments.

source

pub fn len(&self) -> usize

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Return the full amount of recognised arguments. The length of the “arguments queue”.

§Note

The value returned is to be assumed to stay static. However, if Self::find was called previously, and was successful, then the value is subtracted by one.

source