Crate tear

Typed early returns and loop control + Syntax sugar for try!-like error handling

Works with Rust v1.34+ (released on 11 April 2019)

Getting started

The main focus of this crate are the following three macros:

• tear! is used with ValRet for typed early returns.
• terror! is syntax-sugar for try! or the ? operator.
• twist! works with Looping to implement typed loop control.

Look at the synopsis for a general idea of what is possible, and then read the documentation for the macro that interests you.

Otherwise, read the overview module documentation that mentions all the things in this crate.

Feature flags

• The “experimental” crate feature enables support for the experimental Try trait.

• The “combinators” crate feature adds the side method to the Judge trait. It lets you convert to Either any type that implements Judge. You can then use Either’s combinators to do what you want.

• (dev) “ignore-ui” lets you ignore error message tests because all of them are wrong as soon as you have any warnings.

Synopsis

Import the macros into your module:

use tear::prelude::*;

Explicit error-handling syntax with terror!:

let handled = terror! { can_error() => print_error };
let variant = terror! { can_io_error() => CustomError::Io };

// Equivalent using `?`:
let handled = can_error().map_err(print_error)?;
let variant = can_io_error().map_err(CustomError::Io)?;

Early loop continue with twist!:

for re in regexes_strings {
    // Skip iteration if the regex fails to compile
    let re = twist! { Regex::new(re) => |_| next!() };

    // Use regex...

Keyword-like early returns with tear_if!:

fn divide_i32 (num: i32, denom: i32) -> Option<f32> {
    // Return early if dividing by 0
    tear_if! { denom == 0, None };

    // Compute quotient...

Typed returns with tear!:

// Tells the calling function to return early on failure
fn get_value_or_return() -> ValRet<String, i32> { Ret(-1) }

fn status_code() -> i32 {
    let v = tear! { get_value_or_return() };

    // Process value...

See also

• Error Handling in Rust §The real try! macro / ? operator
• guard, a crate implementing “guard” expressions, the opposite of tear_if!.

Finally, please star the GitHub repo if you found this crate useful. It helps developer ego !

Module documentation

Most things are public to allow easy modification. However, things intended only for module development are marked as (dev). A breaking change in those symbols is not a breaking change in public API. Nonetheless, they will be documented in the changelog

In this module, we define in order

• ValRet, its implementation, and its associated trait Return
• Moral, its implementation, and its associated trait Judge
• tear!, tear_if! and terror! macros

Re-exports

• pub use twist_impl::BreakValError;
• pub use twist_impl::BREAKVAL_IN_NOT_LOOP;
• pub use twist_impl::BREAK_WITHOUT_VAL;
• pub use twist_impl::BAD_BREAKVAL_TYPE;
• pub use twist_impl::Looping;
• pub use util::gut;
• pub use trait_impl::Maru;

Modules

• extra
  Crate prelude with all the extras
• overview
  Overview of things in this crate
• prelude
  Crate prelude
• trait_impl
  (dev) Implementation of the Judge and Moral traits for common types
• twist_impl
  (dev) twist! implementation
• util
  Utility functions and macros

Macros

• __bool
  (dev) Always expands to false
• __impl_twist
  (dev) Macro required by twist!
• __unit
  (dev) Always expands to ()
• anybox
  Turn a value into a Box<dyn Any>
• last
  Dirty shortcut for creating a Looping::Break
• last_if
  Explicit loop break
• next
  Dirty shortcut for creating a Looping::Continue
• next_if
  Explicit loop continue
• resume
  Dirty shortcut for creating a Looping::Resume
• ret
  Shorthand for returning a ValRet::Ret
• tear
  Turns a ValRet into a value or an early return
• tear_if
  Explicit if statement with early return
• terror
  try!-like error-handling macro
• twist
  Breaks loops (or not) based on the Looping variant

Enums

• Moral
  A notion of good and bad for the terror! macro
• ValRet
  Represents a usable value or an early return. Use with tear!

Traits

• From
  Used to do value-to-value conversions while consuming the input value. It is the reciprocal of Into.
• Judge
  Convert from and to Moral. Used for the macro map syntax.
• Return
  Convert into ValRet