Clasma

A procedural attribute macro to reduce boilerplate when passing partially borrow structs into functions.

Overview

The #[partial] function annotation generates a macro_rules! macro of the same name and does not touch the function signature. This macro is callable similarly to the original function, except that one can pass a struct instance to provide the arguments annotated with #[clasma].

This attempts to make partial or "split" borrows more ergonomic in Rust, where the borrow checker sometimes requires functions to borrow references to individual fields rather than a single mutable reference to the parent struct, leading to verbose call sites.

Usage

struct Mystruct {
    a: A,
    b: B,
}

let mut x = Mystruct {
    a: A::new(),
    b: B::new(),
};

The first argument to foo! is the struct to be partially borrowed. One passes the remaining arguments without #[clasma] attributes in the same order as the signature.

#[partial]
fn foo(#[clasma] a: &mut A, #[clasma] b: &B, some_arg: u8) {
    // ...
}

foo!(x, 3);
// expands to:
// foo(&mut x.a, &x.b, 3);

One can reorder struct fields, as long as field names match up with #[clasma] argument names. One can also optionally provide generic parameters inside angle brackets <...>.

#[partial]
fn bar<T>(some_arg: T, #[clasma] b: &B, #[clasma] a: &mut A) {
    // ...
}

bar!(<&str>, x, "hello");
// expands to:
// bar::<&str>("hello", &x.b, &mut x.a);

Lifetime parameters are also supported.

#[partial]
fn baz<'t: 'static>(#[clasma] b: &'t B, #[clasma] a: &'t A, other_arg: &'t u8) {
    // ...
}

const y: Mystruct = Mystruct {
    a: A::new(),
    b: B::new(),
};

baz!(<'static>, y, &3);
// expands to:
// baz::<'static>(&y.b, &y.a, &3);

Motivating Example

Imagine a Tourist with a list of travel destinations, that counts the number of times he visits one of his destinations.

struct Tourist {
    n_visits: u32,
    destinations: Vec<String>
}

Before

Without partial borrowing, this code does not compile.

impl Tourist {
    fn visit(&mut self, dest: &String) {
        if self.destinations.contains(dest) {
            self.n_visits += 1;
        }
    }

    fn visit_all(&mut self) {
        for dest in &self.destinations { // <- immutable borrow occurs here
            self.visit(dest); // ERROR: `*self` is also borrowed as immutable 
        }
        println!("Visited {} countries", self.destinations.len());
    }
}

The issue is that visit unnecessarily borrows self.destinations mutably when it only needs an immutable borrow. A workaround would be to borrow each struct field separately on every call to visit:

impl Tourist {
    fn visit(destinations: &Vec<String>, n_visits: &mut u32, dest: &String) {
        if destinations.contains(dest) {
            n_visits += 1;
        }
    }

    fn visit_all(&mut self) {
        for dest in &self.destinations {
            Self::visit(&self.destinations, &mut self.n_visits, dest);
        }
        println!("Visited {} countries", self.destinations.len());
    }
}

However, this gets tedious as the number of fields increases.

With clasma::partial

The partial macro handles borrowing and argument passing.

#[partial]
fn visit(#[clasma] destinations: &Vec<String>, #[clasma] n_visits: &mut u32, dest: &String) {
    if destinations.contains(dest) {
        *n_visits += 1;
    }
}

impl Tourist {
    fn visit_all(&mut self) {
        for dest in &self.destinations {
            visit!(self, dest); // `visit!` automatically borrows the corresponding fields of `self`
        }
        println!("Visited {} countries", self.destinations.len());
    }
}

Installation

cargo add clasma