From fb3ccd7aaf1c9b409946397fba6d7d618c480467 Mon Sep 17 00:00:00 2001 From: Kevin K Date: Sun, 29 Mar 2015 19:53:51 -0400 Subject: [PATCH] docs(clap): rebuild documentation --- docs/clap/index.html | 10 +- docs/clap/struct.Arg.html | 2 +- docs/clap/struct.ArgMatches.html | 16 ++- docs/clap/struct.SubCommand.html | 2 +- docs/search-index.js | 2 +- docs/src/clap/app.rs.html | 154 +++++++++++++++++++++++--- docs/src/clap/args/argmatches.rs.html | 40 ++++--- docs/src/clap/lib.rs.html | 10 +- 8 files changed, 186 insertions(+), 50 deletions(-) diff --git a/docs/clap/index.html b/docs/clap/index.html index 7f8457d4e73..a4e5633a746 100644 --- a/docs/clap/index.html +++ b/docs/clap/index.html @@ -51,15 +51,15 @@

Command Line Argument Parser written in Rust

-

A simply library for parsing command line arguments and subcommands when writing command line and console applications.

+

It is a simple to use and efficient library for parsing command line arguments and subcommands when writing command line, console, or terminal applications.

-

You can use clap to lay out a list of possible valid command line arguments and subcommands, then let clap parse the string given by the user at runtime.

+

You can use clap to lay out a list of possible valid command line arguments and subcommands, then let clap parse and validate the string given by the user at runtime. This means you focus on your applications functionality, not parsing and validating arguments.

-

When using clap you define a set of parameters and rules for your arguments and subcommands, then at runtime clap will determine their validity.

+

What seperates clap from other options available is the very simple almost 'Pythonic' style in which you define the valid available arguments for your program. This means you don't have to spend tons time learning an entirely new library's structures and use.

-

clap also provides the traditional version and help switches 'for free' by parsing the list of possible valid arguments lazily at runtime, and if not already defined by the developer clap will autogenerate all applicable "help" and "version" switches (as well as a "help" subcommand if other subcommands are defined as well).

+

clap also provides all the traditional version and help switches (or flags) 'for free' by parsing the list of developer supplied arguments. If the developer hasn't defined them already, clap will auto-generate only the applicable "help" and "version" switches (as well as a "help" subcommand so long as other subcommands have been manually defined as well).

-

After defining a list of possible valid arguments and subcommands, clap gives you a list of valid matches that the user supplied at runtime, or informs the user of their error and exits gracefully. You can use this list to determine the functioning of your program.

+

After defining a list of possible valid arguments and subcommands, clap parses the string given by the end-user at runtime then gives you a list of the valid matches and their values. If the user made an error or typo, clap informs them and exits gracefully. This means that you can simply use these matches and values to determine the functioning of your program.

Quick Example

diff --git a/docs/clap/struct.Arg.html b/docs/clap/struct.Arg.html
index 43ac00d1c87..040d34b50d0 100644
--- a/docs/clap/struct.Arg.html
+++ b/docs/clap/struct.Arg.html
@@ -43,7 +43,7 @@
     

 
Struct clap::Arg
             [-] [+]
-        [src]

+        [src]

pub struct Arg<'n, 'l, 'h, 'b, 'p, 'r> {
     pub name: &'n str,
     pub short: Option<char>,
diff --git a/docs/clap/struct.ArgMatches.html b/docs/clap/struct.ArgMatches.html
index e83ad64847b..e9e829ed553 100644
--- a/docs/clap/struct.ArgMatches.html
+++ b/docs/clap/struct.ArgMatches.html
@@ -43,7 +43,7 @@
     

 
Struct clap::ArgMatches
             [-] [+]
-        [src]

+        [src]
 
pub struct ArgMatches<'a> {
     pub flags: HashMap<&'a str, FlagArg>,
     pub opts: HashMap<&'a str, OptArg>,
@@ -108,8 +108,8 @@ 
None. 

 
-
NOTE: If getting a value for an option argument that allows multiples, prefer values_of()
-as value_of() will only return the first value.

+
NOTE: If getting a value for an option or positional argument that allows multiples,
+prefer values_of() as value_of() will only return the first value.

 
 
Example
@@ -118,9 +118,9 @@ 

 
fn values_of<'n>(&self, name: &'n str) -> Option<Vec<&str>>

-
Gets the values of a specific option in a vector (i.e. an argument that takes
-an additional value at runtime). If the option wasn't present at runtime
-it returns None

+
Gets the values of a specific option or positional argument in a vector (i.e. an argument
+that takes an additional value at runtime). If the option wasn't present at runtime it
+returns None

 
 
Example
@@ -144,13 +144,11 @@ 

 
fn occurrences_of<'n>(&self, name: &'n str) -> u8

-
Checks the number of occurrences of an option or flag at runtime.
+
Checks the number of occurrences of an option, flag, or positional argument at runtime.
 If an option or flag isn't present it will return 0, if the option or flag doesn't 
 allow multiple occurrences, it will return 1 no matter how many times it occurred 
 (unless it wasn't prsent) at all.

 
-
NOTE: This DOES NOT work for positional arguments (use .value_of() instead). 

-
 
Example
 if matches.occurrences_of("debug") > 1 {
diff --git a/docs/clap/struct.SubCommand.html b/docs/clap/struct.SubCommand.html
index 7c134155def..e2f44b22991 100644
--- a/docs/clap/struct.SubCommand.html
+++ b/docs/clap/struct.SubCommand.html
@@ -43,7 +43,7 @@
     

 
Struct clap::SubCommand
             [-] [+]
-        [src]

+        [src]

 
pub struct SubCommand<'a> {
     pub name: String,
     pub matches: ArgMatches<'a>,
diff --git a/docs/search-index.js b/docs/search-index.js
index ed50c346040..e7dfef45af7 100644
--- a/docs/search-index.js
+++ b/docs/search-index.js
@@ -1,3 +1,3 @@
 var searchIndex = {};
-searchIndex['clap'] = {"items":[[0,"","clap","# clap",null,null],[3,"Arg","","The abstract representation of a command line argument used by the consumer of the library.",null,null],[12,"name","","The unique name of the argument, required",0,null],[12,"short","","The short version (i.e. single character) of the argument, no preceding `-`\n**NOTE:** `short` is mutually exclusive with `index`",0,null],[12,"long","","The long version of the flag (i.e. word) without the preceding `--`\n**NOTE:** `long` is mutually exclusive with `index`",0,null],[12,"help","","The string of text that will displayed to the user when the application's\n`help` text is displayed",0,null],[12,"required","","If this is a required by default when using the command line program\ni.e. a configuration file that's required for the program to function\n**NOTE:** required by default means, it is required *until* mutually\nexclusive arguments are evaluated.",0,null],[12,"takes_value","","Determines if this argument is an option, vice a flag or positional and\nis mutually exclusive with `index` and `multiple`",0,null],[12,"index","","The index of the argument. `index` is mutually exclusive with `takes_value`\nand `multiple`",0,null],[12,"multiple","","Determines if multiple instances of the same flag are allowed. `multiple`\nis mutually exclusive with `index` and `takes_value`.\nI.e. `-v -v -v` or `-vvv`",0,null],[12,"blacklist","","A list of names for other arguments that *may not* be used with this flag",0,null],[12,"possible_vals","","A list of possible values for an option or positional argument",0,null],[12,"requires","","A list of names of other arguments that are *required* to be used when\nthis flag is used",0,null],[3,"SubCommand","","The abstract representation of a command line subcommand used by the consumer of the library.",null,null],[12,"name","","",1,null],[12,"matches","","",1,null],[3,"ArgMatches","","Used to get information about the arguments that\nwhere supplied to the program at runtime.",null,null],[12,"flags","","",2,null],[12,"opts","","",2,null],[12,"positionals","","",2,null],[12,"subcommand","","",2,null],[3,"App","","Used to create a representation of the program and all possible command line arguments\nfor parsing at runtime.",null,null],[11,"new","","Creates a new instance of an application requiring a name (such as the binary). Will be displayed\nto the user when they print version or help and usage information.",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"author","","Sets a string of author(s)",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"about","","Sets a string briefly describing what the program does",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"version","","Sets a string of the version number",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"usage","","Sets a custom usage string to over-ride the one auto-generated by `clap`",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"arg","","Adds an argument to the list of valid possibilties",3,{"inputs":[{"name":"app"},{"name":"arg"}],"output":{"name":"app"}}],[11,"args","","Adds multiple arguments to the list of valid possibilties",3,{"inputs":[{"name":"app"},{"name":"vec"}],"output":{"name":"app"}}],[11,"subcommand","","Adds a subcommand to the list of valid possibilties. Subcommands\nare effectively sub apps, because they can contain their own arguments\nand subcommands. They also function just like apps, in that they get their\nown auto generated help and version switches.",3,{"inputs":[{"name":"app"},{"name":"app"}],"output":{"name":"app"}}],[11,"subcommands","","Adds multiple subcommands to the list of valid possibilties",3,{"inputs":[{"name":"app"},{"name":"vec"}],"output":{"name":"app"}}],[11,"get_matches","","",3,{"inputs":[{"name":"app"}],"output":{"name":"argmatches"}}],[11,"new","","Creates a new instace of `Arg` using a unique string name.\nThe name will be used by the library consumer to get information about\nwhether or not the argument was used at runtime. ",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"short","","Sets the short version of the argument without the preceding `-`.",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"long","","Sets the long version of the argument without the preceding `--`.",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"help","","Sets the help text of the argument that will be displayed to the user\nwhen they print the usage/help information. ",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"required","","Sets whether or not the argument is required by default. Required by\ndefault means it is required, when no other mutually exlusive rules have\nbeen evaluated. Mutually exclusive rules take precedence over being required\nby default.",0,{"inputs":[{"name":"arg"},{"name":"bool"}],"output":{"name":"arg"}}],[11,"mutually_excludes","","Sets a mutually exclusive argument by name. I.e. when using this argument,\nthe following argument can't be present.",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"mutually_excludes_all","","Sets a mutually exclusive arguments by names. I.e. when using this argument,\nthe following argument can't be present.",0,{"inputs":[{"name":"arg"},{"name":"vec"}],"output":{"name":"arg"}}],[11,"requires","","Sets an argument by name that is required when this one is presnet I.e. when\nusing this argument, the following argument *must* be present.",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"requires_all","","Sets arguments by names that are required when this one is presnet I.e. when\nusing this argument, the following arguments *must* be present.",0,{"inputs":[{"name":"arg"},{"name":"vec"}],"output":{"name":"arg"}}],[11,"takes_value","","Specifies that the argument takes an additional value at run time.",0,{"inputs":[{"name":"arg"},{"name":"bool"}],"output":{"name":"arg"}}],[11,"index","","Specifies the index of a positional argument starting at 1.",0,{"inputs":[{"name":"arg"},{"name":"u8"}],"output":{"name":"arg"}}],[11,"multiple","","Specifies if the flag may appear more than once such as for multiple debugging\nlevels (as an example). `-ddd` for three levels of debugging, or `-d -d -d`. \nWhen this is set to `true` you recieve the number of occurances the user supplied\nof a particular flag at runtime.",0,{"inputs":[{"name":"arg"},{"name":"bool"}],"output":{"name":"arg"}}],[11,"possible_values","","Specifies a list of possible values for this argument. At runtime, clap verifies that only\none of the specified values was used, or fails with a usage string.",0,{"inputs":[{"name":"arg"},{"name":"vec"}],"output":{"name":"arg"}}],[11,"new","","Creates a new instance of `ArgMatches`. This ins't called directly, but\nthrough the `.get_matches()` method of `App`",2,{"inputs":[{"name":"argmatches"}],"output":{"name":"argmatches"}}],[11,"value_of","","Gets the value of a specific option or positional argument (i.e. an argument that takes\nan additional value at runtime). If the option wasn't present at runtime\nit returns `None`. ",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"option"}}],[11,"values_of","","Gets the values of a specific option in a vector (i.e. an argument that takes\nan additional value at runtime). If the option wasn't present at runtime\nit returns `None`",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"option"}}],[11,"is_present","","Checks if a flag was argument was supplied at runtime. **DOES NOT** work for\noption or positional arguments (use `.value_of()` instead)",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"bool"}}],[11,"occurrences_of","","Checks the number of occurrences of an option or flag at runtime.\nIf an option or flag isn't present it will return `0`, if the option or flag doesn't \nallow multiple occurrences, it will return `1` no matter how many times it occurred \n(unless it wasn't prsent) at all.",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"u8"}}],[11,"subcommand_matches","","If a subcommand was found, returns the ArgMatches struct associated with it's matches",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"option"}}],[11,"subcommand_name","","If a subcommand was found, returns the name associated with it",2,{"inputs":[{"name":"argmatches"}],"output":{"name":"option"}}],[11,"new","","Creates a new instance of a subcommand requiring a name. Will be displayed\nto the user when they print version or help and usage information.",1,{"inputs":[{"name":"subcommand"},{"name":"str"}],"output":{"name":"app"}}]],"paths":[[3,"Arg"],[3,"SubCommand"],[3,"ArgMatches"],[3,"App"]]};
+searchIndex['clap'] = {"items":[[0,"","clap","# clap",null,null],[3,"Arg","","The abstract representation of a command line argument used by the consumer of the library.",null,null],[12,"name","","The unique name of the argument, required",0,null],[12,"short","","The short version (i.e. single character) of the argument, no preceding `-`\n**NOTE:** `short` is mutually exclusive with `index`",0,null],[12,"long","","The long version of the flag (i.e. word) without the preceding `--`\n**NOTE:** `long` is mutually exclusive with `index`",0,null],[12,"help","","The string of text that will displayed to the user when the application's\n`help` text is displayed",0,null],[12,"required","","If this is a required by default when using the command line program\ni.e. a configuration file that's required for the program to function\n**NOTE:** required by default means, it is required *until* mutually\nexclusive arguments are evaluated.",0,null],[12,"takes_value","","Determines if this argument is an option, vice a flag or positional and\nis mutually exclusive with `index` and `multiple`",0,null],[12,"index","","The index of the argument. `index` is mutually exclusive with `takes_value`\nand `multiple`",0,null],[12,"multiple","","Determines if multiple instances of the same flag are allowed. `multiple`\nis mutually exclusive with `index` and `takes_value`.\nI.e. `-v -v -v` or `-vvv`",0,null],[12,"blacklist","","A list of names for other arguments that *may not* be used with this flag",0,null],[12,"possible_vals","","A list of possible values for an option or positional argument",0,null],[12,"requires","","A list of names of other arguments that are *required* to be used when\nthis flag is used",0,null],[3,"SubCommand","","The abstract representation of a command line subcommand used by the consumer of the library.",null,null],[12,"name","","",1,null],[12,"matches","","",1,null],[3,"ArgMatches","","Used to get information about the arguments that\nwhere supplied to the program at runtime.",null,null],[12,"flags","","",2,null],[12,"opts","","",2,null],[12,"positionals","","",2,null],[12,"subcommand","","",2,null],[3,"App","","Used to create a representation of the program and all possible command line arguments\nfor parsing at runtime.",null,null],[11,"new","","Creates a new instance of an application requiring a name (such as the binary). Will be displayed\nto the user when they print version or help and usage information.",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"author","","Sets a string of author(s)",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"about","","Sets a string briefly describing what the program does",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"version","","Sets a string of the version number",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"usage","","Sets a custom usage string to over-ride the one auto-generated by `clap`",3,{"inputs":[{"name":"app"},{"name":"str"}],"output":{"name":"app"}}],[11,"arg","","Adds an argument to the list of valid possibilties",3,{"inputs":[{"name":"app"},{"name":"arg"}],"output":{"name":"app"}}],[11,"args","","Adds multiple arguments to the list of valid possibilties",3,{"inputs":[{"name":"app"},{"name":"vec"}],"output":{"name":"app"}}],[11,"subcommand","","Adds a subcommand to the list of valid possibilties. Subcommands\nare effectively sub apps, because they can contain their own arguments\nand subcommands. They also function just like apps, in that they get their\nown auto generated help and version switches.",3,{"inputs":[{"name":"app"},{"name":"app"}],"output":{"name":"app"}}],[11,"subcommands","","Adds multiple subcommands to the list of valid possibilties",3,{"inputs":[{"name":"app"},{"name":"vec"}],"output":{"name":"app"}}],[11,"get_matches","","",3,{"inputs":[{"name":"app"}],"output":{"name":"argmatches"}}],[11,"new","","Creates a new instace of `Arg` using a unique string name.\nThe name will be used by the library consumer to get information about\nwhether or not the argument was used at runtime. ",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"short","","Sets the short version of the argument without the preceding `-`.",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"long","","Sets the long version of the argument without the preceding `--`.",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"help","","Sets the help text of the argument that will be displayed to the user\nwhen they print the usage/help information. ",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"required","","Sets whether or not the argument is required by default. Required by\ndefault means it is required, when no other mutually exlusive rules have\nbeen evaluated. Mutually exclusive rules take precedence over being required\nby default.",0,{"inputs":[{"name":"arg"},{"name":"bool"}],"output":{"name":"arg"}}],[11,"mutually_excludes","","Sets a mutually exclusive argument by name. I.e. when using this argument,\nthe following argument can't be present.",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"mutually_excludes_all","","Sets a mutually exclusive arguments by names. I.e. when using this argument,\nthe following argument can't be present.",0,{"inputs":[{"name":"arg"},{"name":"vec"}],"output":{"name":"arg"}}],[11,"requires","","Sets an argument by name that is required when this one is presnet I.e. when\nusing this argument, the following argument *must* be present.",0,{"inputs":[{"name":"arg"},{"name":"str"}],"output":{"name":"arg"}}],[11,"requires_all","","Sets arguments by names that are required when this one is presnet I.e. when\nusing this argument, the following arguments *must* be present.",0,{"inputs":[{"name":"arg"},{"name":"vec"}],"output":{"name":"arg"}}],[11,"takes_value","","Specifies that the argument takes an additional value at run time.",0,{"inputs":[{"name":"arg"},{"name":"bool"}],"output":{"name":"arg"}}],[11,"index","","Specifies the index of a positional argument starting at 1.",0,{"inputs":[{"name":"arg"},{"name":"u8"}],"output":{"name":"arg"}}],[11,"multiple","","Specifies if the flag may appear more than once such as for multiple debugging\nlevels (as an example). `-ddd` for three levels of debugging, or `-d -d -d`. \nWhen this is set to `true` you recieve the number of occurances the user supplied\nof a particular flag at runtime.",0,{"inputs":[{"name":"arg"},{"name":"bool"}],"output":{"name":"arg"}}],[11,"possible_values","","Specifies a list of possible values for this argument. At runtime, clap verifies that only\none of the specified values was used, or fails with a usage string.",0,{"inputs":[{"name":"arg"},{"name":"vec"}],"output":{"name":"arg"}}],[11,"new","","Creates a new instance of `ArgMatches`. This ins't called directly, but\nthrough the `.get_matches()` method of `App`",2,{"inputs":[{"name":"argmatches"}],"output":{"name":"argmatches"}}],[11,"value_of","","Gets the value of a specific option or positional argument (i.e. an argument that takes\nan additional value at runtime). If the option wasn't present at runtime\nit returns `None`. ",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"option"}}],[11,"values_of","","Gets the values of a specific option or positional argument in a vector (i.e. an argument\nthat takes an additional value at runtime). If the option wasn't present at runtime it\nreturns `None`",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"option"}}],[11,"is_present","","Checks if a flag was argument was supplied at runtime. **DOES NOT** work for\noption or positional arguments (use `.value_of()` instead)",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"bool"}}],[11,"occurrences_of","","Checks the number of occurrences of an option, flag, or positional argument at runtime.\nIf an option or flag isn't present it will return `0`, if the option or flag doesn't \nallow multiple occurrences, it will return `1` no matter how many times it occurred \n(unless it wasn't prsent) at all.",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"u8"}}],[11,"subcommand_matches","","If a subcommand was found, returns the ArgMatches struct associated with it's matches",2,{"inputs":[{"name":"argmatches"},{"name":"str"}],"output":{"name":"option"}}],[11,"subcommand_name","","If a subcommand was found, returns the name associated with it",2,{"inputs":[{"name":"argmatches"}],"output":{"name":"option"}}],[11,"new","","Creates a new instance of a subcommand requiring a name. Will be displayed\nto the user when they print version or help and usage information.",1,{"inputs":[{"name":"subcommand"},{"name":"str"}],"output":{"name":"app"}}]],"paths":[[3,"Arg"],[3,"SubCommand"],[3,"ArgMatches"],[3,"App"]]};
 initSearch(searchIndex);
diff --git a/docs/src/clap/app.rs.html b/docs/src/clap/app.rs.html
index 1499dac92ab..8bbe8c7093b 100644
--- a/docs/src/clap/app.rs.html
+++ b/docs/src/clap/app.rs.html
@@ -1067,6 +1067,69 @@
 1025
 1026
 1027
+1028
+1029
+1030
+1031
+1032
+1033
+1034
+1035
+1036
+1037
+1038
+1039
+1040
+1041
+1042
+1043
+1044
+1045
+1046
+1047
+1048
+1049
+1050
+1051
+1052
+1053
+1054
+1055
+1056
+1057
+1058
+1059
+1060
+1061
+1062
+1063
+1064
+1065
+1066
+1067
+1068
+1069
+1070
+1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
+1083
+1084
+1085
+1086
+1087
+1088
+1089
+1090
 
 extern crate libc;
 
@@ -1277,9 +1340,12 @@
             if a.short.is_some() || a.long.is_some() {
                 panic!("Argument \"{}\" has conflicting requirements, both index() and short(), or long(), were supplied", a.name);
             }
-            if a.multiple {
-                panic!("Argument \"{}\" has conflicting requirements, both index() and multiple(true) were supplied",a.name);
+            if self.positionals_idx.contains_key(&i) {
+                panic!("Argument \"{}\" has the same index as another positional argument", a.name);
             }
+            // if a.multiple {
+            //     panic!("Argument \"{}\" has conflicting requirements, both index() and multiple(true) were supplied",a.name);
+            // }
             if a.takes_value {
                 panic!("Argument \"{}\" has conflicting requirements, both index() and takes_value(true) were supplied", a.name);
             }
@@ -1288,6 +1354,7 @@
                 name: a.name,
                 index: i,
                 required: a.required,
+                multiple: a.multiple,
                 blacklist: None,
                 requires: None,
                 possible_vals: None,
@@ -1480,19 +1547,31 @@
             let pos = !self.positionals_idx.is_empty();
             let opts = !self.opts.is_empty();
             let subcmds = !self.subcommands.is_empty();
-            let req_pos = self.positionals_idx.values().filter_map(|ref x| if x.required || self.required.contains(x.name) { Some(x.name) } else {None})
+            let mut num_req_pos = 0;
+            let req_pos = self.positionals_idx.values().filter_map(|ref x| if x.required || self.required.contains(x.name) { 
+                num_req_pos += 1;
+                Some(x.name) 
+            } else {
+                None
+            })
                                                        .fold(String::new(), |acc, ref name| acc + &format!("<{}> ", name)[..]);
-            let req_opts = self.opts.values().filter(|ref x| x.required || self.required.contains(x.name))
+            let mut num_req_opts = 0;
+            let req_opts = self.opts.values().filter_map(|x| if x.required || self.required.contains(x.name) {
+                num_req_opts += 1;
+                Some(x)
+            }else {
+                None
+            })
                                              .fold(String::new(), |acc, ref o| acc + &format!("-{}{} ",if let Some(s) = o.short {
                                                                                                      format!("{} ", s)
                                                                                                    } else {
                                                                                                        format!("-{}=",o.long.unwrap())
                                                                                                    },o.name));
 
-            print!("\t{} {} {} {} {}", if let Some(ref name) = self.bin_name { name.replace("-", " ") } else { self.name.clone() },
+            print!("\t{} {} {} {} {}", self.bin_name.clone().unwrap_or(self.name.clone()),
                 if flags {"[FLAGS]"} else {""},
                 if opts {
-                    if req_opts.len() != self.opts.len() && !req_opts.is_empty() { 
+                    if num_req_opts != self.opts.len() && !req_opts.is_empty() { 
                         format!("[OPTIONS] {}", &req_opts[..])
                     } else if req_opts.is_empty() { 
                         "[OPTIONS]".to_owned()
@@ -1501,7 +1580,7 @@
                     } 
                 } else { "".to_owned() },
                 if pos {
-                    if req_pos.len() != self.positionals_idx.len() && !req_pos.is_empty() { 
+                    if num_req_pos != self.positionals_idx.len() && !req_pos.is_empty() { 
                         format!("[POSITIONAL] {}", &req_pos[..])
                     } else if req_pos.is_empty() { 
                         "[POSITIONAL]".to_owned() 
@@ -1595,7 +1674,9 @@
     }
 
     fn print_version(&self, quit: bool) {
-        println!("{} {}", self.bin_name.clone().unwrap_or(self.name.clone()), self.version.unwrap_or("") );
+        // Print the binary name if existing, but replace all spaces with hyphens in case we're
+        // dealing with subcommands i.e. git mv is translated to git-mv
+        println!("{} {}", &self.bin_name.clone().unwrap_or(self.name.clone())[..].replace(" ", "-"), self.version.unwrap_or("") );
         if quit { self.exit(); }
     }
 
@@ -1610,6 +1691,11 @@
     }
 
     pub fn get_matches(mut self) -> ArgMatches<'ar> {
+        self.verify_positionals();
+        for sc in self.subcommands.values() {
+            sc.verify_positionals();
+        }
+
         let mut matches = ArgMatches::new();
 
         let args = env::args().collect::<Vec<_>>();    
@@ -1627,6 +1713,29 @@
         matches
     }
 
+    fn verify_positionals(&self) {
+        // Because you must wait until all arguments have been supplied, this is the first chance
+        // to make assertions on positional argument indexes
+        // 
+        // Firt we verify that the index highest supplied index, is equal to the number of
+        // positional arguments to verify there are no gaps (i.e. supplying an index of 1 and 3
+        // but no 2)
+        //
+        // Next we verify that only the highest index has a .multiple(true) (if any)
+        if let Some((idx, ref p)) = self.positionals_idx.iter().rev().next() {
+            if *idx as usize != self.positionals_idx.len() {
+                panic!("Found positional argument \"{}\" who's index is {} but there are only {} positional arguments defined", p.name, idx, self.positionals_idx.len());
+            }
+        }
+        if let Some(ref p) = self.positionals_idx.values()
+                                                 .filter(|ref a| a.multiple)
+                                                 .filter(|ref a| a.index as usize != self.positionals_idx.len())
+                                                 .next() {
+            panic!("Found positional argument \"{}\" which accepts multiple values but it's not the last positional argument (i.e. others have a higher index)", 
+                    p.name);
+        }
+    }
+
     fn get_matches_from(&mut self, matches: &mut ArgMatches<'ar>, it: &mut IntoIter<String>) {
         self.create_help_and_version();
 
@@ -1707,10 +1816,27 @@
                             }
                         }
                     }
-                    matches.positionals.insert(p.name, PosArg{
-                        name: p.name.to_owned(),
-                        value: arg.clone(),
-                    });
+                    // Have we made the update yet?
+                    let mut done = false;
+                    if p.multiple {
+                        // Check if it's already existing and update if so...
+                        if let Some(ref mut pa) = matches.positionals.get_mut(p.name) {
+                            done = true;
+                            pa.occurrences += 1;
+                            pa.values.push(arg.clone());
+                        }
+                    } else {
+                        // Only increment the positional counter if it doesn't allow multiples
+                        pos_counter += 1;
+                    }
+                    // Was an update made, or is this the first occurrence?
+                    if !done {
+                        matches.positionals.insert(p.name, PosArg{
+                            name: p.name.to_owned(),
+                            occurrences: 1,
+                            values: vec![arg.clone()],
+                        });
+                    }
 
                     if let Some(ref bl) = p.blacklist {
                         for name in bl {
@@ -1731,7 +1857,6 @@
                             self.required.insert(n);
                         }
                     }
-                    pos_counter += 1;
                 } else {
                     self.report_error(format!("Positional argument \"{}\" was found, but {} wasn't expecting any", arg, self.name), true, true);
                 }
@@ -1755,7 +1880,8 @@
         if let Some(sc_name) = subcmd_name {
             if let Some(ref mut sc) = self.subcommands.get_mut(&sc_name) {
                 let mut new_matches = ArgMatches::new();
-                sc.bin_name = Some(format!("{}{}{}", self.bin_name.clone().unwrap_or("".to_owned()),if self.bin_name.is_some() {"-"} else {""}, sc.name.clone()));
+                // bin_name should be parent's bin_name + the sc's name seperated by a space
+                sc.bin_name = Some(format!("{}{}{}", self.bin_name.clone().unwrap_or("".to_owned()),if self.bin_name.is_some() {" "} else {""}, sc.name.clone()));
                 sc.get_matches_from(&mut new_matches, it);
                 matches.subcommand = Some(Box::new(SubCommand{
                     name: sc.name.clone(),
diff --git a/docs/src/clap/args/argmatches.rs.html b/docs/src/clap/args/argmatches.rs.html
index 620f999286f..c8b66849950 100644
--- a/docs/src/clap/args/argmatches.rs.html
+++ b/docs/src/clap/args/argmatches.rs.html
@@ -279,6 +279,12 @@
 237
 238
 239
+240
+241
+242
+243
+244
+245
 
 use std::collections::HashMap;
 
@@ -373,8 +379,8 @@
     /// an additional value at runtime). If the option wasn't present at runtime
     /// it returns `None`. 
     ///
-    /// *NOTE:* If getting a value for an option argument that allows multiples, prefer `values_of()`
-    /// as `value_of()` will only return the _*first*_ value.
+    /// *NOTE:* If getting a value for an option or positional argument that allows multiples,
+    /// prefer `values_of()` as `value_of()` will only return the _*first*_ value.
     ///
     /// # Example
     ///
@@ -387,21 +393,21 @@
     /// ```
     pub fn value_of<'n>(&self, name: &'n str) -> Option<&str> {
         if let Some(ref opt) = self.opts.get(name) {
-            if !opt.values.is_empty() {
-                if let Some(ref s) = opt.values.iter().nth(0) {
-                    return Some(&s[..]);
-                }
-            } 
+            if let Some(ref s) = opt.values.iter().nth(0) {
+                return Some(&s[..]);
+            }
         }
         if let Some(ref pos) = self.positionals.get(name) {
-            return Some(&pos.value[..]);
+            if let Some(ref s) = pos.values.iter().nth(0) {
+                return Some(&s[..]);
+            }
         }
         None
     }
 
-    /// Gets the values of a specific option in a vector (i.e. an argument that takes
-    /// an additional value at runtime). If the option wasn't present at runtime
-    /// it returns `None`
+    /// Gets the values of a specific option or positional argument in a vector (i.e. an argument
+    /// that takes an additional value at runtime). If the option wasn't present at runtime it
+    /// returns `None`
     ///
     /// # Example
     ///
@@ -423,6 +429,11 @@
 
             return Some(opt.values.iter().map(|s| &s[..]).collect::<Vec<_>>());
         }
+        if let Some(ref pos) = self.positionals.get(name) {
+            if pos.values.is_empty() { return None; } 
+
+            return Some(pos.values.iter().map(|s| &s[..]).collect::<Vec<_>>());
+        }
         None
     }
 
@@ -449,13 +460,11 @@
         false
     }
 
-    /// Checks the number of occurrences of an option or flag at runtime. 
+    /// Checks the number of occurrences of an option, flag, or positional argument at runtime. 
     /// If an option or flag isn't present it will return `0`, if the option or flag doesn't 
     /// allow multiple occurrences, it will return `1` no matter how many times it occurred 
     /// (unless it wasn't prsent) at all.
     ///
-    /// *NOTE:* This _*DOES NOT*_ work for positional arguments (use `.value_of()` instead). 
-    ///
     ///
     /// # Example
     ///
@@ -475,6 +484,9 @@
         if let Some(ref o) = self.opts.get(name) {
             return o.occurrences;
         }
+        if let Some(ref p) = self.positionals.get(name) {
+            return p.occurrences;
+        }
         0
     }
 
diff --git a/docs/src/clap/lib.rs.html b/docs/src/clap/lib.rs.html
index 8eb46b67f35..01e8269af4b 100644
--- a/docs/src/clap/lib.rs.html
+++ b/docs/src/clap/lib.rs.html
@@ -324,15 +324,15 @@
 //! 
 //! Command Line Argument Parser written in Rust
 //! 
-//! A simply library for parsing command line arguments and subcommands when writing command line and console applications.
+//! It is a simple to use and efficient library for parsing command line arguments and subcommands when writing command line, console, or terminal applications.
 //! 
-//! You can use `clap` to lay out a list of possible valid command line arguments and subcommands, then let `clap` parse the string given by the user at runtime.
+//! You can use clap to lay out a list of possible valid command line arguments and subcommands, then let `clap` parse *and validate* the string given by the user at runtime. This means you focus on your applications functionality, not parsing and validating arguments.
 //! 
-//! When using `clap` you define a set of parameters and rules for your arguments and subcommands, then at runtime `clap` will determine their validity.
+//! What seperates `clap` from other options available is the very simple almost 'Pythonic' style in which you define the valid available arguments for your program. This means you don't have to spend tons time learning an entirely new library's structures and use.
 //! 
-//! `clap` also provides the traditional version and help switches 'for free' by parsing the list of possible valid arguments lazily at runtime, and if not already defined by the developer `clap` will autogenerate all applicable "help" and "version" switches (as well as a "help" subcommand if other subcommands are defined as well).
+//! `clap` also provides all the traditional version and help switches (or flags) 'for free' by parsing the list of developer supplied arguments. If the developer hasn't defined them already, `clap` will auto-generate only the applicable "help" and "version" switches (as well as a "help" subcommand so long as other subcommands have been manually defined as well).
 //! 
-//!  After defining a list of possible valid arguments and subcommands, `clap` gives you a list of valid matches that the user supplied at runtime, or informs the user of their error and exits gracefully. You can use this list to determine the functioning of your program.
+//! After defining a list of possible valid arguments and subcommands, `clap` parses the string given by the end-user at runtime then gives you a list of the valid matches and their values. If the user made an error or typo, `clap` informs them and exits gracefully. This means that you can simply use these matches and values to determine the functioning of your program.
 //! 
 //! ## Quick Example
 //!