From f79fc64c7473230c496fd3ec5b010f01bc803a9e Mon Sep 17 00:00:00 2001 From: Zdenek Crha Date: Mon, 28 Dec 2020 18:15:46 +0100 Subject: [PATCH 1/2] Update outdated top level documentation Rewrite the usage introduction to mention only builder-like methods that add option config when creating instance of Options struct. Passing vector of components is not supported now and the working may cause confusion. Add mention of the double-dash '--' argument and how it works to the overview of option handling --- src/lib.rs | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 51ba7787..e722b90b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,19 +12,21 @@ //! Simple getopt alternative. //! -//! Construct a vector of options, either by using `reqopt`, `optopt`, and -//! `optflag` or by building them from components yourself, and pass them to -//! `getopts`, along with a vector of actual arguments (not including -//! `argv[0]`). You'll either get a failure code back, or a match. You'll have -//! to verify whether the amount of 'free' arguments in the match is what you -//! expect. Use `opt_*` accessors to get argument values out of the matches -//! object. +//! Construct instance of `Options` and configure it by using `reqopt()`, +//! `optopt()` and other methods that add option configuration. Then call +//! `parse()` method and pass into it a vector of actual arguments (not +//! including `argv[0]`). +//! +//! You'll either get a failure code back, or a match. You'll have to verify +//! whether the amount of 'free' arguments in the match is what you expect. Use +//! `opt_*` accessors to get argument values out of the matches object. //! //! Single-character options are expected to appear on the command line with a //! single preceding dash; multiple-character options are expected to be //! proceeded by two dashes. Options that expect an argument accept their //! argument following either a space or an equals sign. Single-character -//! options don't require the space. +//! options don't require the space. Everything after double-dash "--" argument +//! is considered to be a 'free' argument, even if it starts with dash. //! //! # Usage //! From 90f3fe9cb2bfa303d5fe64f7ec76eee31433614a Mon Sep 17 00:00:00 2001 From: Zdenek Crha Date: Mon, 28 Dec 2020 18:51:53 +0100 Subject: [PATCH 2/2] Add usage examples for methods that add option config Provide example usage for methods that configure accepted options. The examples describe how to do basic setup and how to query parsed Matches instance for builder-like methods. The only exception is the opt() method which provides too much freedom of configuration to write short sensible example. --- src/lib.rs | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index e722b90b..e0b0e9b4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -194,6 +194,17 @@ impl Options { /// * `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 + /// + /// ``` + /// # use getopts::Options; + /// let mut opts = Options::new(); + /// opts.optflag("h", "help", "help flag"); + /// + /// let matches = opts.parse(&["-h"]).unwrap(); + /// assert!(matches.opt_present("h")); + /// ``` pub fn optflag(&mut self, short_name: &str, long_name: &str, desc: &str) -> &mut Options { validate_names(short_name, long_name); self.grps.push(OptGroup { @@ -213,6 +224,17 @@ impl Options { /// * `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 + /// + /// ``` + /// # use getopts::Options; + /// 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 optflagmulti(&mut self, short_name: &str, long_name: &str, desc: &str) -> &mut Options { validate_names(short_name, long_name); self.grps.push(OptGroup { @@ -233,6 +255,20 @@ impl Options { /// * `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 + /// + /// ``` + /// # use getopts::Options; + /// 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 optflagopt( &mut self, short_name: &str, @@ -260,6 +296,21 @@ impl Options { /// * `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 + /// + /// ``` + /// # use getopts::Options; + /// 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 optmulti( &mut self, short_name: &str, @@ -286,6 +337,21 @@ impl Options { /// * `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 + /// + /// ``` + /// # use getopts::Options; + /// # use getopts::Fail; + /// 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 optopt( &mut self, short_name: &str, @@ -312,6 +378,23 @@ impl Options { /// * `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 + /// + /// ``` + /// # use getopts::Options; + /// # use getopts::Fail; + /// 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 reqopt( &mut self, short_name: &str,