[−][src]Struct serenity::framework::standard::Args
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
[src]
impl Args
pub fn new(message: &str, possible_delimiters: &[String]) -> Self
[src]
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>
[src]
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
[src]
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)
[src]
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,
[src]
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,
[src]
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>
[src]
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>>
[src]
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>pub fn iter<T: FromStr>(&mut self) -> Iter<T> where
T::Err: StdError,
[src]
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,
[src]
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>
[src]
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,
[src]
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,
[src]
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,
[src]
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,
[src]
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,
[src]
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,
[src]
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
[src]
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
[src]
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
[src]
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
[src]
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
[src]
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
[src]
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)
[src]
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)
[src]
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)
[src]
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
[src]
pub fn len_quoted(&mut self) -> usize
: Its task was merged with len
, please use it instead.
Trait Implementations
impl PartialEq<str> for Args
[src]
impl PartialEq<str> for Args
fn eq(&self, other: &str) -> bool
[src]
fn eq(&self, other: &str) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
#[must_use]
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ne(&self, other: &Rhs) -> bool
This method tests for !=
.
impl<'a> PartialEq<&'a str> for Args
[src]
impl<'a> PartialEq<&'a str> for Args
fn eq(&self, other: &&'a str) -> bool
[src]
fn eq(&self, other: &&'a str) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
#[must_use]
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ne(&self, other: &Rhs) -> bool
This method tests for !=
.
impl PartialEq<Args> for Args
[src]
impl PartialEq<Args> for Args
fn eq(&self, other: &Self) -> bool
[src]
fn eq(&self, other: &Self) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
#[must_use]
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
#[must_use]
fn ne(&self, other: &Rhs) -> bool
This method tests for !=
.
impl Clone for Args
[src]
impl Clone for Args
fn clone(&self) -> Args
[src]
fn clone(&self) -> Args
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
impl Eq for Args
[src]
impl Eq for Args
impl Deref for Args
[src]
impl Deref for Args
type Target = str
The resulting type after dereferencing.
fn deref(&self) -> &Self::Target
[src]
fn deref(&self) -> &Self::Target
Dereferences the value.
impl Debug for Args
[src]
impl Debug for Args
Auto Trait Implementations
Blanket Implementations
impl<T, U> Into for T where
U: From<T>,
[src]
impl<T, U> Into for T where
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
impl<T> ToOwned for T where
T: Clone,
type Owned = T
fn to_owned(&self) -> T
[src]
fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
fn clone_into(&self, target: &mut T)
[src]
fn clone_into(&self, target: &mut T)
🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more
impl<T> From for T
[src]
impl<T> From for T
impl<T, U> TryFrom for T where
T: From<U>,
[src]
impl<T, U> TryFrom for T where
T: From<U>,
type Error = !
try_from
)The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
try_from
)Performs the conversion.
impl<T> Borrow for T where
T: ?Sized,
[src]
impl<T> Borrow for T where
T: ?Sized,
impl<T> BorrowMut for T where
T: ?Sized,
[src]
impl<T> BorrowMut for T where
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T, U> TryInto for T where
U: TryFrom<T>,
[src]
impl<T, U> TryInto for T where
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
try_from
)The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
try_from
)Performs the conversion.
impl<T> Any for T where
T: 'static + ?Sized,
[src]
impl<T> Any for T where
T: 'static + ?Sized,
fn get_type_id(&self) -> TypeId
[src]
fn get_type_id(&self) -> TypeId
🔬 This is a nightly-only experimental API. (get_type_id
)
this method will likely be replaced by an associated static
Gets the TypeId
of self
. Read more
impl<T> Erased for T
impl<T> Erased for T
impl<T> Typeable for T where
T: Any,
impl<T> Typeable for T where
T: Any,
impl<T> DebugAny for T where
T: Any + Debug,
[src]
impl<T> DebugAny for T where
T: Any + Debug,
impl<T> CloneAny for T where
T: Clone + Any,
[src]
impl<T> CloneAny for T where
T: Clone + Any,
fn clone_any(&self) -> Box<dyn CloneAny + 'static>
[src]
fn clone_any(&self) -> Box<dyn CloneAny + 'static>
fn clone_any_send(&self) -> Box<dyn CloneAny + 'static + Send> where
T: Send,
[src]
fn clone_any_send(&self) -> Box<dyn CloneAny + 'static + Send> where
T: Send,
fn clone_any_sync(&self) -> Box<dyn CloneAny + 'static + Sync> where
T: Sync,
[src]
fn clone_any_sync(&self) -> Box<dyn CloneAny + 'static + Sync> where
T: Sync,
fn clone_any_send_sync(&self) -> Box<dyn CloneAny + 'static + Sync + Send> where
T: Send + Sync,
[src]
fn clone_any_send_sync(&self) -> Box<dyn CloneAny + 'static + Sync + Send> where
T: Send + Sync,
impl<T> UnsafeAny for T where
T: Any,
impl<T> UnsafeAny for T where
T: Any,