Support for custom error type in FromStr derive (#494)

Resolves #112
Related to #396

Add support for a `#[from_str(error(error_ty[, error_fn]))]` attribute
to specify a custom error type for `FromStr` derive for enums (or
structs with no fields) in case where the string does not match any
variant. A conversion function to convert a `derive_more::FromStrError`
to the custom error type might optionally be provided. Otherwise the
custom error type `T` must satisfy `derive_more::FromStrError: Into<T>`.

[`strum`](https://github.com/Peternator7/strum) provides similar
functionality. See Peternator7/strum#380.

This approach could be used to set a custom error type for `TryInto`
derive as well (#396).

Co-authored-by: Kai Ren <[email protected]>
Co-authored-by: Jelte Fennema-Nio <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -29,6 +29,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   ([#477](https://github.com/JelteF/derive_more/pull/477))
 - Support `Deref` and `DerefMut` derives for enums.
   ([#485](https://github.com/JelteF/derive_more/pull/485))
+- Support custom error in `FromStr` derive.
+  ([#494](https://github.com/JelteF/derive_more/pull/494))
 
 ### Changed
 

impl/doc/from_str.md

@@ -117,6 +117,8 @@ assert_eq!(
 
 Code like this is generated:
 ```rust
+# use core::str::FromStr;
+#
 # enum EnumNoFields {
 #     Foo,
 #     Bar,
@@ -126,7 +128,7 @@ Code like this is generated:
 #
 impl derive_more::core::str::FromStr for EnumNoFields {
     type Err = derive_more::FromStrError;
-    fn from_str(s: &str) -> Result<Self, derive_more::FromStrError> {
+    fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
         Ok(match s.to_lowercase().as_str() {
             "foo" => Self::Foo,
             "bar" => Self::Bar,
@@ -158,11 +160,13 @@ assert_eq!("FOO".parse::<Foo>().unwrap(), Foo);
 
 Code like this is generated:
 ```rust
+# use core::str::FromStr;
+#
 # struct Foo;
 #
 impl derive_more::core::str::FromStr for Foo {
     type Err = derive_more::FromStrError;
-    fn from_str(s: &str) -> Result<Self, derive_more::FromStrError> {
+    fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
         Ok(match s.to_lowercase().as_str() {
             "foo" => Self,
             _ => return Err(derive_more::FromStrError::new("Foo")),
@@ -228,3 +232,212 @@ assert_eq!("variant-two".parse::<Enum>().unwrap(), Enum::VariantTwo);
 > # assert_eq!("Bar".parse::<Enum>().unwrap(), Enum::Bar);
 > # assert_eq!("Ba_R".parse::<Enum>().unwrap(), Enum::Ba_R);
 > ```
+
+
+
+
+## Custom error
+
+The `#[from_str(error(<ty>[, <conv>]))]` attribute can be used to convert the `FromStr`' `Err` type
+into a custom error type. If the conversion function is not provided, the custom error type must implement
+`From<FromStr::Err>`.
+
+
+### Forwarding
+
+Given the following struct:
+```rust
+# use derive_more::{From, FromStr};
+#
+#[derive(From)]
+struct CustomError(core::num::ParseIntError);
+
+#[derive(FromStr, Debug, Eq, PartialEq)]
+#[from_str(error(CustomError))]
+struct MyInt(i32);
+```
+Code like this is generated:
+```rust
+# use core::str::FromStr;
+# use derive_more::From;
+#
+# #[derive(From)]
+# struct CustomError(core::num::ParseIntError);
+#
+# struct MyInt(i32);
+#
+impl derive_more::core::str::FromStr for MyInt {
+    type Err = CustomError;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        FromStr::from_str(s)
+            .map(|v| Self(v))
+            .map_err(Into::into)
+    }
+}
+```
+
+For the explicitly specified error conversion:
+```rust
+# use derive_more::FromStr;
+#
+struct CustomError(core::num::ParseIntError);
+
+impl CustomError {
+    fn new(err: core::num::ParseIntError) -> Self {
+        Self(err)
+    }
+}
+
+#[derive(FromStr, Debug, Eq, PartialEq)]
+#[from_str(error(CustomError, CustomError::new))]
+struct MyInt(i32);
+```
+Code like this is generated:
+```rust
+# use core::str::FromStr;
+#
+# struct CustomError(core::num::ParseIntError);
+#
+# impl CustomError {
+#     fn new(err: core::num::ParseIntError) -> Self {
+#         Self(err)
+#     }
+# }
+#
+# struct MyInt(i32);
+#
+impl derive_more::core::str::FromStr for MyInt {
+    type Err = CustomError;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        FromStr::from_str(s)
+            .map(|v| Self(v))
+            .map_err(CustomError::new)
+    }
+}
+```
+
+Custom error for a newtype struct with one named field, *e.g*,
+```rust
+# use derive_more::{From, FromStr};
+#
+#[derive(From)]
+struct CustomError(core::num::ParseIntError);
+
+#[derive(FromStr)]
+#[from_str(error(CustomError))]
+struct Point1D {
+    x: i32,
+}
+```
+works similarly.
+
+
+### Flat representation
+
+Custom error type is also supported for empty enums and unit structs.
+
+Given the following enum:
+```rust
+# use derive_more::{From, FromStr};
+#
+#[derive(From)]
+struct CustomError(derive_more::FromStrError);
+
+#[derive(FromStr, Debug, Eq, PartialEq)]
+#[from_str(error(CustomError))]
+enum EnumNoFields {
+    Foo,
+    Bar,
+    Baz,
+}
+```
+Code like this is generated:
+```rust
+# use core::str::FromStr;
+# use derive_more::From;
+#
+# #[derive(From)]
+# struct CustomError(derive_more::FromStrError);
+#
+# enum EnumNoFields {
+#     Foo,
+#     Bar,
+#     Baz,
+# }
+#
+impl derive_more::core::str::FromStr for EnumNoFields {
+    type Err = CustomError;
+    fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
+        Ok(match s.to_lowercase().as_str() {
+            "foo" => Self::Foo,
+            "bar" => Self::Bar,
+            "baz" => Self::Baz,
+            _ => return Err(derive_more::FromStrError::new("EnumNoFields").into()),
+        })
+    }
+}
+```
+
+For the explicitly specified error conversion:
+```rust
+# use derive_more::FromStr;
+#
+struct CustomError(derive_more::FromStrError);
+
+impl CustomError {
+   pub fn new(err: derive_more::FromStrError) -> Self {
+       Self(err)
+   }
+}
+
+#[derive(FromStr, Debug, Eq, PartialEq)]
+#[from_str(error(CustomError, CustomError::new))]
+enum EnumNoFields {
+    Foo,
+    Bar,
+    Baz,
+}
+```
+Code like this is generated:
+```rust
+# use core::str::FromStr;
+#
+# struct CustomError(derive_more::FromStrError);
+#
+# impl CustomError {
+#    pub fn new(err: derive_more::FromStrError) -> Self {
+#        Self(err)
+#    }
+# }
+#
+# enum EnumNoFields {
+#     Foo,
+#     Bar,
+#     Baz,
+# }
+#
+impl derive_more::core::str::FromStr for EnumNoFields {
+    type Err = CustomError;
+    fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
+        Ok(match s.to_lowercase().as_str() {
+            "foo" => Self::Foo,
+            "bar" => Self::Bar,
+            "baz" => Self::Baz,
+            _ => return Err(CustomError::new(derive_more::FromStrError::new("EnumNoFields"))),
+        })
+    }
+}
+```
+
+Custom error type for unit structs, *e.g*,
+```rust
+# use derive_more::{From, FromStr};
+#
+#[derive(From)]
+struct CustomError(derive_more::FromStrError);
+
+#[derive(FromStr)]
+#[from_str(error(CustomError))]
+struct Foo;
+```
+works similarly.