api: Adds the traits to be used with the clap-derive crate to be able…

… to use Custom Derive

Currently to use these traits clap must be built with the `unstable` feature. This does not
require a nightly compiler. These traits and APIs may change without warning (hence the `unstable`
feature flag). Once they have been stablelized and the `clap-derive` crate is released the
`unstable` feature flag will no longer be required.

src/lib.rs

@@ -574,3 +574,58 @@ mod map;
 const INTERNAL_ERROR_MSG: &'static str = "Fatal internal error. Please consider filing a bug \
                                           report at https://github.com/kbknapp/clap-rs/issues";
 const INVALID_UTF8: &'static str = "unexpected invalid UTF-8 code point";
+
+#[cfg(unstable)]
+pub use derive::{ArgEnum, ClapApp, IntoApp, FromArgMatches};
+
+#[cfg(unstable)]
+mod derive {
+    /// @TODO @release @docs
+    pub trait ClapApp: IntoApp + FromArgMatches + Sized {
+
+        /// @TODO @release @docs
+        fn parse() -> Self {
+            Self::from_argmatches(Self::into_app().get_matches())
+        }
+
+        /// @TODO @release @docs
+        fn parse_from<I, T>(argv: I) -> Self
+            where I: IntoIterator<Item = T>,
+            T: Into<OsString> + Clone
+        {
+            Self::from_argmatches(Self::into_app().get_matches_from(argv))
+        }
+
+        /// @TODO @release @docs
+        fn try_parse() -> Result<Self, clap::Error> {
+            Self::try_from_argmatches(Self::into_app().get_matches_safe()?)
+        }
+
+
+        /// @TODO @release @docs
+        fn try_parse_from<I, T>(argv: I) -> Result<Self, clap::Error> 
+            where I: IntoIterator<Item = T>,
+            T: Into<OsString> + Clone
+        {
+            Self::try_from_argmatches(Self::into_app().get_matches_from_safe(argv)?)
+        }
+    }
+
+    /// @TODO @release @docs
+    pub trait IntoApp {
+        /// @TODO @release @docs
+        fn into_app<'a, 'b>() -> clap::App<'a, 'b>;
+    }
+
+    /// @TODO @release @docs
+    pub trait FromArgMatches: Sized {
+        /// @TODO @release @docs
+        fn from_argmatches<'a>(matches: clap::ArgMatches<'a>) -> Self;
+
+        /// @TODO @release @docs
+        fn try_from_argmatches<'a>(matches: clap::ArgMatches<'a>) -> Result<Self, clap::Error>;
+    }
+
+    /// @TODO @release @docs
+    pub trait ArgEnum { }
+}