Auto merge of #921 - kbknapp:template-fix, r=kbknapp

Template fix

Fixes BurntSushi/ripgrep#426 and BurntSushi/ripgrep#418

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/kbknapp/clap-rs/921)
<!-- Reviewable:end -->

CHANGELOG.md

@@ -1,3 +1,13 @@
+<a name="v2.22.2"></a>
+### v2.22.2 (2017-03-30)
+
+
+#### Bug Fixes
+
+* **Custom Usage Strings:**  fixes the usage string regression when using help templates ([0e4fd96d](https://github.com/kbknapp/clap-rs/commit/0e4fd96d74280d306d09e60ac44f938a82321769))
+
+
+
 <a name="v2.22.1"></a>
 ### v2.22.1 (2017-03-24)
 

Cargo.toml

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

README.md

@@ -45,15 +45,16 @@ Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
 
 ## What's New
 
-Here's the highlights for v2.22.1
+Here's the highlights for v2.22.2
 
-* **usage:**  fixes a big regression with custom usage strings 
+* fixes the usage string regression when using help templates 
 
-Here's the highlights for v2.21.0 to v2.22.0
+Here's the highlights for v2.21.0 to v2.22.1
 
-* **App::name:**  adds the ability to change the name of the App instance after creation
-* **Arg::hide_default_value:**  adds ability to hide the default value of an argument from the help string
-* **yaml:**  fixes support for loading author info from yaml
+* fixes a big regression with custom usage strings 
+* adds the ability to change the name of the App instance after creation
+* adds ability to hide the default value of an argument from the help string
+* fixes support for loading author info from yaml
 * adds fish subcommand help support
 * options that use `require_equals(true)` now display the equals sign in help messages, usage strings, and errors
 * setting the max term width now correctly propagates down through child subcommands

src/app/help.rs

@@ -888,7 +888,7 @@ impl<'a> Help<'a> {
                                 parser.meta.about.unwrap_or("unknown about")));
                 }
                 b"usage" => {
-                    try!(write!(self.writer, "{}", usage::create_help_usage(parser, true)));
+                    try!(write!(self.writer, "{}", usage::create_usage_no_title(parser, &[])));
                 }
                 b"all-args" => {
                     try!(self.write_all_args(&parser));

src/args/arg.rs

@@ -2440,18 +2440,24 @@ impl<'a, 'b> Arg<'a, 'b> {
         self
     }
 
-    ///Works identically to Validator but is intended to be used with non UTF-8 formatted strings.
+    /// Works identically to Validator but is intended to be used with values that could 
+    /// contain non UTF-8 formatted strings.
+    ///
     /// # Examples
-    /// ```rust
+    ///
+    #[cfg_attr(not(unix), doc=" ```ignore")]
+    #[cfg_attr(    unix , doc=" ```rust")]
     /// # use clap::{App, Arg};
-    ///fn has_ampersand(v: &OsStr) -> Result<(), String> {
-    ///     if v.contains("&") { return Ok(()); }
-    ///     Err(String::from("The value did not contain the required & sigil"))
+    /// # use std::ffi::{OsStr, OsString};
+    /// # use std::os::unix::ffi::OsStrExt;
+    /// fn has_ampersand(v: &OsStr) -> Result<(), OsString> {
+    ///     if v.as_bytes().iter().any(|b| *b == b'&') { return Ok(()); }
+    ///     Err(OsString::from("The value did not contain the required & sigil"))
     /// }
     /// let res = App::new("prog")
     ///     .arg(Arg::with_name("file")
     ///         .index(1)
-    ///         .validator(has_ampersand))
+    ///         .validator_os(has_ampersand))
     ///     .get_matches_from_safe(vec![
     ///         "prog", "Fish & chips"
     ///     ]);

tests/help.rs

@@ -686,7 +686,27 @@ fn ripgrep_usage() {
     rg [OPTIONS] --files [<path> ...]
     rg [OPTIONS] --type-list");
 
-    assert!(test::compare_output(app, "ripgrep --help", RIPGREP_USAGE, false));
+    assert!(test::compare_output(app, "rg --help", RIPGREP_USAGE, false));
+}
+
+#[test]
+fn ripgrep_usage_using_templates() {
+    let app = App::new("ripgrep")
+        .version("0.5")
+        .usage("
+    rg [OPTIONS] <pattern> [<path> ...]
+    rg [OPTIONS] [-e PATTERN | -f FILE ]... [<path> ...]
+    rg [OPTIONS] --files [<path> ...]
+    rg [OPTIONS] --type-list")
+        .template("\
+{bin} {version}
+
+USAGE:{usage}
+
+FLAGS:
+{flags}");
+
+    assert!(test::compare_output(app, "rg --help", RIPGREP_USAGE, false));
 }
 
 #[test]