Buildstructor

https://docs.rs/buildstructor/
Admin
Buildstructor is a Rust procedural macro crate that derives typesafe builders from constructors and...
Tokens:6,022
Snippets:58
Trust Score:9.1
Update:1 day ago
Show doc for...
Tokens:
Raw
### Builder entry and exit configuration examples

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows how to configure builder entry and exit points. The entry defaults to 'builder' for 'new', '<name>_builder' for '<name>_new', and must be specified otherwise. The exit defaults to 'build'. The example demonstrates three methods with different configurations.

```rust
struct MyStruct {
    simple: usize
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new(simple: usize) -> MyStruct {
        Self { simple }
    }
    #[builder]
    fn try_new(simple: usize) -> MyStruct {
        Self { simple }
    }
    #[builder(entry = "random", exit = "create")]
    fn do_random(simple: usize) -> MyStruct {
        Self { simple }
    }
}

fn main() {
    let mine = MyStruct::builder().simple(2).build();
    assert_eq!(mine.simple, 2);

    let mine = MyStruct::try_builder().simple(2).build();
    assert_eq!(mine.simple, 2);

    let mine = MyStruct::random().simple(2).create();
    assert_eq!(mine.simple, 2);
}
```

--------------------------------

### Example: Derive Builder and use generated builder

Source: https://docs.rs/buildstructor/latest/buildstructor/derive.Builder.html

Shows the full workflow: import the `Builder` macro, derive it on a struct, and use the generated `builder()` method to set fields and build the instance. The example asserts the built value equals the provided field.

```rust
use buildstructor::Builder;

#[derive(Builder)]
struct MyStruct {
    sum: usize,
}

  let mine = MyStruct::builder().sum(3).build();
  assert_eq!(mine.sum, 3);
```

--------------------------------

### buildstructor macro usage example

Source: https://docs.rs/buildstructor/latest/buildstructor/attr.buildstructor.html

Shows how to use the buildstructor macro. Import the macro, annotate an impl block with #[buildstructor], and annotate a constructor with #[builder]. The generated builder is then used to construct the struct.

```rust
use buildstructor::buildstructor;

struct MyStruct {
    sum: usize,
}

#[buildstructor]
impl MyStruct {
    #[builder]
    fn new(a: usize, b: usize) -> MyStruct {
        Self { sum: a + b }
    }
}
  let mine = MyStruct::builder().a(2).b(3).build();
  assert_eq!(mine.sum, 5);
```

--------------------------------

### Builder derive macro usage example

Source: https://docs.rs/buildstructor/latest/src/buildstructor/lib.rs.html

Shows how to use the `#[derive(Builder)]` macro on a struct. The generated builder is used with `.builder().sum(3).build()`.

```rust
use buildstructor::Builder;

#[derive(Builder)]
struct MyStruct {
    sum: usize,
}

# #[allow(clippy::needless_doctest_main)]
# fn main() {
  let mine = MyStruct::builder().sum(3).build();
  assert_eq!(mine.sum, 3);
# }
```

--------------------------------

### Builder on methods with self, &self, and &mut self

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows how to generate builders on methods taking self, &self, and &mut self. The entry method name is required and cannot be defaulted; exit defaults to 'call'. The example uses entry names 'query', 'query_ref', and 'query_ref_mut' with exits 'call', 'stop', and 'go' respectively.

```rust
use buildstructor::buildstructor;

#[derive(Default)]
pub struct MyStruct;

#[buildstructor]
impl MyStruct {
    #[builder(entry = "query")]
    fn do_query(self, _simple: String) -> bool {
        true
    }

    #[builder(entry = "query_ref", exit = "stop")]
    fn do_query_ref(&self, _simple: String) -> bool {
        true
    }

    #[builder(entry = "query_ref_mut", exit = "go")]
    fn do_query_ref_mut(&mut self, _simple: String) -> bool {
        true
    }
}

fn main() {
    MyStruct::default().query().simple("3".to_string()).call(); // self

    let mine = MyStruct::default();
    mine.query_ref().simple("3".to_string()).stop(); // &self

    let mut mine = MyStruct::default();
    mine.query_ref_mut().simple("3".to_string()).go(); // &mut self
}
```

--------------------------------

### Add buildstructor dependency to Cargo.toml

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Adds the buildstructor crate as a dependency in Cargo.toml. Use the version wildcard to get the latest version.

```toml
[dependencies]
buildstructor = "*"
```

--------------------------------

### buildstructor attribute macro usage example

Source: https://docs.rs/buildstructor/latest/src/buildstructor/lib.rs.html

Shows how to use the `#[buildstructor]` attribute macro on an impl block containing a `new` function. The generated builder is used with `.builder().a(2).b(3).build()`.

```rust
use buildstructor::buildstructor;

struct MyStruct {
    sum: usize,
}

#[buildstructor]
impl MyStruct {
    #[builder]
    fn new(a: usize, b: usize) -> MyStruct {
        Self { sum: a + b }
    }
}
# #[allow(clippy::needless_doctest_main)]
# fn main() {
  let mine = MyStruct::builder().a(2).b(3).build();
  assert_eq!(mine.sum, 5);
# }
```

--------------------------------

### Annotate impl and methods with #[buildstructor] and #[builder]

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows the primary usage: annotate an impl block with #[buildstructor::buildstructor] and methods with #[builder]. The example includes a constructor and a method with custom entry/exit names and visibility. The generated builder is used in main to build and mutate the struct.

```rust
pub struct MyStruct {
    sum: usize,
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new(a: usize, b: usize) -> MyStruct {
        Self { sum: a + b }
    }
    
    #[builder(entry = "more", exit = "add", visibility="pub")]
    fn add_more(&mut self, c: usize, d: usize, e: Option<usize>) {
        self.sum += c + d + e.unwrap_or(3);
    }
}

fn main() {
    let mut mine = MyStruct::builder().a(2).b(3).build();
    assert_eq!(mine.sum, 5);
    
    mine.more().c(1).d(2).add();
    assert_eq!(mine.sum, 11);
}
```

--------------------------------

### Async builder with tokio

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows how to create an async builder by making the constructor async. The builder's build() method returns a future that must be awaited.

```rust
struct MyStruct {
    param: usize
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    async fn new(param: usize) -> MyStruct {
        Self { param }
    }
}

#[tokio::main]
async fn main() {
    let mine = MyStruct::builder().param(2).build().await;
    assert_eq!(mine.param, 2);
}
```

--------------------------------

### Async builder

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

To create an async builder, make your constructor `async`. The builder's `build` method will then return a future that must be awaited.

```APIDOC
## Async builder

### Description
To create an `async` builder just make your constructor `async`.

### Example
```rust
struct MyStruct {
    param: usize
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    async fn new(param: usize) -> MyStruct {
        Self { param }
    }
}

#[tokio::main]
async fn main() {
    let mine = MyStruct::builder().param(2).build().await;
    assert_eq!(mine.param, 2);
}
```
```

--------------------------------

### Fallible builder with Result

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows how to create a fallible builder by making the constructor return a Result. The build() method returns a Result that must be unwrapped or handled.

```rust
use std::error::Error;
struct MyStruct {
    param: usize
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new(param: usize) -> Result<MyStruct, Box<dyn Error>> {
        Ok(Self { param })
    }
}

fn main() {
    let mine = MyStruct::builder().param(2).build().unwrap();
    assert_eq!(mine.param, 2);
}
```

--------------------------------

### Builder on methods (self, &self, &mut self)

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Builders can be generated on methods that take self, &self, and &mut self as a parameter. The entry point must be specified and cannot be defaulted, while the exit defaults to 'call'.

```APIDOC
## Builder on methods (self, &self, &mut self)

### Description
Builders can be generated on methods that take `self`, `&self`, and `&mut self` as a parameter. The `entry` configuration must be specified, and `exit` defaults to `call`.

### Usage
Annotate methods with `#[builder(entry = "...", exit = "...")]` inside an `impl` block annotated with `#[buildstructor]`.

### Example
```rust
use buildstructor::buildstructor;

#[derive(Default)]
pub struct MyStruct;

#[buildstructor]
impl MyStruct {
    #[builder(entry = "query")]
    fn do_query(self, _simple: String) -> bool {
        true
    }

    #[builder(entry = "query_ref", exit = "stop")]
    fn do_query_ref(&self, _simple: String) -> bool {
        true
    }

    #[builder(entry = "query_ref_mut", exit = "go")]
    fn do_query_ref_mut(&mut self, _simple: String) -> bool {
        true
    }
}

fn main() {
    MyStruct::default().query().simple("3".to_string()).call(); // self

    let mine = MyStruct::default();
    mine.query_ref().simple("3".to_string()).stop(); // &self

    let mut mine = MyStruct::default();
    mine.query_ref_mut().simple("3".to_string()).go(); // &mut self
}
```
```

--------------------------------

### Builder for struct with Vec field

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows how Buildstructor generates additional methods to build a Vec field one element at a time. The builder provides singular methods (e.g., .address()) and a plural method (.addresses()) to set the entire collection.

```rust
struct MyStruct {
    addresses: Vec<String>
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new(addresses: Vec<String>) -> MyStruct {
        Self { addresses }
    }
}

fn main() {
    let mine = MyStruct::builder()
        .address("Amsterdam".to_string())
        .address("Fakenham")
        .addresses(vec!["Norwich".to_string(), "Bristol".to_string()])
        .build();
    assert_eq!(mine.addresses, vec!["Amsterdam".to_string(), 
                                    "Fakenham".to_string(), 
                                    "Norwich".to_string(), 
                                    "Bristol".to_string()]);
}
```

--------------------------------

### Builder with pub visibility override

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Demonstrates using the visibility attribute to make the builder public even when the constructor method is private. This allows the builder to be the sole entry point for creating the struct.

```rust
use std::error::Error;

pub mod foo {
    pub struct MyStruct {
        pub param: usize
    }
    
    #[buildstructor::buildstructor]
    impl MyStruct {
        #[builder(visibility = "pub")]
        fn new(param: usize) -> MyStruct {
            Self { param }
        }
    }
}

fn main() {
    let mine = foo::MyStruct::builder().param(2).build();
    assert_eq!(mine.param, 2);
}
```

--------------------------------

### Optional field builder with defaulting in constructor

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows that Option fields become optional in the builder. The constructor handles defaulting (unwrap_or(3)). If a user forgets to set an Option or collection field, a compile error is generated.

```rust
struct MyStruct {
    param: usize
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new(param: Option<usize>) -> MyStruct {
        Self { param: param.unwrap_or(3) }
    }
}

fn main() {
    let mine = MyStruct::builder().param(2).build();
    assert_eq!(mine.param, 2);
    let mine = MyStruct::builder().and_param(Some(2)).build();
    assert_eq!(mine.param, 2);
    let mine = MyStruct::builder().build();
    assert_eq!(mine.param, 3);
}
```

--------------------------------

### Into field (simple types)

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Types automatically have into conversion if the type is not a scalar, has no generic parameters, or is a generic parameter from the impl or constructor method. This is useful for Strings and other types where you want to overload the singular build method.

```APIDOC
## Into field (simple types)

### Description
Types automatically have into conversion if:
- the type is not a scalar.
- the type has no generic parameters. (this may be relaxed later)
- the type is a generic parameter from the impl or constructor method.

This is useful for Strings, but also other types where you want to overload the singular build method. Create an enum that derives `From` for all the types you want to support and then use this type in your constructor.

### Example
```rust
struct MyStruct {
    param: String   
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new<T: Into<String>>(param: T) -> MyStruct {
        Self { param: param.into() }
    }
}

fn main() {
    let mine = MyStruct::builder().param("Hi").build();
    assert_eq!(mine.param, "Hi");
}
```
```

--------------------------------

### Fallible builder

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

To create a fallible builder, make your constructor fallible using `Result`. The builder's `build` method will then return a `Result`.

```APIDOC
## Fallible builder

### Description
To create a fallible builder just make your constructor fallible using `Result`.

### Example
```rust
use std::error::Error;
struct MyStruct {
    param: usize
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new(param: usize) -> Result<MyStruct, Box<dyn Error>> {
        Ok(Self { param })
    }
}

fn main() {
    let mine = MyStruct::builder().param(2).build().unwrap();
    assert_eq!(mine.param, 2);
}
```
```

--------------------------------

### Into field with generic type parameter

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows using a generic type parameter with Into<String> to allow passing any type that converts into String. This is useful for overloading the singular build method, but has the downside of not supporting optional fields.

```rust
struct MyStruct {
    param: String   
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new<T: Into<String>>(param: T) -> MyStruct {
        Self { param: param.into() }
    }
}

fn main() {
    let mine = MyStruct::builder().param("Hi").build();
    assert_eq!(mine.param, "Hi");
}
```

--------------------------------

### Optional Field

Source: https://docs.rs/buildstructor/latest/buildstructor/

Fields that are `Option` become optional in the builder. Defaulting should be done in the constructor.

```APIDOC
## Optional Field

### Description
Fields of type `Option` are optional in the builder. If not set, the constructor receives `None` and can apply a default. If a field is `Option` or a collection and not set, a compile error is generated.

### Example
```rust
struct MyStruct {
    param: usize
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new(param: Option<usize>) -> MyStruct {
        Self { param: param.unwrap_or(3) }
    }
}

fn main() {
    let mine = MyStruct::builder().param(2).build();
    assert_eq!(mine.param, 2);
    let mine = MyStruct::builder().and_param(Some(2)).build();
    assert_eq!(mine.param, 2);
    let mine = MyStruct::builder().build();
    assert_eq!(mine.param, 3);
}
```
```

--------------------------------

### Derive builder with #[derive(buildstructor::Builder)]

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Shows the derive usage: annotate a struct with #[derive(buildstructor::Builder)] to generate a default constructor and builder. The generated constructor has private visibility and the builder matches the struct's visibility.

```rust
#[derive(buildstructor::Builder)]
pub struct MyStruct {
    simple: usize,
}

fn main() {
    let mut mine = MyStruct::builder().simple(2).build();
    assert_eq!(mine.simple, 2);
}
```

--------------------------------

### Optional field

Source: https://docs.rs/buildstructor/latest/buildstructor/index.html

Fields that are `Option` will also be optional in the builder. Defaulting should be done in the constructor. If an optional field is not set, a compile error is generated.

```APIDOC
## Optional field

### Description
Fields that are `Option` will also be optional in the builder. You should do defaulting in your constructor. If a field is an `Option` or collection and the user forgets to set it, a compile error will be generated.

### Example
```rust
struct MyStruct {
    param: usize
}

#[buildstructor::buildstructor]
impl MyStruct {
    #[builder]
    fn new(param: Option<usize>) -> MyStruct {
        Self { param: param.unwrap_or(3) }
    }
}

fn main() {
    let mine = MyStruct::builder().param(2).build();
    assert_eq!(mine.param, 2);
    let mine = MyStruct::builder().and_param(Some(2)).build();
    assert_eq!(mine.param, 2);
    let mine = MyStruct::builder().build();
    assert_eq!(mine.param, 3);
}
```
```

--------------------------------

### Deprecated #[builder] attribute macro usage

Source: https://docs.rs/buildstructor/latest/buildstructor/attr.builder.html

Shows the deprecated #[builder] attribute macro. Deprecated since 0.2.0; migrate to #[buildstructor::buildstructor] and annotate individual methods with #[builder].

```rust
#[builder]
```

--------------------------------

### Derive Builder macro attribute

Source: https://docs.rs/buildstructor/latest/buildstructor/derive.Builder.html

The `#[derive(Builder)]` attribute is applied to a struct to automatically generate a builder and constructor. This is the core usage of the buildstructor crate.

```rust
#[derive(Builder)]
```
Tokens:
Raw