Crate tear

Source
Expand description

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

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