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 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)
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!