Auto merge of #265 - kbknapp:issue-262, r=james-darkfox

Issue 262 - Result and Lossy options for invalid Unicode

This allows not `panic!`ing on invalid unicode characters, and the option of returning lossy results. This does **not** turn all results into an `OsStr` preserving invalid unicode.

If this helps with #262 we can merge (after review), otherwise we'll continue to discuss if there's a better way to handle this issue.

Author: homu

src/app/app.rs

@@ -8,7 +8,7 @@ pub enum ClapErrorType {
     /// Error occurs when some possible values were set, but clap found unexpected value
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg};
@@ -22,7 +22,7 @@ pub enum ClapErrorType {
     /// Error occurs when clap found unexpected flag or option
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg};
@@ -34,7 +34,7 @@ pub enum ClapErrorType {
     /// Error occurs when clap found unexpected subcommand
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg, SubCommand};
@@ -50,7 +50,7 @@ pub enum ClapErrorType {
     /// Error occurs when option does not allow empty values but some was found
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg};
@@ -70,7 +70,7 @@ pub enum ClapErrorType {
     /// Error occurs when argument got more values then were expected
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg};
@@ -83,7 +83,7 @@ pub enum ClapErrorType {
     /// Error occurs when argument got less values then were expected
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg};
@@ -96,7 +96,7 @@ pub enum ClapErrorType {
     /// Error occurs when clap find two ore more conflicting arguments
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg};
@@ -109,7 +109,7 @@ pub enum ClapErrorType {
     /// Error occurs when one or more required arguments missing
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg};
@@ -122,7 +122,7 @@ pub enum ClapErrorType {
     /// Error occurs when required subcommand missing
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg, AppSettings, SubCommand};
@@ -140,7 +140,7 @@ pub enum ClapErrorType {
     /// `AppSettings::ArgRequiredElseHelp` was used
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg, AppSettings, SubCommand};
@@ -157,7 +157,7 @@ pub enum ClapErrorType {
     /// Error occurs when clap find argument while is was not expecting any
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App};
@@ -168,7 +168,7 @@ pub enum ClapErrorType {
     /// Error occurs when argument was used multiple times and was not set as multiple.
     ///
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg};
@@ -178,6 +178,24 @@ pub enum ClapErrorType {
     ///     .get_matches_from_safe(vec!["", "--debug", "--debug"]);
     /// ```
     UnexpectedMultipleUsage,
+    /// Error occurs when argument contains invalid unicode characters
+    ///
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use clap::{App, Arg};
+    /// # use std::os::unix::ffi::OsStringExt;
+    /// # use std::ffi::OsString;
+    /// let result = App::new("myprog")
+    ///     .arg(Arg::with_name("debug")
+    ///         .short("u")
+    ///         .takes_value(true))
+    ///     .get_matches_from_safe(vec![OsString::from_vec(vec![0x20]), 
+    ///                                 OsString::from_vec(vec![0xE9])]);
+    /// assert!(result.is_err());
+    /// ```
+    InvalidUnicode
 }
 
 /// Command line argument parser error

src/app/errors.rs

@@ -10,7 +10,7 @@ pub enum AppSettings {
     ///
     /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements)
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, AppSettings};
@@ -23,7 +23,7 @@ pub enum AppSettings {
     ///
     /// **NOTE:** This defaults to false (subcommands do *not* need to be present)
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, AppSettings};
@@ -37,7 +37,7 @@ pub enum AppSettings {
     ///
     /// **NOTE:** Subcommands count as arguments
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, AppSettings};
@@ -52,7 +52,7 @@ pub enum AppSettings {
     /// **NOTE:** The version for the current command and this setting must be set **prior** to
     /// adding any subcommands
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg, SubCommand, AppSettings};
@@ -72,7 +72,7 @@ pub enum AppSettings {
     ///
     /// **NOTE:** Do not set this value to false, it will have undesired results!
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg, SubCommand, AppSettings};
@@ -90,7 +90,7 @@ pub enum AppSettings {
     ///
     /// **NOTE:** This setting is cosmetic only and does not affect any functionality.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg, SubCommand, AppSettings};
@@ -112,7 +112,7 @@ pub enum AppSettings {
     /// behavior for all subcommands, you must set this on each command (needing this is extremely
     /// rare)
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg, AppSettings};
@@ -131,7 +131,7 @@ pub enum AppSettings {
     /// still be displayed and exit. If this is *not* the desired result, consider using
     /// `.arg_required_else_help()`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # use clap::{App, Arg, AppSettings};