[−][src]Derive Macro typed_builder::TypedBuilder

#[derive(TypedBuilder)]
{
    // Attributes available to this derive:
    #[builder]
}

TypedBuilder is not a real type - deriving it will generate a ::builder() method on your struct that will return a compile-time checked builder. Set the fields using setters with the same name as the struct's fields that accept Into types for the type of the field, and call .build() when you are done to create your object.

Trying to set the same fields twice will generate a compile-time error. Trying to build without setting one of the fields will also generate a compile-time error - unless that field is marked as #[builder(default)], in which case the ::default() value of it's type will be picked. If you want to set a different default, use #[builder(default=...)].

Examples

#[macro_use]
extern crate typed_builder;

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

    // #[default] without parameter - use the type's default
    // #[builder(setter(strip_option))] - wrap the setter argument with `Some(...)`
    #[builder(default, setter(strip_option))]
    y: Option<i32>,

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

fn main() {
    assert!(
        Foo::builder().x(1).y(2).z(3).build()
        == Foo { x: 1, y: Some(2), z: 3, });

    // Change the order of construction:
    assert!(
        Foo::builder().z(1).x(2).y(3).build()
        == Foo { x: 2, y: Some(3), z: 1, });

    // Optional fields are optional:
    assert!(
        Foo::builder().x(1).build()
        == Foo { x: 1, y: None, z: 20, });

    // This will not compile - because we did not set x:
    // Foo::builder().build();

    // This will not compile - because we set y twice:
    // Foo::builder().x(1).y(2).y(3);
}

Customisation with attributes

In addition to putting #[derive(TypedBuilder)] on a type, you can specify a #[builder(…)] attribute on the type, and on any fields in it.

On the type, the following values are permitted:

name = FooBuilder: customise the name of the builder type. By default, the builder type will use the type’s name plus “Builder”, e.g. FooBuilder for type Foo. (Note this is name = FooBuilder and not name = "FooBuilder".)
doc: enable documentation of the builder type. By default, the builder type is given #[doc(hidden)], so that the builder() method will show FooBuilder as its return type, but it won’t be a link. If you turn this on, the builder type and its build method will get sane defaults. The field methods on the builder will be undocumented by default.
builder_method_doc = "…" replaces the default documentation that will be generated for the builder() method of the type for which the builder is being generated.
builder_type_doc = "…" replaces the default documentation that will be generated for the builder type. Setting this implies doc.
build_method_doc = "…" replaces the default documentation that will be generated for the build() method of the builder type. Setting this implies doc.

On each field, the following values are permitted:

default: make the field optional, defaulting to Default::default(). This requires that the field type implement Default. Mutually exclusive with any other form of default.
default = …: make the field optional, defaulting to the expression ….
setter(...): settings for the field setters. The following values are permitted inside:
- doc = "…": sets the documentation for the field’s setter on the builder type. This will be of no value unless you enable docs for the builder type with #[builder(doc)] or similar on the type.
- skip: do not define a method on the builder for this field. This requires that a default be set.
- into: automatically convert the argument of the setter method to the type of the field. Note that this conversion interferes with Rust's type inference and integer literal detection, so this may reduce ergonomics if the field type is generic or an unsigned integer.
- strip_option: for Option<...> fields only, this makes the setter wrap its argument with Some(...), relieving the caller from having to do this. Note that with this setting on one cannot set the field to None with the setter - so the only way to get it to be None is by using #[builder(default)] and not calling the field's setter.