Struct serenity::framework::standard::Args

pub struct Args { /* fields omitted */ }

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;

let mut args = Args::new("hello world!", &[" ".to_string()]); // 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;

// 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""#, &[" ".to_string()]);

// 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;

let mut args = Args::new("4 2", &[" ".to_string()]);

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 *_n methods:

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

let mut args = Args::new("trois cinq quatre six", &[" ".to_string()]);

assert_eq!(args.single_n::<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.single_n::<String>().unwrap(), "trois");
assert_eq!(args.single_n::<String>().unwrap(), "trois");
assert_eq!(args.single_n::<String>().unwrap(), "trois");
assert_eq!(args.single_n::<String>().unwrap(), "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");

Methods

impl Args

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

Create a new instance of Args for parsing arguments.

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

Example

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

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.
&[" ".to_string()],
);

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");

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

Retrieves the current argument. Does not parse.

Note

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

Examples

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

let mut args = Args::new("4 2", &[" ".to_string()]);

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

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

Trims the current argument off leading and trailing whitespace.

Examples

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

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

assert_eq!(args.trim().current(), Some("42"));

pub fn trim_all(&mut self)

Trims all of the arguments after the offset off leading and trailing whitespace.

Examples

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

let mut args = Args::new("     42     , 84 ,\t168\t", &[",".to_string()]);

args.trim_all();
assert_eq!(args.single::<String>().unwrap(), "42");
assert_eq!(args.single::<String>().unwrap(), "84");
assert_eq!(args.single::<String>().unwrap(), "168");

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

Parses the current argument and advances.

Examples

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

let mut args = Args::new("4 2", &[" ".to_string()]);

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);

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

Like single, but doesn't advance.

Examples

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

let args = Args::new("4 2", &[" ".to_string()]);

assert_eq!(args.single_n::<u32>().unwrap(), 4);
assert_eq!(args.rest(), "4 2");

pub fn skip(&mut self) -> Option<String>

"Skip" the argument. Equivalent to args.single::<String>().ok().

Examples

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

let mut args = Args::new("4 2", &[" ".to_string()]);

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

pub fn skip_for(&mut self, i: u32) -> Option<Vec<String>>

Like skip, but do it multiple times.

Examples

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

let mut args = Args::new("man of culture topknot", &[" ".to_string()]);

args.skip_for(3);
assert_eq!(args.remaining(), 1);
assert_eq!(args.single::<String>().unwrap(), "topknot");

Important traits for Iter<'a, T>

impl<'a, T: FromStr> Iterator for Iter<'a, T> where
    T::Err: StdError,  type Item = Result<T, Error<T::Err>>;

pub fn iter<T: FromStr>(&mut self) -> Iter<T> where
    T::Err: StdError, 

Iterate until end of message.

Examples

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

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

let mut args = Args::new("4 2", &[" ".to_string()]);

for arg in args.iter::<u32>() {
    // Default to zero in case some linguist turns our numbers into words and can't parse those.
    let arg = arg.unwrap_or(0);
    assert!(arg % 2 == 0);
}

assert!(args.is_empty());

pub fn multiple<T: FromStr>(self) -> Result<Vec<T>, Error<T::Err>> where
    T::Err: StdError, 

Parses all of the remaining arguments and returns them in a Vec. Equivalent to args.iter().collect::<Vec<_>>().

Examples

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

let args = Args::new("4 2", &[" ".to_string()]);

assert_eq!(*args.multiple::<u32>().unwrap(), [4, 2]);

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

Retrieves the current argument and also removes quotes around it if they're present. Does not parse.

Note

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

Examples

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

let mut args = Args::new("4 \"2\"", &[" ".to_string()]);

assert_eq!(args.current_quoted(), Some("4"));
args.next();
assert_eq!(args.current_quoted(), Some("2"));
args.next();
assert_eq!(args.current_quoted(), None);

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

Like single, but accounts quotes.

Examples

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

let mut args = Args::new(r#""4 2""#, &[" ".to_string()]);

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

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

Like single_quoted, but doesn't advance.

Examples

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

let mut args = Args::new(r#""4 2""#, &[" ".to_string()]);

assert_eq!(args.single_quoted_n::<String>().unwrap(), "4 2");
assert_eq!(args.rest(), r#""4 2""#);

pub fn iter_quoted<T: FromStr>(&mut self) -> IterQuoted<T> where
    T::Err: StdError, 

Like iter, but accounts quotes.

Examples

Assert that all of the numbers in quotations in the message are odd.

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

let mut args = Args::new(r#""5" "3""#, &[" ".to_string()]);

for arg in args.iter_quoted::<u32>() {
    // Default to zero in case some linguist turns our numbers into words and can't parse those.
    let arg = arg.unwrap_or(0);
    assert!(arg % 2 != 0);
}

assert!(args.is_empty());

pub fn multiple_quoted<T: FromStr>(self) -> Result<Vec<T>, Error<T::Err>> where
    T::Err: StdError, 

Like multiple, but accounts quotes.

Examples

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

let mut args = Args::new(r#""4" "2""#, &[" ".to_string()]);

assert_eq!(*args.multiple_quoted::<u32>().unwrap(), [4, 2]);

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

Returns the first argument that can be parsed and removes it from the message. The suitable argument can be in an arbitrary position in the message. Likewise, takes quotes into account.

Note

Unlike the rest, this function permantently removes the argument if it was found and was succesfully parsed. Hence, use with caution.

Examples

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

let mut args = Args::new("c4 2", &[" ".to_string()]);

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

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

Like find, but does not remove it.

Examples

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

let mut args = Args::new("c4 2", &[" ".to_string()]);

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

// The `69` 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());

pub fn full(&self) -> &str

Gets original message passed to the command.

Examples

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

let args = Args::new("42 69", &[" ".to_string()]);

assert_eq!(args.full(), "42 69");

pub fn full_quoted(&self) -> &str

Gets the original message passed to the command, but without quotes (if both starting and ending quotes are present, otherwise returns as is).

Examples

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

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

assert_eq!(args.full_quoted(), "42 69");

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

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

assert_eq!(args.full_quoted(), "\"42 69");

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

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

assert_eq!(args.full_quoted(), "42 69\"");

pub fn rest(&self) -> &str

Returns the message starting from the token in the current argument offset; the "rest" of the message.

Examples

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

let mut args = Args::new("to tre fire", &[" ".to_string()]);

assert_eq!(args.rest(), "to tre fire");

args.skip();

assert_eq!(args.rest(), "tre fire");

args.skip();

assert_eq!(args.rest(), "fire");

args.skip();

assert_eq!(args.rest(), "");

pub fn len(&self) -> usize

The full amount of recognised arguments.

Note

This never changes. Except for find, which upon success, subtracts the length by 1. (e.g len of 3 becomes 2)

Examples

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

let mut args = Args::new("4 2", &[" ".to_string()]);

assert_eq!(args.len(), 2); // `2` because `["4", "2"]`

pub fn is_empty(&self) -> bool

Returns true if there are no arguments left.

Examples

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

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

// will be `true` because passed message is empty thus no arguments.
assert!(args.is_empty());

pub fn remaining(&self) -> usize

Amount of arguments still available.

Examples

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

let mut args = Args::new("2 4", &[" ".to_string()]);

assert_eq!(args.remaining(), 2);

args.skip();

assert_eq!(args.remaining(), 1);

pub fn next(&mut self)

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

Examples

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

let mut args = Args::new("4 2", &[" ".to_string()]);

args.next();

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

pub fn rewind(&mut self)

Go one step behind. This decrements the offset pointer.

Examples

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

let mut args = Args::new("4 2", &[" ".to_string()]);

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

// By this point, we can only parse 2 now.
// However, with the help of `rewind`, we can mess with 4 again.
args.rewind();

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

pub fn restore(&mut self)

Go back to the starting point.

Examples

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

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

// Let's parse 'em numbers!
assert_eq!(args.single::<u32>().unwrap(), 42);
assert_eq!(args.single::<u32>().unwrap(), 420);
assert_eq!(args.single::<u32>().unwrap(), 69);

// Oh, no! I actually wanted to multiply all of them by 2!
// I don't want to call `rewind` 3 times manually....
// Wait, I could just go entirely back!
args.restore();

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

pub fn len_quoted(&mut self) -> usize

Deprecated since 0.5.3:

Its task was merged with len, please use it instead.

Like len, but accounts quotes.

Examples

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

let mut args = Args::new(r#""42" "69""#, &[" ".to_string()]);

assert_eq!(args.len_quoted(), 2); // `2` because `["42", "69"]`

Trait Implementations

impl PartialEq<str> for Args

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

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

#[must_use]

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

This method tests for !=.

impl<'a> PartialEq<&'a str> for Args

fn eq(&self, other: &&'a str) -> bool

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

#[must_use]

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

This method tests for !=.

impl PartialEq<Args> for Args

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

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

#[must_use]

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

This method tests for !=.

impl Clone for Args

fn clone(&self) -> Args

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Eq for Args

impl Debug for Args

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

Formats the value using the given formatter.

impl Deref for Args

type Target = str

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.