guard_macros

This library provides a macro called guard! which replaces recurring let-else and if statements.

For documentation, refer to Rustdoc:

• latest version
• latest commit

lib.rs:

• Usage
• Overview
• Example
• Specification

Usage

// returns when (expr) is evaluated to false
guard!( (expr) );

// returns when refuted (i.e. (expr) doesn't match (pat))
guard!( (pat) = (expr) );

// panics instead of returning (called "Refute Handler")
guard!( (expr) => panic!("false") );
guard!( (pat) = (expr) => panic!("refuted") );

guard! {
    // can be repeated
    (expr),
    (pat) = (expr) => panic!("refuted"),

    // can be scoped and nested
    {
        (expr),
        (pat) = (expr),
        {
            (expr),
            (pat) = (expr) => panic!("baz"),
        } => _, // inherit refute handler
    } => panic!("foo"),
}

Overview

guard_macros provides two macros:

• guard! which replaces recurring let-else and if statements.
• make_guard! which defines new guard macros with different default Refute Handlers.

Refute Handler

A "Refute Handler" is an expression that is executed when the condition of a clause is not met. It can be specified by appending => followed by an expression, either:

• to a single clause

  guard! {
      (pat) = (expr) => panic!("refuted"),
      (expr) => panic!("false"),
  }
  

• or to a group of clauses enclosed by { }.

  guard! {
      {
          (pat) = (expr),
          (expr),
      } => panic!("unmet")
  }
  

  Note: By default, blocks create a new scope, but it can be disabled by prepending a * to the opening brace.

Example

Specification

• guard!

  ^Syntax

  GuardBody :
     GuardDecl ( , GuardDecl )* ,^?

  GuardDecl :
        *^? { GuardBody } RefuteHandlerInheritable
     | GuardClause RefuteHandler^?

  GuardClause :
        PatternNoTopAlt = Expression
     | Expression

  RefuteHandler :
     => Expression

  RefuteHandlerInheritable :
        RefuteHandler
     | => _

• make_guard!

  ^Syntax

  MakeGuardBody :
     MakeGuardDecl ( , MakeGuardDecl )* ,^?

  MakeGuardDecl :
     Identifier RefuteHandler