Crate tear[−][src]

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...

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`