jkelleyrtp/optargs

Easy-to-use optional function arguments for Rust

OptArgs: Optional arguments for Rust functions

Enable optional arguments for any function:

#[optargs::optfn]
pub fn plot(
    x: Vec<i32>,
    y: Option<Vec<i32>>,
    title: Option<&str>,
    xlabel: Option<&str>,
    ylabel: Option<&str>,
    legend: Option<bool>
) {}

// can now call it with optional arguments
plot!(
    x: vec![1,2,3], 
    y: vec![1,2,3], 
    title: "Awesome plot", 
    xlabel: "x axis", 
    ylabel: "y axis"
);

...or struct:

#[derive(optargs::OptStruct)]
pub struct Scatter {
    x: Vec<i32>,
    y: Option<Vec<i32>>,
    title: Option<&str>,
    xlabel: Option<&str>,
    ylabel: Option<&str>,
    legend: Option<bool>
}
impl Scatter {
    fn plot(self) {/* custom impl that references self */}
}

// Call it
Scatter!{ x: vec![1,2,3], y: vec![1,2,3] }.plot()

This crate is especially useful for cleaning up builder-heavy codebases and making library APIs more ergonomic. It also integrates well with Rust-Analyzer and doesn't generate heavy compile times.

---

This crate adds two macros to make it easy to add optional arguments to functions.

• #[optargs] - derive a macro_rules to call a function with optional arguments.
• #[derive(OptStruct)] - derive a typed-builder builder for a struct with optional fields.

This crate takes advantage of the recent const_generics in Rust stable (1.51), so our MSRV is 1.51.

Of note:

• All optional arguments will default to none. We currently don't provide a custom default (accepting PRs if anyone wants!).
• All optional arguments must come after required arguments.
• Unnamed positional arguments must be in the correct position.
• All arguments can be required, but now you get to name them.
• Traditional macro_rules scoping applies IE you can't use the macro before function declaration. However, they are exported with macro_export, so you can use them anywhere with crate::$MACRO. Currently, there's no way to disable this, so you can't have two functions with the same name. If this becomes a problem, we'll gladly accept a PR.

How it works:

OptArgs uses const generics to ensure compile-time correctness. I've taken the liberty of expanding and humanizing the macros in the reference examples.

In essence, we encode the state of required parameters into a ZST with const parameters. When each required parameter is added, we flip the const parameter from false to true. Only when all the required parameters are entered, then can we proceed with calling the original function.

struct Validator<const A: bool> {}
impl Validator<true> { fn validate(self) {} }
impl<const A: bool> Validator<A> { fn b(self) -> Validator<A> { self }}
// Not to worry about the unsafe, Validator is a ZST and has no place in memory.
// All this validation code will be removed anyways.
impl Validator<false> { fn a(self) -> Validator<true> { unsafe {std::mem::transmute(self)} } }

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

optargs's Issues

Add const into the mix

Allow const args to be specified in the fn!() syntax, with defaults