typed-builder 0.3.0

Compile-time type-checked builder derive
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

[![Build Status](https://api.travis-ci.org/idanarye/rust-typed-builder.svg?branch=master)](https://travis-ci.org/idanarye/rust-typed-builder)
[![Latest Version](https://img.shields.io/crates/v/typed-builder.svg)](https://crates.io/crates/typed-builder)
[![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://idanarye.github.io/rust-typed-builder/)

# Rust Typed Builder

Creates a compile-time verified builder:

```rust
#[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:
```rust
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]`):
```rust
Foo::builder().x(1).build()
```

But you can't omit non-optional arguments - or it won't compile:
```rust
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](https://crates.io/crates/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](https://crates.io/crates/derive_builder) - does all the checks in runtime, returning a `Result` you need to unwrap.
* [safe-builder-derive](https://crates.io/crates/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.