Struct Options

pub struct Options { /* private fields */ }

A description of the options that a program can handle.

Implementations

impl Options

pub fn new() -> Options

Create a blank set of options.

pub fn parsing_style(&mut self, style: ParsingStyle) -> &mut Options

Set the parsing style.

pub fn long_only(&mut self, long_only: bool) -> &mut Options

Set or clear “long options only” mode.

In “long options only” mode, short options cannot be clustered together, and long options can be given with either a single “-” or the customary “–”. This mode also changes the meaning of “-a=b”; in the ordinary mode this will parse a short option “-a” with argument “=b”; whereas in long-options-only mode the argument will be simply “b”.

pub fn opt( &mut self, short_name: &str, long_name: &str, desc: &str, hint: &str, hasarg: HasArg, occur: Occur, ) -> &mut Options

Create a generic option group, stating all parameters explicitly.

pub fn optflag( &mut self, short_name: &str, long_name: &str, desc: &str, ) -> &mut Options

Create a long option that is optional and does not take an argument.

• short_name - e.g. "h" for a -h option, or "" for none
• long_name - e.g. "help" for a --help option, or "" for none
• desc - Description for usage help

Example

let mut opts = Options::new();
opts.optflag("h", "help", "help flag");

let matches = opts.parse(&["-h"]).unwrap();
assert!(matches.opt_present("h"));

pub fn optflagmulti( &mut self, short_name: &str, long_name: &str, desc: &str, ) -> &mut Options

Create a long option that can occur more than once and does not take an argument.

• short_name - e.g. "h" for a -h option, or "" for none
• long_name - e.g. "help" for a --help option, or "" for none
• desc - Description for usage help

Example

let mut opts = Options::new();
opts.optflagmulti("v", "verbose", "verbosity flag");

let matches = opts.parse(&["-v", "--verbose"]).unwrap();
assert_eq!(2, matches.opt_count("v"));

pub fn optflagopt( &mut self, short_name: &str, long_name: &str, desc: &str, hint: &str, ) -> &mut Options

Create a long option that is optional and takes an optional argument.

• short_name - e.g. "h" for a -h option, or "" for none
• long_name - e.g. "help" for a --help option, or "" for none
• desc - Description for usage help
• hint - Hint that is used in place of the argument in the usage help, e.g. "FILE" for a -o FILE option

Example

let mut opts = Options::new();
opts.optflagopt("t", "text", "flag with optional argument", "TEXT");

let matches = opts.parse(&["--text"]).unwrap();
assert_eq!(None, matches.opt_str("text"));

let matches = opts.parse(&["--text=foo"]).unwrap();
assert_eq!(Some("foo".to_owned()), matches.opt_str("text"));

pub fn optmulti( &mut self, short_name: &str, long_name: &str, desc: &str, hint: &str, ) -> &mut Options

Create a long option that is optional, takes an argument, and may occur multiple times.

• short_name - e.g. "h" for a -h option, or "" for none
• long_name - e.g. "help" for a --help option, or "" for none
• desc - Description for usage help
• hint - Hint that is used in place of the argument in the usage help, e.g. "FILE" for a -o FILE option

Example

let mut opts = Options::new();
opts.optmulti("t", "text", "text option", "TEXT");

let matches = opts.parse(&["-t", "foo", "--text=bar"]).unwrap();

let values = matches.opt_strs("t");
assert_eq!(2, values.len());
assert_eq!("foo", values[0]);
assert_eq!("bar", values[1]);

pub fn optopt( &mut self, short_name: &str, long_name: &str, desc: &str, hint: &str, ) -> &mut Options

Create a long option that is optional and takes an argument.

• short_name - e.g. "h" for a -h option, or "" for none
• long_name - e.g. "help" for a --help option, or "" for none
• desc - Description for usage help
• hint - Hint that is used in place of the argument in the usage help, e.g. "FILE" for a -o FILE option

Example

let mut opts = Options::new();
opts.optopt("o", "optional", "optional text option", "TEXT");

let matches = opts.parse(&["arg1"]).unwrap();
assert_eq!(None, matches.opt_str("optional"));

let matches = opts.parse(&["--optional", "foo", "arg1"]).unwrap();
assert_eq!(Some("foo".to_owned()), matches.opt_str("optional"));

pub fn reqopt( &mut self, short_name: &str, long_name: &str, desc: &str, hint: &str, ) -> &mut Options

Create a long option that is required and takes an argument.

• short_name - e.g. "h" for a -h option, or "" for none
• long_name - e.g. "help" for a --help option, or "" for none
• desc - Description for usage help
• hint - Hint that is used in place of the argument in the usage help, e.g. "FILE" for a -o FILE option

Example

let mut opts = Options::new();
opts.optopt("o", "optional", "optional text option", "TEXT");
opts.reqopt("m", "mandatory", "madatory text option", "TEXT");

let result = opts.parse(&["--mandatory", "foo"]);
assert!(result.is_ok());

let result = opts.parse(&["--optional", "foo"]);
assert!(result.is_err());
assert_eq!(Fail::OptionMissing("mandatory".to_owned()), result.unwrap_err());

pub fn parse<C>(&self, args: C) -> Result<Matches, Fail>

where C: IntoIterator, <C as IntoIterator>::Item: AsRef<OsStr>,

Parse command line arguments according to the provided options.

On success returns Ok(Matches). Use methods such as opt_present opt_str, etc. to interrogate results.

Panics

Returns Err(Fail) on failure: use the Debug implementation of Fail to display information about it.

pub fn short_usage(&self, program_name: &str) -> String

Derive a short one-line usage summary from a set of long options.

pub fn usage(&self, brief: &str) -> String

Derive a formatted message from a set of options.

pub fn usage_with_format<F>(&self, formatter: F) -> String

where F: FnMut(&mut dyn Iterator<Item = String>) -> String,

Derive a custom formatted message from a set of options. The formatted options provided to a closure as an iterator.

Trait Implementations

impl Clone for Options

fn clone(&self) -> Options

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Options

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

Formats the value using the given formatter.

impl Default for Options

fn default() -> Options

Returns the “default value” for a type.

impl PartialEq for Options

fn eq(&self, other: &Options) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Options

impl StructuralPartialEq for Options