tear! now uses convert::From and add intra-doc links

Author: tqdv

CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] – 2021-04-11
+
+### Changed
+- `tear!` now uses the `convert::From` trait to automatically convert types like `?`
+
+### Fixed
+- `twist!` no longer requires traits to be in scope
+- `ret!` is now documented
+
+
 ## [0.4.0] — 2020-08-03
 
 Removed `rip!` and `fear!`. Items marked as `(dev)` are no longer considered public API.
@@ -22,6 +32,7 @@ Removed `rip!` and `fear!`. Items marked as `(dev)` are no longer considered pub
 - `tear::prelude` no longer exports the Judge and Return symbols. 
 - `Judge::ret_error` as it was supposed to be `(dev)`
 
+
 ## [0.3.0] – 2020-05-27
 
 Make `terror!` work for booleans and add the `next_if!` and `last_if!` macros.
@@ -38,6 +49,7 @@ Make `terror!` work for booleans and add the `next_if!` and `last_if!` macros.
 ### Changed
 - Use `Maru` instead of `()` in `gut` and `Judge` for `Option`
 
+
 ## [0.2.0] – 2020-05-26
 
 Implemented typed loop control with `twist!`. Make `terror!` fully compatible with `?`.
@@ -67,6 +79,7 @@ Implemented typed loop control with `twist!`. Make `terror!` fully compatible wi
 - `or_else` and `map_ret` methods on `ValRet`. Use `result().or_else()` or `result().map_err()`
   instead
 
+
 ## [0.1.1] – 2020-05-19
 
 This release was to test if I could overwrite
@@ -76,6 +89,7 @@ Turns out you can, but the squatter is still in the list of owners and authors.
 ### Added
 - Licenses
 
+
 ## [0.1.0] – 2020-05-19
 
 Initial release

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "tear"
 description = "Typed early returns and loop control + Syntax sugar for try!-like error handling"
-version = "0.4.0"
+version = "0.5.0"
 authors = ["Tilwa Qendov <[email protected]>"]
 edition = "2018"
 license = "MIT OR Apache-2.0"

notes.md

@@ -1,16 +1,20 @@
 # Notes
 
+## TODO
+
+Nothing currently
+
+## Thoughts
+
 - `Moral` is not meant to be manipulated, nor is `ValRet`. If you need combinators,
   use `Judge`'s side or result methods.
 - If there's a use-case where Judge -> Return blanket trait implementation poses a problem, I should
   replace it with a macro. Also, if auto traits get stabilized, we could let the user disable it.
-- I should probably use proc_macros instead of abusing macros for `__impl_twist!`, but I don't know how
+- I should probably use proc\_macros instead of abusing macros for `__impl_twist!`, but I don't know how
   to write one, and docs aren't easily found.
 - Convenience functions are named shortly and memorable. Trait functions are named boringly and at least
   two words.
 
-## TODO
-
 ## Useful resources
 - <https://stackoverflow.com/questions/40302026/what-does-the-tt-metavariable-type-mean-in-rust-macros>
 - <https://medium.com/@phoomparin/a-beginners-guide-to-rust-macros-5c75594498f1>

src/lib.rs

@@ -130,7 +130,7 @@ In this module, we define in order
 pub mod overview; // For documentation
 pub mod prelude;
 pub mod extra;
-pub mod trait_impl; // Move the trait implementions as they are quite noisy
+pub mod trait_impl; // Move the trait implementations as they are quite noisy
 pub mod twist_impl; // Currently only for `twist!`
 #[macro_use] pub mod util; // Utility macros that aren't the main focus. To reduce file size.
 
@@ -147,13 +147,14 @@ use ValRet::*;
 use Moral::*;
 #[cfg(feature = "combinators")] use either::Either::{self, *};
 
-/** Represents a usable value or an early return. Use with `tear!`
+/** Represents a usable value or an early return. Use with [`tear!`]
 
 # Description
 
 The idea is to type an early return. The early return either evaluates to something (Val) or
 returns early (Ret).
 */
+#[must_use = "Suggestion: use tear! to handle it"]
 #[derive(PartialEq, Debug, Clone)]
 pub enum ValRet<V, R> {
 	/// The usable value
@@ -164,7 +165,7 @@ pub enum ValRet<V, R> {
 
 /**
 **NB**: Other combinators such as `and`, `and_then`, `or`, `map_val`
-aren't implemented because I didn't need them and not because they aren't useful.
+aren't implemented because I didn't need them, not because they aren't useful.
 
 Examples will all use the following two variables
 ```
@@ -182,7 +183,7 @@ impl<V, R> ValRet<V, R> {
 	pub fn ret (self) -> Option<R> { maybe_match! { self, Ret(r) => r } }
 }
 
-/// Convert into ValRet
+/// Convert into [`ValRet`]
 pub trait Return where Self :Sized {
 	/// The Val in ValRet
 	type Value;
@@ -193,7 +194,7 @@ pub trait Return where Self :Sized {
 	fn into_valret (self) -> ValRet<Self::Value, Self::Returned>;
 }
 
-/// A notion of good and bad for the `terror!` macro
+/// A notion of good and bad for the [`terror!`] macro
 #[derive(PartialEq, Debug, Clone)]
 pub enum Moral<Y, N> {
 	/// The good
@@ -248,11 +249,11 @@ impl<Y, N> Moral<Y, N> {
 
 	/* Special conversions */
 
-	/** (dev) Convert to a `Looping` by mapping Good to Resume, and Bad through a function
+	/** (dev) Convert to a [`Looping`] by mapping Good to Resume, and Bad through a function
 
 	The function `f` takes the bad value and maps it to a `Looping` value.
 
-	Used in the `twist!` macro with the mapping (`=>`) syntax. See `twist!` documentation.
+	Used in the `twist!` macro with the mapping (`=>`) syntax. See [`twist!`] documentation.
 	*/
 	pub fn resume_or_else<B> (self, f :impl FnOnce(N) -> Looping<Y, B>) -> Looping<Y, B> {
 		match self {
@@ -262,9 +263,9 @@ impl<Y, N> Moral<Y, N> {
 	}
 }
 
-/** Convert from and to Moral. Used for the macro map syntax.
+/** Convert from and to [`Moral`]. Used for the macro map syntax.
 
-This mirrors the `std::ops::Try` trait.
+This mirrors the [`ops::Try`](`core::ops::Try`) trait.
 
 It is used for the `=>` mapping syntax of macros, to differentiate the value we want to keep from
 the value we want to map through the function.
@@ -304,9 +305,9 @@ pub trait Judge :Sized {
 	}
 }
 
-/** Turns a `ValRet` into a value or an early return
+/** Turns a [`ValRet`] into a value or an early return
 
-It also coerces its argument to a ValRet (Return trait).
+It also coerces its argument to a `ValRet` ([`Return`] trait).
 
 # Description
 
@@ -326,6 +327,10 @@ let x = tear! { $e => $f }
 Same as the previous form, but the return value `r` is first mapped through $f before returning.
 In short, we return `$f(r)`.
 
+Additionally, both forms make use of the [`convert::From`](`core::convert::From`) trait to automatically convert
+the value when returning it. This behaviour is the same as the try operator `?`.
+You may need to be more specific with type annotations so that the compiler can infer the right types.
+
 # Examples
 
 tear! with Val and Ret.
@@ -335,7 +340,7 @@ tear! with Val and Ret.
 # use tear::prelude::*;
 #
 // "Ian" is assigned to name
-let name = tear! { Val("Ian") };
+let name = tear! { Val::<_, ()>("Ian") };
 # assert_eq![ name, "Ian" ];
 
 # fn func () -> i32 {
@@ -379,6 +384,23 @@ fn string_id(s: OsString) -> String {
 # assert_eq![ string_id(OsString::from("ROOT")), "4" ];
 ```
 
+Automatic conversion with `convert::From`
+
+```rust
+# use tear::prelude::*;
+#[derive(Debug, PartialEq, Eq)]
+struct MyInt(u8);
+impl std::convert::From<u8> for MyInt {
+    fn from(x :u8) -> Self { Self(x) }
+}
+
+fn five_as_myint() -> MyInt {
+    tear! { Ret(5) }
+}
+
+assert_eq![ five_as_myint(), MyInt(5) ];
+```
+
 # Naming
 
 The name "tear" comes from the image of tearing apart the the usable value from the early return.
@@ -390,7 +412,7 @@ macro_rules! tear {
 	( $e:expr ) => {
 		match $crate::Return::into_valret($e) {
 			$crate::ValRet::Val(v) => v,
-			$crate::ValRet::Ret(r) => return r,
+			$crate::ValRet::Ret(r) => return $crate::From::from(r),
 		}
 	};
 	// With a mapping function eg. `tear! { $e => |v| v }` or `tear! { $e => func }`
@@ -435,7 +457,7 @@ Early return a value: recursively computing the length of a slice.
 # #[macro_use] extern crate tear;
 fn len (v: &[i32]) -> usize {
     // Base case
-    tear_if! { v.is_empty(), 0 }
+    tear_if! { v.is_empty(), 0 as usize }
     
     // Recursion
     1 + len(&v[1..])
@@ -495,10 +517,10 @@ macro_rules! tear_if {
 	};
 }
 
-/** `try!`-like error-handling macro
+/** [`try!`]-like error-handling macro
 
 `terror!` is like `tear!`, but stronger and more righteous.
-It automatically converts the Bad value to the return type Bad value (Judge trait).
+It automatically converts the Bad value to the return type Bad value ([`Judge`] trait).
 
 # Description
 
@@ -516,6 +538,9 @@ let x = terror! { $e => $f };
 Same as the previous form, but the bad `value` is first mapped through $f before returning.
 In short, we return `from_bad($f(value))`.
 
+Both forms make use of the [`convert::From`](`core::convert::From`) trait to convert the bad value,
+making it fully compatible with `try!` and the `?` operator.
+
 # Explanation using examples
 
 The description is especially terse on purpose: it is really hard to explain what `terror!` does without using examples.
@@ -641,6 +666,46 @@ To do so, we extract the `ParseIntError`, and wrap it into our custom error with
 That is the role of the function following the `=>` arrow: it converts the error type of
 the left statement, into the function return error type.
 
+### Automatic conversion just like `?`
+
+Since `terror!` mimics `?`, it also supports autoconversion using the `convert::From` trait.
+
+```rust
+# use tear::prelude::*;
+# use std::io;
+# macro_rules! assert_match {
+#     ( $e:expr, $($p:pat)|+ ) => {
+#         match $e {
+#             $($p)|+ => (),
+#             ref e => panic!("assertion failed: `{:?}` does not match `{}`", e, stringify!($($p)|+)),
+#         }
+#     }
+# }
+# #[derive(Debug)]
+enum CustomError {
+    IOError(io::Error),
+    OtherError,
+}
+
+impl std::convert::From<io::Error> for CustomError {
+    fn from(x :io::Error) -> Self {
+        Self::IOError(x)
+    }
+}
+
+# fn fail_with_io_error() -> io::Result<()> {
+#     Err(io::Error::new(io::ErrorKind::Other, "oh no!"))
+# }
+#
+fn auto_convert() -> Result<bool, CustomError> {
+    terror! { fail_with_io_error() };
+    Ok(false)
+}
+
+assert_match![ auto_convert(), Err(CustomError::IOError(_)) ];
+```
+
+
 # `terror!` vs. `?` when moving into closures
 
 The only difference between `terror!` and `?` is that since `terror!` is a macro,

src/overview.rs

@@ -15,10 +15,10 @@ All symbols are accessible directly from the crate root as we reexport them all.
 
 # Early returns
 
-We represent an early return with `ValRet` and process it with `tear!`. The macro accepts any
-type that knows how to convert to a `ValRet` using the `Return` trait.
+We represent an early return with [`ValRet`] and process it with [`tear!`]. The macro accepts any
+type that knows how to convert to a `ValRet` using the [`Return`] trait.
 
-We use `tear!` in `tear_if!` to implement early returns as a syntax.
+We use `tear!` in [`tear_if!`] to implement early returns as a syntax.
 
 # Mapping syntax
 
@@ -36,10 +36,10 @@ This is why arguments must implement the `Judge` trait that knows how to convert
 
 # Error handling
 
-`terror!` is the error-handling macro. It depends on `Judge` to decide if the value is usable
+`terror!` is the error-handling macro. It depends on [`Judge`] to decide if the value is usable
 or not.
 
-A short way of discarding the error value in a function returning `Option<T>`, is to use the `gut`
+A short way of discarding the error value in a function returning `Option<T>`, is to use the [`gut`]
 function:
 
 ```
@@ -52,7 +52,7 @@ fn f () -> Option<i32> {
 ```
 
 If you need to do some things before returning `None`, use a block, and return `tear::Maru` at the
-end. `Maru` is the placeholder type used to represent the bad value of `Option<T>`, or the good
+end. [`Maru`] is the placeholder type used to represent the bad value of `Option<T>`, or the good
 and bad values of `bool`.
 
 # Loop control
@@ -70,8 +70,8 @@ assert_eq![ x, 3 ];
 ```
 
 In the complex case where you want to breakval from multiple loops with a different type, you can
-use `Box<dyn Any>` to hide those type. We provide the `anybox!` macro to take the concrete type,
-and wrap it into a `Box<dyn Any>` object. See `twist!` documentation for more information.
+use `Box<dyn Any>` to hide those type. We provide the [`anybox!`] macro to take the concrete type,
+and wrap it into a `Box<dyn Any>` object. See [`twist!`] documentation for more information.
 
 ```
 use tear::prelude::*;
@@ -88,7 +88,7 @@ assert_eq![ x, 3 ];
 ```
 
 For simple cases where you only break from one loop (ie. when you don't use `-labels`), you can
-use the `last!`, `next!`, and `resume!` as shortcuts for the right-hand side of `twist!`:
+use the [`last!`], [`next!`], and [`resume!`] as shortcuts for the right-hand side of `twist!`:
 
 ```
 use tear::extra::*;
@@ -98,14 +98,9 @@ loop {
 }
 ```
 
-There's also `next_if!` and `last_if!` macros that continue or break the loop based on a condition
+There's also [`next_if!`] and [`last_if!`] macros that continue or break the loop based on a condition
 or a pattern match.
 
-# Legacy
-
-`rip!` is an alias for `terror!`, and `fear!` is an alias for `tear!`. This is because mapping
-syntax and normal syntax used to separate.
-
 # Add functionality to your own types
 
 If you want to enable the mapping syntax for your type.
@@ -126,3 +121,4 @@ If using the "experimental" crate feature, then you only need to implement the `
 `Judge` and `Return` trait will be automatically implemented.
 
 */
+use super::*;

src/trait_impl.rs

@@ -15,7 +15,7 @@ use crate::*;
 
 /** A placeholder type with a single value ◯
 
-It mirrors the `NoneError` type. For example, it is used in conjunction with `Moral` to
+It mirrors the [`NoneError`](`core::option::NoneError`) type. For example, it is used in conjunction with [`Moral`] to
 represent the bad types for `bool` or `Option<T>`.
 
 # Examples
@@ -39,7 +39,7 @@ fn f() -> () {
 
 # See also
 
-- the `gut` function, that takes over the right-hand side
+- the [`gut`] function, that takes over the right-hand side
 */
 #[derive(Copy, Debug, Clone)]
 pub struct Maru;