#builder

macro typed-builder

Compile-time type-checked builder derive

5 releases (3 breaking)

0.3.0 Feb 19, 2019
0.2.0 Feb 6, 2019
0.1.1 Jul 25, 2018
0.1.0 Oct 5, 2017
0.0.0 Oct 4, 2017

#107 in Procedural macro helpers

Download history 149/week @ 2018-12-20 569/week @ 2018-12-27 46/week @ 2019-01-03 25/week @ 2019-01-10 29/week @ 2019-01-17 42/week @ 2019-01-24 17/week @ 2019-01-31 53/week @ 2019-02-07 37/week @ 2019-02-14 27/week @ 2019-02-21 44/week @ 2019-02-28 68/week @ 2019-03-07 80/week @ 2019-03-14 75/week @ 2019-03-21 52/week @ 2019-03-28

196 downloads per month
Used in 6 crates (2 directly)

MIT license

28KB
511 lines

Build Status Latest Version Rust Documentation

Rust Typed Builder

Creates a compile-time verified builder:

#[macro_use]
extern crate typed_builder;

#[derive(TypedBuilder)]
struct Foo {
    // Mandatory Field:
    x: i32,

    // #[builder(default)] without parameter - use the type's default
    #[builder(default)]
    y: Option<i32>,

    // Or you can set the default
    #[builder(default=20)]
    z: i32,

    // If the default cannot be parsed, you must encode it as a string:
    #[builder(default_code="vec![30, 40]")]
    w: Vec<u32>,
}

Build in any order:

Foo::builder().x(1).y(2).z(3).w(vec![4, 5]).build();
Foo::builder().z(1).x(2).w(vec![4, 5]).y(3).build();

Omit optional fields(the one marked with #[default]):

Foo::builder().x(1).build()

But you can't omit non-optional arguments - or it won't compile:

Foo::builder().build(); // missing x
Foo::builder().x(1).y(2).y(3); // y is specified twice

Features

  • Custom derive for generating the builder pattern.
  • All setters are accepting Into values.
  • Compile time verification that all fields are set before calling .build().
  • Compile time verification that no field is set more than once.
  • Ability to annotate fields with #[builder(default)] to make them optional and specify a default value when the user does not set them.
  • Generates simple documentation for the .builder() method.

Limitations

  • No custom build error - if you neglect to set a field or set a field twice you'll get regular no method error that doesn't tell you what you did wrong.
    • If there is a way to generate proper errors I'll gladly implement it.
  • The generated builder type has ugly internal name and many generic parameters. It is not meant for passing around and doing fancy builder tricks - only for nicer object creation syntax(constructor with named arguments and optional arguments).
    • For the that reason, all builder methods are call-by-move and the builder is not cloneable. Saves the trouble of determining if the fields are cloneable...
    • If you want a builder you can pass around, check out derive-builder. It's API does not conflict with typed-builder's so you can be able to implement them both on the same type.

Alternatives - and why typed-builder is better

  • derive-builder - does all the checks in runtime, returning a Result you need to unwrap.
  • safe-builder-derive - this one does compile-time checks - by generating a type for each possible state of the builder. Rust can remove the dead code, but your build time will still be exponential. typed-builder is encoding the builder's state in the generics arguments - so Rust will only generate the path you actually use.

Dependencies

~783KB
~18K SLoC