pub struct Args { /* private fields */ }
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
sourceimpl Args
impl Args
sourcepub fn new(message: &str, possible_delimiters: &[Delimiter]) -> Self
pub fn new(message: &str, possible_delimiters: &[Delimiter]) -> 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, 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");
sourcepub fn advance(&mut self) -> &mut Self
pub fn advance(&mut self) -> &mut Self
Move to the next argument. This increments the offset pointer.
Does nothing if the message is empty.
sourcepub fn rewind(&mut self) -> &mut Self
pub fn rewind(&mut self) -> &mut Self
Go one step behind. This decrements the offset pointer.
Does nothing if the offset pointer is 0
.
sourcepub fn current(&self) -> Option<&str>
pub fn current(&self) -> Option<&str>
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);
sourcepub fn trimmed(&mut self) -> &mut Self
pub fn trimmed(&mut self) -> &mut Self
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 ");
sourcepub fn quoted(&mut self) -> &mut Self
pub fn quoted(&mut self) -> &mut Self
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\"");
sourcepub fn parse<T: FromStr>(&self) -> Result<T, Error<T::Err>>
pub fn parse<T: FromStr>(&self) -> Result<T, Error<T::Err>>
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.
sourcepub fn single<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>
pub fn single<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>
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
.
sourcepub fn single_quoted<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>
pub fn single_quoted<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>
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
.
sourcepub fn iter<T: FromStr>(&mut self) -> Iter<'_, T>ⓘNotable traits for Iter<'a, T>impl<'a, T: FromStr> Iterator for Iter<'a, T> type Item = Result<T, Error<T::Err>>;
pub fn iter<T: FromStr>(&mut self) -> Iter<'_, T>ⓘNotable traits for Iter<'a, T>impl<'a, T: FromStr> Iterator for Iter<'a, T> type Item = Result<T, Error<T::Err>>;
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());
sourcepub fn raw(&self) -> RawArguments<'_>ⓘNotable traits for RawArguments<'a>impl<'a> Iterator for RawArguments<'a> type Item = &'a str;
pub fn raw(&self) -> RawArguments<'_>ⓘNotable traits for RawArguments<'a>impl<'a> Iterator for RawArguments<'a> type Item = &'a str;
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");
sourcepub fn raw_quoted(&self) -> RawArguments<'_>ⓘNotable traits for RawArguments<'a>impl<'a> Iterator for RawArguments<'a> type Item = &'a str;
pub fn raw_quoted(&self) -> RawArguments<'_>ⓘNotable traits for RawArguments<'a>impl<'a> Iterator for RawArguments<'a> type Item = &'a str;
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"]);
sourcepub fn find<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>
pub fn find<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>
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.
sourcepub fn find_n<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>
pub fn find_n<T: FromStr>(&mut self) -> Result<T, Error<T::Err>>
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.
sourcepub fn rest(&self) -> &str
pub fn rest(&self) -> &str
Starting from the offset, return the remainder of available arguments.
sourcepub fn remains(&self) -> Option<&str>
pub fn remains(&self) -> Option<&str>
Starting from the offset, return the remainder of available arguments.
Returns None
if there are no remaining arguments.
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
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.
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Args
impl Send for Args
impl Sync for Args
impl Unpin for Args
impl UnwindSafe for Args
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more