rsb_derive 0.5.1

An opinionated macro implementation for Rust struct builder pattern with compile-time validation
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

[![Cargo](https://img.shields.io/crates/v/rsb_derive.svg)](https://crates.io/crates/rsb_derive)

# Opinionated and Option-based builder pattern macro for Rust

## Motivation
A derive macros to support a builder pattern for Rust:
- Everything except `Option<>` fields and explicitly defined `default` attribute in structs are required, so you 
don't need any additional attributes to indicate it, and the presence of required params 
is checked at the compile time (not at the runtime).
- To create new struct instances there is `::new` and an auxiliary init struct definition 
with only required fields (to compensate the Rust's named params inability). 

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
rsb_derive = "0.4"
```

The macros generates the following functions and instances for your structures:
- `with/without/opt_<field_name>` : immutable setters for fields (`opt` is an additional setter for `Option<>` input argument)
- `<field_name>/reset/mopt_<field_name>` : mutable setters for fields (`mopt` is an additional setter for `Option<>` input argument)
- `new` : factory method with required fields as arguments
- `From<>` instance from an an auxiliary init struct definition with only required fields. 
The init structure generated as `<YourStructureName>Init`. So, you can use `from(...)` or `into()` 
functions from it.

### Marking the derive attribute on your structures:

```rust
// Import it
use rsb_derive::Builder;

// And use it on your structs
#[derive(Clone,Builder)]
struct MyStructure {
    pub req_field1: String,
    pub req_field2: i32,
    pub opt_field1: Option<String>,
    pub opt_field2: Option<i32>
}
```

### Using the builder pattern on your structures 

```rust
// Creating instances

// Option #1:
let s1 : MyStructure = MyStructure::new(
            "hey".into(),
            0);

// Option #2 (named arguments emulation):
let s2 : MyStructure = MyStructureInit {
        req_field1 : "hey".into(),
        req_field2 : 0
    }.into();


// Working with instances
let updated = 
    s1.clone()
      .with_opt_field1("hey".into()) // for Option<> fields you specify a bare argument
      .without_opt_field2() // you can reset Option<> if you need it
      .opt_opt_field1(Some(("hey".into())) // you can use opt_<field> to provide Option<> inputs
      .with_req_field2(10); // you can update required params as well

// All together example

let s1 : MyStructure =
    MyStructure::from(
        MyStructureInit {
            req_field1 : "hey".into(),
            req_field2 : 0
        }
    )
        .with_opt_field1("hey".into())
        .with_opt_field2(10);

// Mutable example (in case you really need it)
let mut s1 : MyStructure =
    MyStructure::from(
        MyStructureInit {
            req_field1 : "hey".into(),
            req_field2 : 0
        }
    );

s1
    .opt_field1("hey".into()) // no prefix with for mutable setter    
    .opt_field2(10)
    .field2(15)
    .reset_opt_field2(); // mutable reset function for optional fields

    


``` 

### Defaults

While you're free to use the Rust `Default` on your own structs or on auxiliary init structs 
this lib intentionally ignores this approach and gives you an auxiliary `default` attribute 
to manage this like: 

```rust
#[derive(Debug, Clone, PartialEq, Builder)]
struct StructWithDefault {
    pub req_field1: String,
    #[default="10"]
    pub req_field2: i32, // default here make this field behave like optional

    pub opt_field1: Option<String>,
    #[default="Some(11)"]
    pub opt_field2: Option<i32> // default works also on optional fields
}

let my_struct : StructWithDefault = StructWithDefault::from(
    StructWithDefaultInit {
        req_field1 : "test".into()
    }
);
```


## Licence
Apache Software License (ASL)

## Author
Abdulla Abdurakhmanov