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 withValRet
for typed early returns.terror!
is syntax-sugar fortry!
or the?
operator.twist!
works withLooping
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 theJudge
trait. It lets you convert toEither
any type that implementsJudge
. You can then useEither
’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) |
util | Utility functions and macros |
Macros
__bool | (dev) Always expands to |
__impl_twist | (dev) Macro required by |
__unit | (dev) Always expands to |
anybox | Turn a value into a |
last | Dirty shortcut for creating a |
last_if | Explicit loop break |
next | Dirty shortcut for creating a |
next_if | Explicit loop continue |
resume | Dirty shortcut for creating a |
ret | Shorthand for returning a ValRet::Ret |
tear | Turns a |
tear_if | Explicit |
terror |
|
twist | Breaks loops (or not) based on the |
Enums
Moral | A notion of good and bad for the |
ValRet | Represents a usable value or an early return. Use with |
Traits
From | Used to do value-to-value conversions while consuming the input value. It is the reciprocal of
|
Judge | Convert from and to |
Return | Convert into |