Crate derive_builder [−] [src]

Derive a builder for a struct

This crate implements the builder pattern for you. Just apply #[derive(Builder)] to a struct Foo, and it will derive an additional struct FooBuilder with setter-methods for all fields and a build-method — the way you want it.

Quick Start

Add derive_builder as a dependency to you Cargo.toml.

What you write

#[macro_use]
extern crate derive_builder;

#[derive(Builder)]
struct Lorem {
    ipsum: String,
    // ..
}

What you get


#[derive(Clone, Default)]
struct LoremBuilder {
    ipsum: Option<String>,
}

#[allow(dead_code)]
impl LoremBuilder {
    pub fn ipsum<VALUE: Into<String>>(&mut self, value: VALUE) -> &mut Self {
        let mut new = self;
        new.ipsum = Some(value.into());
        new
    }
    fn build(&self) -> Result<Lorem, String> {
        Ok(Lorem {
            ipsum: Clone::clone(self.ipsum
                .as_ref()
                .ok_or("ipsum must be initialized")?),
        })
    }
}

By default all generated setter-methods take and return &mut self (aka non-conusuming builder pattern). Accordingly the build method also takes a reference by default.

You can easily opt into different patterns and control many other aspects.

The build method returns Result<T, String>, where T is the struct you started with. It returns Err<String> if you didn't initialize all fields.

Builder Patterns

Let's look again at the example above. You can build structs like this:

let x: Lorem = LoremBuilder::default().ipsum("42").build()?;

Ok, chaining method calls is nice, but what if ipsum("42") should only happen if geek = true?

So let's make this call conditional

let mut builder = LoremBuilder::default();
if geek {
    builder.ipsum("42");
}
let x: Lorem = builder.build()?;

Now it comes in handy that our setter methods takes and returns a mutable reference. Otherwise we would need to write something more clumsy like builder = builder.ipsum("42") to reassign the return value each time we have to call a setter conditionally.

Setters with mutable references are therefore a convenient default for the builder pattern in Rust.

But this is a free world and the choice is still yours.

Owned, aka Consuming

Precede your struct (or field) with #[builder(pattern="owned")] to opt into this pattern.

  • Setters take and return self.
  • PRO: Setter calls and final build method can be chained.
  • CON: If you don't chain your calls, you have to create a reference to each return value, e.g. builder = builder.ipsum("42").

This pattern is recommended and active by default if you don't specify anything else. You can precede your struct (or field) with #[builder(pattern="mutable")] to make this choice explicit.

  • Setters take and return &mut self.
  • PRO: Setter calls and final build method can be chained.
  • CON: The build method must clone or copy data to create something owned out of a mutable reference. Otherwise it could not be used in a chain. (*)

Immutable

Precede your struct (or field) with #[builder(pattern="immutable")] to opt into this pattern.

  • Setters take and return &self.
  • PRO: Setter calls and final build method can be chained.
  • CON: If you don't chain your calls, you have to create a reference to each return value, e.g. builder = builder.ipsum("42").
  • CON: The build method and each setter must clone or copy data to create something owned out of a reference. (*)

(*) Performance Considerations

Luckily Rust is clever enough to optimize these clone-calls away in release builds for your every-day use cases. Thats quite a safe bet - we checked this for you. ;-) Switching to consuming signatures (=self) is unlikely to give you any performance gain, but very likely to restrict your API for non-chained use cases.

More Features

Generic structs

#[macro_use]
extern crate derive_builder;

#[derive(Builder, Debug, PartialEq, Default, Clone)]
struct GenLorem<T: Clone> {
    ipsum: String,
    dolor: T,
}

fn main() {
    let x = GenLoremBuilder::default().ipsum("sit").dolor(42).build().unwrap();
    assert_eq!(x, GenLorem { ipsum: "sit".into(), dolor: 42 });
}

Doc-Comments and Attributes

#[derive(Builder)] copies doc-comments and attributes #[...] from your fields to the according builder fields and setter-methods, if it is one of the following:

  • /// ...
  • #[doc = ...]
  • #[cfg(...)]
  • #[allow(...)]

The whitelisting minimizes interference with other custom attributes like Serde/Diesel etc.

#[macro_use]
extern crate derive_builder;

#[derive(Builder)]
struct Lorem {
    /// `ipsum` may be any `String` (be creative).
    ipsum: String,
    #[doc = r"`dolor` is the estimated amount of work."]
    dolor: i32,
    // `#[derive(Builder)]` understands conditional compilation via cfg-attributes,
    // i.e. => "no field = no setter".
    #[cfg(target_os = "macos")]
    #[allow(non_snake_case)]
    Im_a_Mac: bool,
}

Setter Visibility

Setters are public by default. You can precede your struct (or field) with #[builder(public)] to make this explicit.

Otherwise precede your struct (or field) with #[builder(private)] to opt into private setters.

Setter Prefixes

Setter methods are named after their corresponding field by default.

You can precede your struct (or field) with e.g. #[builder(setter_prefix="xyz") to change the method name to xyz_foo if the field is named foo. Note that an underscore is included by default, since Rust favors snake case here.

Troubleshooting

Gotchas

  • Tuple structs and unit structs are not supported as they have no field names.
  • When defining a generic struct, you cannot use VALUE as a generic parameter as this is what all setters are using.

Debugging Info

If you experience any problems during compilation, you can enable additional debug output by setting the environment variable RUST_LOG=derive_builder=trace before you call cargo or rustc. Example: RUST_LOG=derive_builder=trace cargo test.

Report Issues and Ideas

https://github.com/colin-kiegel/rust-derive-builder/issues

If possible please try to provide the debugging info if you experience unexpected compilation errors (see above).