Struct getargs::Options

pub struct Options<'a, S> where
    S: AsRef<str>,  { /* fields omitted */ }

An argument parser.

See the crate documentation for more details.

Methods

impl<'a, S> Options<'a, S> where
    S: AsRef<str>, 

pub fn new(args: &[S]) -> Options<S>

Creates a new argument parser given the slice of arguments.

The argument parser only lives as long as the slice of arguments.

pub fn next(&self) -> Option<Result<Opt<'a>>>

Retrieves the next option.

Returns None if there are no more options. Returns Some(Err(..)) if a parse error occurs.

This method mutates the state of the parser (despite taking a shared reference to self).

This method does not retrieve any value that goes with the option. If the option requires an value, such as in --option=value, then you should call value after getting the option.

Examples

Basic usage:

use getargs::{Opt, Options};
let args = ["-a", "--bee", "foo"];
let opts = Options::new(&args);
assert_eq!(opts.next(), Some(Ok(Opt::Short('a'))));
assert_eq!(opts.next(), Some(Ok(Opt::Long("bee"))));
assert_eq!(opts.next(), None);

pub fn value_str(&self) -> Result<&'a str>

Retrieves the value passed for this option as a string.

This function returns an error if there is no value to return because the end of the argument list has been reached.

This function is not pure, and it mutates the state of the parser (despite taking a shared reference to self).

Panics

This method panics if next has not yet been called, or it is called twice for the same option.

Examples

Basic usage:

use getargs::{Opt, Options};
let args = ["-aay", "--bee=foo", "-c", "see", "bar"];
let opts = Options::new(&args);
assert_eq!(opts.next(), Some(Ok(Opt::Short('a'))));
assert_eq!(opts.value_str(), Ok("ay"));
assert_eq!(opts.next(), Some(Ok(Opt::Long("bee"))));
assert_eq!(opts.value_str(), Ok("foo"));
assert_eq!(opts.next(), Some(Ok(Opt::Short('c'))));
assert_eq!(opts.value_str(), Ok("see"));

pub fn value<T>(&self) -> Result<T> where
    T: FromStr,
    T::Err: Display, 

Retrieves the value passed for this option and parses it.

This method retrieves the value passed for the last option and parses it as any type that implements FromStr (and any potential error is Display). It returns an error if there is no value to return because the end of the argument list has been reached, or if the value failed to parse.

This function is not pure, and it mutates the state of the parser (despite taking a shared reference to self).

Panics

This method panics if next has not yet been called, or it is called twice for the same option.

Examples

Basic usage:

use getargs::{Error, Opt, Options, Result};
let args = ["-a1", "--bee=2.5", "-c", "see", "bar"];
let opts = Options::new(&args);
assert_eq!(opts.next(), Some(Ok(Opt::Short('a'))));
let val: Result<i32> = opts.value();
assert_eq!(val, Ok(1));
assert_eq!(opts.next(), Some(Ok(Opt::Long("bee"))));
assert_eq!(opts.value::<f64>(), Ok(2.5));
assert_eq!(opts.next(), Some(Ok(Opt::Short('c'))));
assert_eq!(opts.value::<i64>(), Err(Error::InvalidValue {
    opt: Opt::Short('c'),
    desc: "invalid digit found in string".to_string(),
    value: "see",
}));

pub fn arg_str(&self) -> Option<&'a S>

Retrieves the next positional argument as a string, after the options have been parsed.

This method returns the next positional argument after the parsed options as a string. This method must be called after the options has finished parsing.

After this method is called, this struct may be re-used to parse further options with next, or you can continue getting positional arguments (which will treat options as regular positional arguments).

This function is not pure, and it mutates the state of the parser (despite taking a shared reference to self).

Panics

This method panics if the option parsing is not yet complete; that is, it panics if next has not yet returned None at least once.

Examples

Basic usage:

use getargs::{Opt, Options};
let args = ["-a", "foo", "bar"];
let opts = Options::new(&args);
assert_eq!(opts.next(), Some(Ok(Opt::Short('a'))));
assert_eq!(opts.next(), None);
assert_eq!(opts.arg_str(), Some(&"foo"));
assert_eq!(opts.arg_str(), Some(&"bar"));
assert_eq!(opts.arg_str(), None);

pub fn arg<T>(&self) -> Option<Result<T>> where
    T: FromStr,
    T::Err: Display, 

Retrieves and parses the next positional argument, after the options have been parsed.

This method returns the next positional argument after the parsed options, parsed as any type that implements FromStr (and any potential error is Display). This method must be called after the options has finished parsing.

After this method is called, this struct may be re-used to parse further options with next, or you can continue getting positional arguments (which will treat options as regular positional arguments).

This function is not pure, and it mutates the state of the parser (despite taking a shared reference to self).

Panics

This method panics if the option parsing is not yet complete; that is, it panics if next has not yet returned None at least once.

Examples

Basic usage:

use getargs::{Error, Opt, Options, Result};
let args = ["-a", "1", "3.5", "foo"];
let opts = Options::new(&args);
assert_eq!(opts.next(), Some(Ok(Opt::Short('a'))));
assert_eq!(opts.next(), None);
let arg: Option<Result<i32>> = opts.arg();
assert_eq!(arg, Some(Ok(1)));
assert_eq!(opts.arg::<f64>(), Some(Ok(3.5)));
assert_eq!(opts.arg::<i32>(), Some(Err(Error::InvalidArg {
    desc: "invalid digit found in string".to_string(),
    value: "foo",
})));

pub fn args(&self) -> &'a [S]

Retrieves the rest of the positional arguments, after the options have been parsed.

This method returns the list of arguments after the parsed options.

Panics

This method panics if the option parsing is not yet complete; that is, it panics if next has not yet returned None at least once.

Examples

Basic usage:

use getargs::{Opt, Options};
let args = ["-a", "foo", "bar"];
let opts = Options::new(&args);
assert_eq!(opts.next(), Some(Ok(Opt::Short('a'))));
assert_eq!(opts.next(), None);
assert_eq!(opts.args(), &["foo", "bar"]);