Struct pico_args::Arguments

pub struct Arguments(_);

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.

pub fn from_env() -> Self

Creates a parser from env::args.

The executable path will be removed.

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

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

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

Checks that arguments contain a specified flag.

Must be used only once for each flag.

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.

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<Option<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<Option<T>, Error>

Parses a free-standing argument using a specified function.

Must be used only once for each argument.

Errors

• When any flags are left.
• When argument is not a UTF-8 string. Use [free_from_os_str] instead.
• When value parsing failed.

pub fn 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.

Must be used only once for each argument.

Errors

• When any flags are left.
• When value parsing failed.

pub fn free(self) -> Result<Vec<String>, Error>

Returns a list of free arguments as Strings.

This list will also include -, which indicates stdin.

Errors

• When any flags are left.
• When any of the arguments is not a UTF-8 string.

pub fn free_os(self) -> Result<Vec<OsString>, Error>

Returns a list of free arguments as OsStrings.

This list will also include -, which indicates stdin.

Errors

• When any flags are left. Only UTF-8 strings will be checked for flag prefixes.

pub fn finish(self) -> Result<(), Error>

Checks that all flags were processed.

Use it instead of free if you do not expect any free arguments.

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.