LoremBuilder

Derive a builder for a struct

LoremBuilder(编辑工具) V1.2.1 Mac版. LogMaster(远程日志查看器) V1.0 Mac版. ProtoPie(交互原型设计软件) V3.11.1 Mac版. Cache Monitor(SQL开发工具) V2.80 Mac版.
LoremBuilder The filler text generator for OSX LoremBuilder is an ultra-lightweight, advanced placeholder text editor specifically created to help developers and designers in their daily tasks. Lorem Ipsum Generator: Bacon, Hipster, Hip Hop.

I am sorry but I am not on Twitter, Facebook, LinkedIn, Pinterest, Tumblr or Instagram. I don't even have a blog. In my spare time, instead of posting, liking, retweeting or sharing pictures of my lunch, I keep myself busy reading geek stuff, travelling, hugging friends, riding my motorcycle, playing with my dog, deepening my knowledge of programming languages, sleeping, watching movies.

This crate implements the builder pattern for you.Just apply #[derive(Builder)] to a struct Foo, and it will derive an additionalstruct FooBuilder with setter-methods for all fields and a build-method— the way you want it.

Add derive_builder as a dependency to you Cargo.toml.

What you write

What you get

By default all generated setter-methods take and return &mut self(aka non-conusuming builder pattern). Accordingly, the build method also takes areference by default.

You can easily opt into different patterns and control many other aspects.

The build method returns Result<T, String>, where T is the struct you started with.It returns Err if you didn't initialize all fields and no default values wereprovided.

Let's look again at the example above. You can now build structs like this:

Ok, chaining method calls is nice, but what if ipsum(42) should only happen if geek = true?

So let's make this call conditional

Now it comes in handy that our setter methods take and return mutable references. Otherwisewe would need to write something more clumsy like builder = builder.ipsum(42) to reassignthe return value each time we have to call a setter conditionally.

Setters with mutable references are therefore a convenient default for the builderpattern in Rust.

But this is a free world and the choice is still yours!

Owned, aka Consuming

Precede your struct (or field) with #[builder(pattern = 'owned')] to opt into this pattern.Builders generated with this pattern do not automatically derive Clone, which allows buildersto be generated for structs with fields that do not derive Clone.

Setters take and return self.
PRO: Setter calls and final build method can be chained.
CON: If you don't chain your calls, you have to create a reference to each return value,e.g. builder = builder.ipsum(42).

Mutable, aka Non-Consuming (recommended)

This pattern is recommended and active by default if you don't specify anything else.You can precede your struct (or field) with #[builder(pattern = 'mutable')]to make this choice explicit.

Setters take and return &mut self.
PRO: Setter calls and final build method can be chained.
CON: The build method must clone or copy data to create something owned out of amutable reference. Otherwise it could not be used in a chain. (*)

Immutable

Precede your struct (or field) with #[builder(pattern = 'immutable')] to opt into this pattern.

Setters take and return &self.
PRO: Setter calls and final build method can be chained.
CON: If you don't chain your calls, you have to create a reference to each return value,e.g. builder = builder.ipsum(42).
CON: The build method and each setter must clone or copy data to create something ownedout of a reference. (*)

(*) Performance Considerations

Luckily Rust is clever enough to optimize these clone-calls away in release buildsfor your every-day use cases. Thats quite a safe bet - we checked this for you. ;-)Switching to consuming signatures (=self) is unlikely to give you any performancegain, but very likely to restrict your API for non-chained use cases.

Hidden Fields

You can hide fields by skipping their setters on the builder struct.

Opt-out — skip setters via #[builder(setter(skip))] on individual fields.
Opt-in — set #[builder(setter(skip))] on the whole structand enable individual setters via #[builder(setter)].

The types of skipped fields must implement Default.

Alternatively, you can use the more verbose form:

#[builder(setter(skip = 'true'))]
#[builder(setter(skip = 'false'))]

Setter Visibility

Setters are public by default. You can precede your struct (or field) with #[builder(public)]to make this explicit.

Otherwise precede your struct (or field) with #[builder(private)] to opt into privatesetters.

Setter Name/Prefix

Setter methods are named after their corresponding field by default.

You can customize the setter name via #[builder(setter(name = 'foo')).
Alternatively you can set a prefix via #[builder(setter(prefix = 'xyz')), which will changethe method name to xyz_foo if the field is named foo. Note that an underscore isinserted, since Rust favors snake case here.

Prefixes can also be defined on the struct level, but renames only work on fields. Renamestake precedence over prefix definitions.

Generic Setters

You can make each setter generic over the Into-trait. It's as simple as adding#[builder(setter(into))] to either a field or the whole struct.

Setters for Option

You can avoid to user to wrap value into Some(...) for field of type Option<T>. It's as simple as adding#[builder(setter(strip_option))] to either a field or the whole struct.

If you want to set the value to None when unset, then enable default on this field (or do not use strip_option).

Limitation: only the Option type name is supported, not type alias nor std::option::Option.

Fallible Setters

Alongside the normal setter methods, you can expose fallible setters which are generic overthe TryInto trait. TryInto is a not-yet-stable trait(see rust-lang issue #33417) similar toInto with the key distinction that the conversion can fail, and therefore produces aResult.

You can only declare the try_setter attribute today if you're targeting nightly, and you haveto add #![feature(try_from)] to your crate to use it.

Default Values

You can define default values for each field via annotation by #[builder(default = '...')],where ... stands for any Rust expression and must be string-escaped, e.g.

#[builder(default = '42')]
#[builder(default)] delegates to the Default trait of the base type.

The expression will be evaluated with each call to build.

Tips on Defaults

The #[builder(default)] annotation can be used on the struct level, too. Overrides arestill possible.
Delegate to a private helper method on FooBuilder for anything fancy. This wayyou will get much better error diagnostics from the rust compiler and it will be muchmore readable for other human beings. :-)

You can even reference other fields, but you have to remember that the builder structwill wrap every type in an Option (as illustrated earlier).

Generic Structs

Build Method Customization

You can rename or suppress the auto-generated build method, leaving you free to implementyour own version. Suppression is done using #[builder(build_fn(skip))] at the struct level,and renaming is done with #[builder(build_fn(name = 'YOUR_NAME'))].

Pre-Build Validation

If you're using the provided build method, you can declare#[builder(build_fn(validate = 'path::to::fn'))] to specify a validator function which getsaccess to the builder before construction. The path does not need to be fully-qualified, andwill consider use statements made at module level. It must be accessible from the scopewhere the target struct is declared.

The provided function must have the signature (&FooBuilder) -> Result<_, String>;the Ok variant is not used by the build method.

Note:

Default values are applied after validation, and will therefore not be validated!

Additional Trait Derivations

You can derive additional traits on the builder, including traits defined by other crates:

Attributes declared for those traits are not forwarded to the fields on the builder.

Documentation Comments and Attributes

#[derive(Builder)] copies doc comments and attributes (#[...]) from your fieldsto the according builder fields and setter-methods, if it is one of the following:

/// ...
#[doc = ...]
#[cfg(...)]
#[allow(...)]

The whitelisting minimizes interference with other custom attributes likethose used by Serde, Diesel, or others.

You can activate support for #![no_std] by adding #[builder(no_std)] to your structand #![feature(alloc)] extern crate alloc to your crate.

The latter requires the nightly toolchain.

Gotchas

Tuple structs and unit structs are not supported as they have no fieldnames.
Generic setters introduce a type parameter VALUE: Into<_>. Therefore you can't useVALUE as a type parameter on a generic struct in combination with generic setters.
The try_setter attribute and owned builder pattern are not compatible in practice;an error during building will consume the builder, making it impossible to continueconstruction.
When re-exporting the underlying struct under a different name, theauto-generated documentation will not match.
If derive_builder depends on your crate, and vice versa, then a cyclicdependency would occur. To break it you could try to depend on thederive_builder_core crate instead.

Debugging Info

If you experience any problems during compilation, you can enable additional debug output intwo steps:

Add features = ['logging'] to the derive_builder dependency in Cargo.toml.
Set this environment variable before calling cargo or rustc RUST_LOG=derive_builder=trace.

Example: env RUST_LOG=derive_builder=trace cargo test.

Report Issues and Ideas

If possible please try to provide the debugging info if you experience unexpectedcompilation errors (see above).

Derive a builder for a struct

Add derive_builder as a dependency to you Cargo.toml.

What you write

What you get

By default all generated setter-methods take and return &mut self(aka non-conusuming builder pattern). Accordingly, the build method also takes areference by default.

You can easily opt into different patterns and control many other aspects.

The build method returns Result<T, String>, where T is the struct you started with.It returns Err if you didn't initialize all fields and no default values wereprovided.

Let's look again at the example above. You can now build structs like this:

Ok, chaining method calls is nice, but what if ipsum(42) should only happen if geek = true?

So let's make this call conditional

Setters with mutable references are therefore a convenient default for the builderpattern in Rust.

But this is a free world and the choice is still yours!

Owned, aka Consuming

Setters take and return self.
PRO: Setter calls and final build method can be chained.
CON: If you don't chain your calls, you have to create a reference to each return value,e.g. builder = builder.ipsum(42).

Mutable, aka Non-Consuming (recommended)

This pattern is recommended and active by default if you don't specify anything else.You can precede your struct (or field) with #[builder(pattern = 'mutable')]to make this choice explicit.

Setters take and return &mut self.
PRO: Setter calls and final build method can be chained.
CON: The build method must clone or copy data to create something owned out of amutable reference. Otherwise it could not be used in a chain. (*)

Immutable

Precede your struct (or field) with #[builder(pattern = 'immutable')] to opt into this pattern.

Setters take and return &self.
PRO: Setter calls and final build method can be chained.
CON: If you don't chain your calls, you have to create a reference to each return value,e.g. builder = builder.ipsum(42).
CON: The build method and each setter must clone or copy data to create something ownedout of a reference. (*)

(*) Performance Considerations

Hidden Fields

You can hide fields by skipping their setters on the builder struct.

Opt-out — skip setters via #[builder(setter(skip))] on individual fields.
Opt-in — set #[builder(setter(skip))] on the whole structand enable individual setters via #[builder(setter)].

The types of skipped fields must implement Default.

Alternatively, you can use the more verbose form:

#[builder(setter(skip = 'true'))]
#[builder(setter(skip = 'false'))]

Setter Visibility

Setters are public by default. You can precede your struct (or field) with #[builder(public)]to make this explicit.

Otherwise precede your struct (or field) with #[builder(private)] to opt into privatesetters.

Setter Name/Prefix

Setter methods are named after their corresponding field by default.

You can customize the setter name via #[builder(setter(name = 'foo')).
Alternatively you can set a prefix via #[builder(setter(prefix = 'xyz')), which will changethe method name to xyz_foo if the field is named foo. Note that an underscore isinserted, since Rust favors snake case here.

Prefixes can also be defined on the struct level, but renames only work on fields. Renamestake precedence over prefix definitions.

Generic Setters

You can make each setter generic over the Into-trait. It's as simple as adding#[builder(setter(into))] to either a field or the whole struct.

Setters for Option

You can avoid to user to wrap value into Some(...) for field of type Option<T>. It's as simple as adding#[builder(setter(strip_option))] to either a field or the whole struct.

If you want to set the value to None when unset, then enable default on this field (or do not use strip_option).

Limitation: only the Option type name is supported, not type alias nor std::option::Option.

Fallible Setters

You can only declare the try_setter attribute today if you're targeting nightly, and you haveto add #![feature(try_from)] to your crate to use it.

Default Values

You can define default values for each field via annotation by #[builder(default = '...')],where ... stands for any Rust expression and must be string-escaped, e.g.

#[builder(default = '42')]
#[builder(default)] delegates to the Default trait of the base type.

The expression will be evaluated with each call to build.

Tips on Defaults

The #[builder(default)] annotation can be used on the struct level, too. Overrides arestill possible.
Delegate to a private helper method on FooBuilder for anything fancy. This wayyou will get much better error diagnostics from the rust compiler and it will be muchmore readable for other human beings. :-)

Lore Builder

You can even reference other fields, but you have to remember that the builder structwill wrap every type in an Option (as illustrated earlier).

Generic Structs

Build Method Customization

Pre-Build Validation

The provided function must have the signature (&FooBuilder) -> Result<_, String>;the Ok variant is not used by the build method.

Note:

Default values are applied after validation, and will therefore not be validated!

Additional Trait Derivations

You can derive additional traits on the builder, including traits defined by other crates:

Attributes declared for those traits are not forwarded to the fields on the builder.

Documentation Comments and Attributes

#[derive(Builder)] copies doc comments and attributes (#[...]) from your fieldsto the according builder fields and setter-methods, if it is one of the following:

/// ...
#[doc = ...]
#[cfg(...)]
#[allow(...)]

Lorem Ipsum Builder

The whitelisting minimizes interference with other custom attributes likethose used by Serde, Diesel, or others.

You can activate support for #![no_std] by adding #[builder(no_std)] to your structand #![feature(alloc)] extern crate alloc to your crate.

The latter requires the nightly toolchain.

Gotchas

Tuple structs and unit structs are not supported as they have no fieldnames.
Generic setters introduce a type parameter VALUE: Into<_>. Therefore you can't useVALUE as a type parameter on a generic struct in combination with generic setters.
The try_setter attribute and owned builder pattern are not compatible in practice;an error during building will consume the builder, making it impossible to continueconstruction.
When re-exporting the underlying struct under a different name, theauto-generated documentation will not match.
If derive_builder depends on your crate, and vice versa, then a cyclicdependency would occur. To break it you could try to depend on thederive_builder_core crate instead.

Debugging Info

If you experience any problems during compilation, you can enable additional debug output intwo steps:

Add features = ['logging'] to the derive_builder dependency in Cargo.toml.
Set this environment variable before calling cargo or rustc RUST_LOG=derive_builder=trace.

Example: env RUST_LOG=derive_builder=trace cargo test.

Report Issues and Ideas

If possible please try to provide the debugging info if you experience unexpectedcompilation errors (see above).

Huntercontact507

What you write

What you get

Owned, aka Consuming

Mutable, aka Non-Consuming (recommended)

Immutable

(*) Performance Considerations

Hidden Fields

Setter Visibility

Setter Name/Prefix

Generic Setters

Setters for Option

Fallible Setters

Default Values

Tips on Defaults

Generic Structs

Build Method Customization

Pre-Build Validation

Additional Trait Derivations

Documentation Comments and Attributes

Gotchas

Debugging Info

Report Issues and Ideas

What you write

What you get

Owned, aka Consuming

Mutable, aka Non-Consuming (recommended)

Immutable

(*) Performance Considerations

Hidden Fields

Setter Visibility

Setter Name/Prefix

Generic Setters

Setters for Option

Fallible Setters

Default Values

Tips on Defaults

Lore Builder

Generic Structs

Build Method Customization

Pre-Build Validation

Additional Trait Derivations

Documentation Comments and Attributes

Lorem Ipsum Builder

Gotchas

Debugging Info

Report Issues and Ideas

MOST POPULAR ARTICLES