Indices

CHANGELOG.md

@@ -1,3 +1,28 @@
+<a name="v2.31.0"></a>
+## v2.31.0 (2018-03-04)
+
+
+#### Features
+
+* **Arg Indices:**  adds the ability to query argument value indices ([f58d0576](https://github.com/kbknapp/clap-rs/commit/f58d05767ec8133c8eb2de117cb642b9ae29ccbc))
+* **Indices:**  implements an Indices<Item=&usize> iterator ([1e67be44](https://github.com/kbknapp/clap-rs/commit/1e67be44f0ccf161cc84c4e6082382072e89c302))
+* **Raw Args** adds a convenience function to `Arg` that allows implying all of `Arg::last` `Arg::allow_hyphen_values` and `Arg::multiple(true)` ([66a78f29](https://github.com/kbknapp/clap-rs/commit/66a78f2972786f5fe7c07937a1ac23da2542afd2))
+
+#### Documentation
+
+*   Fix some typos and markdown issues. ([935ba0dd](https://github.com/kbknapp/clap-rs/commit/935ba0dd547a69c3f636c5486795012019408794))
+* **Arg Indices:**  adds the documentation for the arg index querying methods ([50bc0047](https://github.com/kbknapp/clap-rs/commit/50bc00477afa64dc6cdc5de161d3de3ba1d105a7))
+* **CONTRIBUTING.md:**  fix url to clippy upstream repo to point to https://github.com/rust-lang-nursery/rust-clippy instead of https://github.com/Manishearth/rust-clippy ([42407d7f](https://github.com/kbknapp/clap-rs/commit/42407d7f21d794103cda61f49d2615aae0a4bcd9))
+* **Values:**  improves the docs example of the Values iterator ([74075d65](https://github.com/kbknapp/clap-rs/commit/74075d65e8db1ddb5e2a4558009a5729d749d1b6))
+* Updates readme to hint that the `wrap_help` feature is a thing ([fc7ab227](https://github.com/kbknapp/clap-rs/commit/66a78f2972786f5fe7c07937a1ac23da2542afd2))
+
+### Improvements
+
+*  Cargo.toml: use codegen-units = 1 in release and bench profiles ([19f425ea](https://github.com/kbknapp/clap-rs/commit/66a78f2972786f5fe7c07937a1ac23da2542afd2))
+*  Adds WASM support (clap now compiles on WASM!) ([689949e5](https://github.com/kbknapp/clap-rs/commit/689949e57d390bb61bc69f3ed91f60a2105738d0))
+*  Uses the short help tool-tip for PowerShell completion scripts ([ecda22ce](https://github.com/kbknapp/clap-rs/commit/ecda22ce7210ce56d7b2d1a5445dd1b8a2959656))
+
+
 <a name="v2.30.0"></a>
 ## v2.30.0 (2018-02-13)
 

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 
 name = "clap"
-version = "2.30.0"
+version = "2.31.0"
 authors = ["Kevin K. <kbknapp@gmail.com>"]
 exclude = ["examples/*", "clap-test/*", "tests/*", "benches/*", "*.png", "clap-perf/*", "*.dot"]
 repository = "https://github.com/kbknapp/clap-rs"

README.md

@@ -42,12 +42,26 @@ Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
 
 ## What's New
 
-Here's whats new in 2.30.0:
-
-* **Bash Completions:**  instead of completing a generic option name, all bash completions fall back to file completions UNLESS `Arg::possible_values` was used 
-* **YAML:** Adds a missing conversion from  `Arg::last` when instantiating from a YAML file 
-* **Deps:**  No longer needlessly compiles `ansi_term` on Windows since its not used 
-* **Help Message:** changes the `[values: foo bar baz]` array to `[possible values: foo bar baz]` for consistency with the API 
+Here's whats new in 2.31.0:
+
+* **Arg Indices:**  adds the ability to query argument value indices
+  * implements an `Indices<Item=usize>` iterator
+  * adds the documentation for the arg index querying methods
+* **Improves PowerShell completions** - Uses the short help tool-tip for PowerShell completion scripts
+* Adds WASM support (clap now compiles on WASM!)
+* **Raw Args** adds a convenience function to `Arg` that allows implying all of `Arg::last` `Arg::allow_hyphen_values` and `Arg::multiple(true)`
+* **CONTRIBUTING.md:**  fix url to clippy upstream repo
+* **Values Documentation:**  improves the docs example of the Values iterator
+* Updates README.md to hint that the `wrap_help` feature is a thing
+* Use `codegen-units = 1` in release and bench profiles to improve bench performance
+* Fix some typos and markdown issues in the docs
+
+Here's whats new in 2.30.x:
+
+* **Bash Completions:**  instead of completing a generic option name, all bash completions fall back to file completions UNLESS `Arg::possible_values` was used
+* **YAML:** Adds a missing conversion from  `Arg::last` when instantiating from a YAML file
+* **Deps:**  No longer needlessly compiles `ansi_term` on Windows since its not used
+* **Help Message:** changes the `[values: foo bar baz]` array to `[possible values: foo bar baz]` for consistency with the API
 
 Here's whats new in 2.29.x:
 
@@ -309,7 +323,7 @@ subcommands:
 
 Since this feature requires additional dependencies that not everyone may want, it is *not* compiled in by default and we need to enable a feature flag in Cargo.toml:
 
-Simply change your `clap = "2.30"` to `clap = {version = "2.30", features = ["yaml"]}`.
+Simply change your `clap = "2.31"` to `clap = {version = "2.31", features = ["yaml"]}`.
 
 Finally we create our `main.rs` file just like we would have with the previous two examples:
 
@@ -429,7 +443,7 @@ For full usage, add `clap` as a dependency in your `Cargo.toml` () to use from c
 
 ```toml
 [dependencies]
-clap = "~2.30"
+clap = "~2.31"
 ```
 
 (**note**: If you are concerned with supporting a minimum version of Rust that is *older* than the current stable Rust minus 2 stable releases, it's recommended to use the `~major.minor.patch` style versions in your `Cargo.toml` which will only update the patch version automatically. For more information see the [Compatibility Policy](#compatibility-policy))
@@ -452,15 +466,15 @@ To disable these, add this to your `Cargo.toml`:
 
 ```toml
 [dependencies.clap]
-version = "2.30"
+version = "2.31"
 default-features = false
 ```
 
 You can also selectively enable only the features you'd like to include, by adding:
 
 ```toml
 [dependencies.clap]
-version = "2.30"
+version = "2.31"
 default-features = false
 
 # Cherry-pick the features you'd like to use
@@ -509,7 +523,7 @@ In order to keep from being surprised of breaking changes, it is **highly** reco
 
 ```toml
 [dependencies]
-clap = "~2.30"
+clap = "~2.31"
 ```
 
 This will cause *only* the patch version to be updated upon a `cargo update` call, and therefore cannot break due to new features, or bumped minimum versions of Rust.
@@ -526,11 +540,11 @@ Right now Cargo's version resolution is pretty naive, it's just a brute-force se
 
 # In one Cargo.toml
 [dependencies]
-clap = "~2.30.0"
+clap = "~2.31.0"
 
 # In another Cargo.toml
 [dependencies]
-clap = "2.30"
+clap = "2.31"
 ```
 
 This is inherently an unresolvable crate graph in Cargo right now. Cargo requires there's only one major version of a crate, and being in the same workspace these two crates must share a version. This is impossible in this location, though, as these version constraints cannot be met.

src/app/parser.rs

@@ -8,6 +8,7 @@ use std::os::unix::ffi::OsStrExt;
 use std::path::PathBuf;
 use std::slice::Iter;
 use std::iter::Peekable;
+use std::cell::Cell;
 
 // Internal
 use INTERNAL_ERROR_MSG;
@@ -67,6 +68,7 @@ where
     cache: Option<&'a str>,
     pub help_message: Option<&'a str>,
     pub version_message: Option<&'a str>,
+    cur_idx: Cell<usize>,
 }
 
 impl<'a, 'b> Parser<'a, 'b>
@@ -77,6 +79,7 @@ where
         Parser {
             meta: AppMeta::with_name(n),
             g_settings: AppFlags::zeroed(),
+            cur_idx: Cell::new(0),
             ..Default::default()
         }
     }
@@ -1552,6 +1555,10 @@ where
     ) -> ClapResult<ParseResult<'a>> {
         // maybe here lifetime should be 'a
         debugln!("Parser::parse_long_arg;");
+
+        // Update the curent index
+        self.cur_idx.set(self.cur_idx.get() + 1);
+
         let mut val = None;
         debug!("Parser::parse_long_arg: Does it contain '='...");
         let arg = if full_arg.contains_byte(b'=') {
@@ -1635,6 +1642,10 @@ where
         let mut ret = ParseResult::NotFound;
         for c in arg.chars() {
             debugln!("Parser::parse_short_arg:iter:{}", c);
+
+            // update each index because `-abcd` is four indices to clap
+            self.cur_idx.set(self.cur_idx.get() + 1);
+
             // Check for matching short options, and return the name if there is no trailing
             // concatenated value: -oval
             // Option: -o
@@ -1810,12 +1821,20 @@ where
     {
         debugln!("Parser::add_single_val_to_arg;");
         debugln!("Parser::add_single_val_to_arg: adding val...{:?}", v);
+
+        // update the current index because each value is a distinct index to clap
+        self.cur_idx.set(self.cur_idx.get() + 1);
+
+        // @TODO @docs @p4: docs for indices should probably note that a terminator isn't a value
+        // and therefore not reported in indices
         if let Some(t) = arg.val_terminator() {
             if t == v {
                 return Ok(ParseResult::ValuesDone);
             }
         }
+
         matcher.add_val_to(arg.name(), v);
+        matcher.add_index_to(arg.name(), self.cur_idx.get());
 
         // Increment or create the group "args"
         if let Some(grps) = self.groups_for_arg(arg.name()) {
@@ -1838,6 +1857,8 @@ where
         debugln!("Parser::parse_flag;");
 
         matcher.inc_occurrence_of(flag.b.name);
+        matcher.add_index_to(flag.b.name, self.cur_idx.get());
+
         // Increment or create the group "args"
         self.groups_for_arg(flag.b.name)
             .and_then(|vec| Some(matcher.inc_occurrences_of(&*vec)));

src/args/arg_matcher.rs

@@ -59,7 +59,7 @@ impl<'a> ArgMatcher<'a> {
             if !aa.has_switch() || aa.is_set(ArgSettings::Multiple) {
                 // positional args can't override self or else we would never advance to the next
 
-                // Also flags with --multiple set are ignored otherwise we could never have more 
+                // Also flags with --multiple set are ignored otherwise we could never have more
                 // than one
                 return;
             }
@@ -172,11 +172,21 @@ impl<'a> ArgMatcher<'a> {
     pub fn add_val_to(&mut self, arg: &'a str, val: &OsStr) {
         let ma = self.entry(arg).or_insert(MatchedArg {
             occurs: 0,
+            indices: Vec::with_capacity(1),
             vals: Vec::with_capacity(1),
         });
         ma.vals.push(val.to_owned());
     }
 
+    pub fn add_index_to(&mut self, arg: &'a str, idx: usize) {
+        let ma = self.entry(arg).or_insert(MatchedArg {
+            occurs: 0,
+            indices: Vec::with_capacity(1),
+            vals: Vec::new(),
+        });
+        ma.indices.push(idx);
+    }
+
     pub fn needs_more_vals<'b, A>(&self, o: &A) -> bool
     where
         A: AnyArg<'a, 'b>,