Struct Arguments

pub struct Arguments(/* private fields */);

An arguments parser.

Implementations

impl Arguments

pub fn from_vec(args: Vec<OsString>) -> Self

Creates a parser from a vector of arguments.

The executable path must be removed.

This can be used for supporting -- arguments to forward to another program. See examples/dash_dash.rs for an example.

pub fn from_env() -> Self

Creates a parser from env::args_os.

The executable path will be removed.

pub fn subcommand(&mut self) -> Result<Option<String>, Error>

Parses the name of the subcommand, that is, the first positional argument.

Returns None when subcommand starts with - or when there are no arguments left.

Errors

• When arguments is not a UTF-8 string.

pub fn contains<A: Into<Keys>>(&mut self, keys: A) -> bool

Checks that arguments contain a specified flag.

Searches through all arguments, not only the first/next one.

Calling this method “consumes” the flag: if a flag is present n times then the first n calls to contains for that flag will return true, and subsequent calls will return false.

When the “combined-flags” feature is used, repeated letters count as repeated flags: -vvv is treated the same as -v -v -v.

pub fn value_from_str<A, T>(&mut self, keys: A) -> Result<T, Error>

where A: Into<Keys>, T: FromStr, <T as FromStr>::Err: Display,

Parses a key-value pair using FromStr trait.

This is a shorthand for value_from_fn("--key", FromStr::from_str)

pub fn value_from_fn<A: Into<Keys>, T, E: Display>( &mut self, keys: A, f: fn(_: &str) -> Result<T, E>, ) -> Result<T, Error>

Parses a key-value pair using a specified function.

Searches through all argument, not only the first/next one.

When a key-value pair is separated by a space, the algorithm will threat the next argument after the key as a value, even if it has a -/-- prefix. So a key-value pair like --key --value is not an error.

Must be used only once for each option.

Errors

• When option is not present.
• When key or value is not a UTF-8 string. Use value_from_os_str instead.
• When value parsing failed.
• When key-value pair is separated not by space or =.

pub fn opt_value_from_str<A, T>(&mut self, keys: A) -> Result<Option<T>, Error>

where A: Into<Keys>, T: FromStr, <T as FromStr>::Err: Display,

Parses an optional key-value pair using FromStr trait.

This is a shorthand for opt_value_from_fn("--key", FromStr::from_str)

pub fn opt_value_from_fn<A: Into<Keys>, T, E: Display>( &mut self, keys: A, f: fn(_: &str) -> Result<T, E>, ) -> Result<Option<T>, Error>

Parses an optional key-value pair using a specified function.

The same as value_from_fn, but returns Ok(None) when option is not present.

pub fn values_from_str<A, T>(&mut self, keys: A) -> Result<Vec<T>, Error>

where A: Into<Keys>, T: FromStr, <T as FromStr>::Err: Display,

Parses multiple key-value pairs into the Vec using FromStr trait.

This is a shorthand for values_from_fn("--key", FromStr::from_str)

pub fn values_from_fn<A: Into<Keys>, T, E: Display>( &mut self, keys: A, f: fn(_: &str) -> Result<T, E>, ) -> Result<Vec<T>, Error>

Parses multiple key-value pairs into the Vec using a specified function.

This functions can be used to parse arguments like:
--file /path1 --file /path2 --file /path3
But not --file /path1 /path2 /path3.

Arguments can also be separated: --file /path1 --some-flag --file /path2

This method simply executes opt_value_from_fn multiple times.

An empty Vec is not an error.

pub fn value_from_os_str<A: Into<Keys>, T, E: Display>( &mut self, keys: A, f: fn(_: &OsStr) -> Result<T, E>, ) -> Result<T, Error>

Parses a key-value pair using a specified function.

Unlike value_from_fn, parses &OsStr and not &str.

Must be used only once for each option.

Errors

• When option is not present.
• When value parsing failed.
• When key-value pair is separated not by space. Only value_from_fn supports = separator.

pub fn opt_value_from_os_str<A: Into<Keys>, T, E: Display>( &mut self, keys: A, f: fn(_: &OsStr) -> Result<T, E>, ) -> Result<Option<T>, Error>

Parses an optional key-value pair using a specified function.

The same as value_from_os_str, but returns Ok(None) when option is not present.

pub fn values_from_os_str<A: Into<Keys>, T, E: Display>( &mut self, keys: A, f: fn(_: &OsStr) -> Result<T, E>, ) -> Result<Vec<T>, Error>

Parses multiple key-value pairs into the Vec using a specified function.

This method simply executes opt_value_from_os_str multiple times.

Unlike values_from_fn, parses &OsStr and not &str.

An empty Vec is not an error.

pub fn free_from_str<T>(&mut self) -> Result<T, Error>

where T: FromStr, <T as FromStr>::Err: Display,

Parses a free-standing argument using FromStr trait.

This is a shorthand for free_from_fn(FromStr::from_str)

pub fn free_from_fn<T, E: Display>( &mut self, f: fn(_: &str) -> Result<T, E>, ) -> Result<T, Error>

Parses a free-standing argument using a specified function.

Parses the first argument from the list of remaining arguments. Therefore, it’s up to the caller to check if the argument is actually a free-standing one and not an unused flag/option.

Sadly, there is no way to automatically check for flag/option. -, --, -1, -0.5, --.txt - all of this arguments can have different meaning depending on the caller requirements.

Must be used only once for each argument.

Errors

• When argument is not a UTF-8 string. Use free_from_os_str instead.
• When argument parsing failed.
• When argument is not present.

pub fn free_from_os_str<T, E: Display>( &mut self, f: fn(_: &OsStr) -> Result<T, E>, ) -> Result<T, Error>

Parses a free-standing argument using a specified function.

The same as free_from_fn, but parses &OsStr instead of &str.

pub fn opt_free_from_str<T>(&mut self) -> Result<Option<T>, Error>

where T: FromStr, <T as FromStr>::Err: Display,

Parses an optional free-standing argument using FromStr trait.

The same as free_from_str, but returns Ok(None) when argument is not present.

pub fn opt_free_from_fn<T, E: Display>( &mut self, f: fn(_: &str) -> Result<T, E>, ) -> Result<Option<T>, Error>

Parses an optional free-standing argument using a specified function.

The same as free_from_fn, but returns Ok(None) when argument is not present.

pub fn opt_free_from_os_str<T, E: Display>( &mut self, f: fn(_: &OsStr) -> Result<T, E>, ) -> Result<Option<T>, Error>

Parses a free-standing argument using a specified function.

The same as free_from_os_str, but returns Ok(None) when argument is not present.

pub fn finish(self) -> Vec<OsString>

Returns a list of remaining arguments.

It’s up to the caller what to do with them. One can report an error about unused arguments, other can use them for further processing.

Trait Implementations

impl Clone for Arguments

fn clone(&self) -> Arguments

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Arguments

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

Formats the value using the given formatter.