[]()

Builder Pattern Derive

Rust macro to automatically implement the builder pattern for arbitrary structs. A simple #[derive(Builder)] will generate a FooBuilder for your struct Foo with all setter-methods and a build method.

How it Works

use derive_builder::Builder;

#[derive(Default, Builder, Debug)]
#[builder(setter(into))]
struct Channel {
    token: i32,
    special_info: i32,
    // .. a whole bunch of other fields ..
}

fn main() {
    // builder pattern, go, go, go!...
    let ch = ChannelBuilder::default()
        .special_info(42u8)
        .token(19124)
        .build()
        .unwrap();
    println!("{:?}", ch);
}

Note that we did not write any definition or implementation of ChannelBuilder. Instead the derive_builder crate acts on #[derive(Builder)] and generates the necessary code at compile time.

This is the generated boilerplate code you didn't need to write. :-)

#[derive(Clone, Default)]
struct ChannelBuilder {
    token: Option<i32>,
    special_info: Option<i32>,
}

#[allow(dead_code)]
impl ChannelBuilder {
    pub fn token<VALUE: Into<i32>>(&mut self, value: VALUE) -> &mut Self {
        let mut new = self;
        new.token = Some(value.into());
        new
    }
    pub fn special_info<VALUE: Into<i32>>(&mut self, value: VALUE) -> &mut Self {
        let mut new = self;
        new.special_info = Some(value.into());
        new
    }
    fn build(
        &self,
    ) -> Result<Channel, ChannelBuilderError> {
        Ok(Channel {
            id: match self.id {
                Some(ref value) => Clone::clone(value),
                None => {
                    return Err(
                        Into::into(
                            ::derive_builder::UninitializedFieldError::from("id"),
                        ),
                    )
                }
            },
            token: match self.token {
                Some(ref value) => Clone::clone(value),
                None => {
                    return Err(
                        Into::into(
                            ::derive_builder::UninitializedFieldError::from("token"),
                        ),
                    )
                }
            },
            special_info: match self.special_info {
                Some(ref value) => Clone::clone(value),
                None => {
                    return Err(
                        Into::into(
                            ::derive_builder::UninitializedFieldError::from("special_info"),
                        ),
                    )
                }
            },
        })
    }
}

Note: This is edited for readability. The generated code doesn't assume traits such as Into are in-scope, and uses full paths to access them.

Get Started

It's as simple as three steps:

Add derive_builder to your Cargo.toml either manually or with cargo-edit:

cargo add derive_builder

Add use derive_builder::Builder;
Annotate your struct with #[derive(Builder)]

Usage and Features

Chaining: The setter calls can be chained, because they consume and return &mut self by default.
Builder patterns: You can opt into other builder patterns by preceding your struct (or field) with #[builder(pattern = "owned")] or #[builder(pattern = "immutable")].
Extensible: You can still define your own implementations for the builder struct and define additional methods. Just make sure to name them differently than the setter and build methods.
Documentation and attributes: Setter methods can be documented by simply documenting the corresponding field. Similarly #[cfg(...)] and #[allow(...)] attributes are also applied to the setter methods.
Hidden fields: You can skip setters via #[builder(setter(skip))] on each field individually.
Setter visibility: You can opt into private setter by preceding your struct with #[builder(private)].
Setter type conversions: With #[builder(setter(into))], setter methods will be generic over the input types – you can then supply every argument that implements the Into trait for the field type.
Setter strip option: With #[builder(setter(strip_option))], setter methods will take T as parameter'type for field of type Option<T>.
Collection setters: Adding #[builder(setter(each(name = "method_name")))] to fields whose types implement Default and Extend will generate a setter which adds items to the builder collection for that field. It's possible for these setters to be generic over the Into<T> trait too, like so: #[builder(setter(each(name = "foo", into)))].
Builder field visibility: You can use #[builder(field(private))] or ..(public), to set field visibility of your builder.
Generic structs: Are also supported, but you must not use a type parameter named VALUE, if you also activate setter type conversions.
Default values: You can use #[builder(default)] to delegate to the Default implementation or any explicit value via = "..". This works both on the struct and field level.
Pre-build validation: You can use #[builder(build_fn(validate = "path::to::fn"))] to add your own validation before the target struct is generated.
Build method suppression: You can use #[builder(build_fn(skip))] to disable auto-implementation of the build method and provide your own.
Custom build method error types: You can use #[builder(build_fn(error = "path::to::Error"))] to have your builder return an error type of your choosing. By default, the macro will emit an error type alongside the builder.
Builder derivations: You can use #[builder(derive(Trait1, Trait2, ...))] to have the builder derive additonal traits. All builders derive Default and Clone, so you should not declare those in this attribute.
Pass-through attributes: Use #[builder_struct_attr(...)], #[builder_impl_attr(...)], #[builder_field_attr(...)], and #[builder_setter_attr(...)] to declare attributes that will be added to the relevant part of the generated builder.
no_std support: Just add #[builder(no_std)] to your struct, use feature alloc, and add extern crate alloc to your crate.
No alloc no_std support: Do not use alloc feature and then either add #[builder(no_std, build_fn(error(validation_error = false)))] or #[builder(no_std, build_fn(error = "path::to::Error"))] to your struct.
Renaming and re-export support: Use #[builder(crate = "...")] to set the root for derive_builder. This is useful if you want to rename derive_builder in Cargo.toml or if your crate is re-exporting derive_builder::Builder and needs the generated code to not directly reference the derive_builder crate.

For more information and examples please take a look at our documentation.

Gotchas

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

Documentation

Detailed explaination of all features and tips for troubleshooting. You'll also find a discussion of different builder patterns.

Changelog

Yes, we keep a changelog.

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.

colin-kiegel / rust-derive-builder

readme