Changelog
All notable changes to this project are documented here.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
3.0.2 - 2024-11-20
Fixed
- Fix
unexpected_cfgs
lint coming from#[cfg(rust_analyzer)]
on the latest nightly (#212)
3.0.1 - 2024-11-17
Fixed
- Fix handling of lifetimes not used in fn param types (#208)
3.0.0 - 2024-11-13
See the most interesting changes described in Bon 3.0 Release blog post.
All the breaking changes are very unlikely to actually break your code that was written against the v2
version of bon
. 99% of users should be able to update without any migration.
Changed
🎉🎉 Stabilize the builder's typestate API allowing for custom builder extensions. This is the main theme of this release. This new API brings the flexibility to a whole new level 🚀 🚀 (#145)
Improve rustdoc output. See the rustoc examples and comparison in the Alternatives section (#145)
Add info that the member is required or optional.
For members with default values show the default value in the docs.
For optional members provide links to
{member}(T)
andmaybe_{member}(Option<T>)
setters.Remove
__
prefixes for generic types and lifetimes from internal symbols. Instead, the prefixes added only if the macro detects a name collision.
⚠️ Breaking. Reject unnecessary empty attributes e.g.
#[builder()]
or#[builder]
with no parameters on a member (#145)⚠️ Breaking. Reject square brackets and curly braces delimiters for
builder_type
,finish_fn
,start_fn
andon
attributes syntax. Only parentheses are accepted e.g.#[builder(finish_fn(...))]
or#[builder(on(...))]
. This no longer works:#[builder(finish_fn[...])]
or#[builder(on{...})]
(#145)⚠️ Breaking. Reject non-consecutive
on(...)
clauses. For example, the following now generates a compile error:#[builder(on(String, into), finish_fn = build, on(Vec<_>, into))]
, because there is afinish_fn = ...
betweenon(...)
clauses. (#155)⚠️ Breaking.
#[builder(derive(Clone, Debug))]
now generates impl blocks that follow the behaviour of standardClone
andDebug
derives in that it conservatively addsClone/Debug
trait bounds for all the generic types declared on the original item (struct or function). Previously no additional bounds were required onClone
andDebug
impls. See the Added section for details on the way to override these bounds with#[builder(derive(Clone/Debug(bounds(...))))]
(#145)⚠️ Breaking. The name of the builder struct generated for methods named
builder
changed fromTBuilderBuilder
to justTBuilder
making methods namedbuilder
work the same as methods namednew
. (#145)⚠️ Breaking. The type of the builder is now dependent on the order of the setters' invocation. This may only break code like the following:
rustlet builder = if condition { Foo::builder().a(1).b(2) } else { Foo::builder().b(1).a(2) }; builder.build();
This is because the types of the builders returned from the branches are the following:
FooBuilder<SetB<SetA>>
(if
branch)FooBuilder<SetA<SetB>>
(else
branch)
We believe such code should generally be very rare and even if it breaks, it's easy to fix it by reordering the setter method calls. This compromise was accepted as a design tradeoff such that the builder's type signature becomes simpler, the generated documentation becomes much less noisy, it removes an annoying special case for the builder of just one member, and it improves the type-checking performance considerably compared to the previous approach that used tuples to represent the type state. (#145)
Removed
⚠️ Breaking. Remove support for
#[bon::builder]
proc-macro attribute on top of astruct
. Use#[derive(bon::Builder)]
for that instead. This syntax has been deprecated since2.1
and it is now removed as part of a major version cleanup (#145)⚠️ Breaking. Remove
#[builder(expose_positional_fn = positional_fn_name)]
attribute. Use#[builder(start_fn = builder_fn_name)]
instead, since this attribute works additively keeping the function with positional arguments under the attribute unchanged. (#153)
Added
⚠️ Breaking. Builder macros now generate additional
mod builder_name {}
wherebuilder_name
is the snake_case version of the name of the builder struct. This new module contains the type state API of the builder. There is a low probability that this new module name may conflict with existing symbols in your scope, so this change is marked as breaking (#145)Add
#[builder(builder_type(vis = "...", doc { ... }))]
that allows overriding the visibility and docs of the builder struct (#145)Add
#[builder(finish_fn(vis = "...", doc { ... } ))]
that allows overriding the visibility and docs of the finishing function (#145)Add
#[builder(start_fn(doc { ... }))]
that allows overriding the docs of the starting function (#145)Add
#[builder(with = closure)]
syntax to customize setters with a closure. If the closure returns aResult<_, E>
the setters become fallible (#145)Add
#[builder(with = Some)]
,#[builder(with = FromIterator::from_iter)]
,#[builder(with = <_>::from_iter)]
syntax support for two well-known functions that will probably be used frequently (#157)Add
#[builder(required)]
forOption
fields to opt out from their special handling which makesbon
treat them as regular required fields. It's also available at the top-level via#[builder(on(_, required))]
(#145, #155)Add
#[builder(crate = path::to::bon)]
and#[bon(crate = path::to::bon)]
to allow overriding the path tobon
crate used in the generated code, which is useful for the cases whenbon
macros are wrapped by other macros (#153)Add
#[builder(state_mod)]
to configure the builder's type state API module name, visibility and docs (#145)🔬 Experimental. Add
#[builder(overwritable)]
and#[builder(on(..., overwritable)]
to make it possible to call setters multiple times for the same member. This attribute is available under the cargo feature"experimental-overwritable"
. The fate of this feature depends on your feedback in the tracking issue #149. Please, let us know if you have a use case for this attribute! (#145)Add
#[builder(setters)]
to fine-tune the setters names, visibility and docs (#145)Add
#[builder(derive(Clone/Debug(bounds(...))]
to allow overriding trait bounds on theClone/Debug
impl block of the builder (#145)Add inheritance of
#[allow()]
and#[expect()]
lint attributes to all generated items. This is useful to suppress any lints coming from the generated code. Although, lints coming from the generated code are generally considered defects inbon
and should be reported via a Github issue, but this provides an easy temporary workaround for the problem (#145)
Fixed
- Fix false-positive
unused_mut
lints coming from#[builder]
on a method that takesmut self
(#197) - Fix
#[cfg/cfg_attr()]
not being expanded when used on function arguments with doc comments or other attributes (#145) - Fix raw identifiers in optional/default members (#175)
Other
- Add graceful internal panic handling. If some
bon
macro panics due to an internal bug, the macro will try to generate a fallback for IDEs to still provide intellisense (#145) - Switch from
elastio.github.io/bon
to a custom domainbon-rs.com
(#158) - Add anonymous stats with
umami
for the docs website (#158)
Docs
Refactor the README.md and all pages in the Guide Book by simplifying them and removing redundancies (#170)
Add new pages to the Guide Book:
3.0.0-rc - 2024-11-09
All the breaking changes are very unlikely to actually break your code that was written against the v2
version of bon
. 99% of users should be able to update without any migration.
Changed
🎉🎉 Stabilize the builder's typestate API allowing for custom builder extensions. This is the main theme of this release. This new API brings the flexibility to a whole new level 🚀 🚀 (#145)
Improve rustdoc output. See the rustoc examples and comparison in the Alternatives section (#145)
Add info that the member is required or optional.
For members with default values show the default value in the docs.
For optional members provide links to
{member}(T)
andmaybe_{member}(Option<T>)
setters.Remove
__
prefixes for generic types and lifetimes from internal symbols. Instead, the prefixes added only if the macro detects a name collision.
⚠️ Breaking. Reject unnecessary empty attributes e.g.
#[builder()]
or#[builder]
with no parameters on a member (#145)⚠️ Breaking. Reject square brackets and curly braces delimiters for
builder_type
,finish_fn
,start_fn
andon
attributes syntax. Only parentheses are accepted e.g.#[builder(finish_fn(...))]
or#[builder(on(...))]
. This no longer works:#[builder(finish_fn[...])]
or#[builder(on{...})]
(#145)⚠️ Breaking. Reject non-consecutive
on(...)
clauses. For example, the following now generates a compile error:#[builder(on(String, into), finish_fn = build, on(Vec<_>, into))]
, because there is afinish_fn = ...
betweenon(...)
clauses. (#155)⚠️ Breaking.
#[builder(derive(Clone, Debug))]
now generates impl blocks that follow the behaviour of standardClone
andDebug
derives in that it conservatively addsClone/Debug
trait bounds for all the generic types declared on the original item (struct or function). Previously no additional bounds were required onClone
andDebug
impls. See the Added section for details on the way to override these bounds with#[builder(derive(Clone/Debug(bounds(...))))]
(#145)⚠️ Breaking. The name of the builder struct generated for methods named
builder
changed fromTBuilderBuilder
to justTBuilder
making methods namedbuilder
work the same as methods namednew
. (#145)⚠️ Breaking. The type of the builder is now dependent on the order of the setters' invocation. This may only break code like the following:
rustlet builder = if condition { Foo::builder().a(1).b(2) } else { Foo::builder().b(1).a(2) }; builder.build();
This is because the types of the builders returned from the branches are the following:
FooBuilder<SetB<SetA>>
(if
branch)FooBuilder<SetA<SetB>>
(else
branch)
We believe such code should generally be very rare and even if it breaks, it's easy to fix it by reordering the setter method calls. This compromise was accepted as a design tradeoff such that the builder's type signature becomes simpler, the generated documentation becomes much less noisy, it removes an annoying special case for the builder of just one member, and it improves the type-checking performance considerably compared to the previous approach that used tuples to represent the type state. (#145)
Removed
⚠️ Breaking. Remove support for
#[bon::builder]
proc-macro attribute on top of astruct
. Use#[derive(bon::Builder)]
for that instead. This syntax has been deprecated since2.1
and it is now removed as part of a major version cleanup (#145)⚠️ Breaking. Remove
#[builder(expose_positional_fn = positional_fn_name)]
attribute. Use#[builder(start_fn = builder_fn_name)]
instead, since this attribute works additively keeping the function with positional arguments under the attribute unchanged. (#153)
Added
⚠️ Breaking. Builder macros now generate additional
mod builder_name {}
wherebuilder_name
is the snake_case version of the name of the builder struct. This new module contains the type state API of the builder. There is a low probability that this new module name may conflict with existing symbols in your scope, so this change is marked as breaking (#145)Add
#[builder(builder_type(vis = "...", doc { ... }))]
that allows overriding the visibility and docs of the builder struct (#145)Add
#[builder(finish_fn(vis = "...", doc { ... } ))]
that allows overriding the visibility and docs of the finishing function (#145)Add
#[builder(start_fn(doc { ... }))]
that allows overriding the docs of the starting function (#145)Add
#[builder(with = closure)]
syntax to customize setters with a closure. If the closure returns aResult<_, E>
the setters become fallible (#145)Add
#[builder(with = Some)]
,#[builder(with = FromIterator::from_iter)]
,#[builder(with = <_>::from_iter)]
syntax support for two well-known functions that will probably be used frequently (#157)Add
#[builder(required)]
forOption
fields to opt out from their special handling which makesbon
treat them as regular required fields. It's also available at the top-level via#[builder(on(_, required))]
(#145, #155)Add
#[builder(crate = path::to::bon)]
and#[bon(crate = path::to::bon)]
to allow overriding the path tobon
crate used in the generated code, which is useful for the cases whenbon
macros are wrapped by other macros (#153)Add
#[builder(state_mod)]
to configure the builder's type state API module name, visibility and docs (#145)🔬 Experimental. Add
#[builder(overwritable)]
and#[builder(on(..., overwritable)]
to make it possible to call setters multiple times for the same member. This attribute is available under the cargo feature"experimental-overwritable"
. The fate of this feature depends on your feedback in the tracking issue #149. Please, let us know if you have a use case for this attribute! (#145)Add
#[builder(setters)]
to fine-tune the setters names, visibility and docs (#145)Add
#[builder(derive(Clone/Debug(bounds(...))]
to allow overriding trait bounds on theClone/Debug
impl block of the builder (#145)Add inheritance of
#[allow()]
and#[expect()]
lint attributes to all generated items. This is useful to suppress any lints coming from the generated code. Although, lints coming from the generated code are generally considered defects inbon
and should be reported via a Github issue, but this provides an easy temporary workaround for the problem (#145)
Fixed
- Fix
#[cfg/cfg_attr()]
not being expanded when used on function arguments with doc comments or other attributes (#145) - Fix raw identifiers in optional/default members (#175)
Other
- Add graceful internal panic handling. If some
bon
macro panics due to an internal bug, the macro will try to generate a fallback for IDEs to still provide intellisense (#145) - Switch from
elastio.github.io/bon
to a custom domainbon-rs.com
(#158) - Add anonymous stats with
umami
for the docs website (#158)
Docs
Refactor the README.md and all pages in the Guide Book by simplifying them and removing redundancies (#170)
Add new pages to the Guide Book:
2.3.0 - 2024-09-14
See the blog post for this release that describes some of the most notable changes in detail.
Added
- Add support for positional params in
start_fn
andfinish_fn
(#125)
Fixed
- Forward lint suppression from
#[allow()/expect()]
attributes written by the user on the top-level to the generated items (#125) - Suppress the false-positive (clippy issue)
clippy::future_not_send
lint (#125) - Fix the cases where
#[builder(derive(Debug, Clone))]
didn't validate for all members to implementClone/Debug
if these members were of reference or generic types (#125)
2.2.1 - 2024-09-09
Changed
- Lower MSRV from 1.70.0 to 1.59.0 (#120)
2.2.0 - 2024-09-08
See the blog post for this release that describes some of the most notable changes in detail.
Changed
The
#[bon::builder]
attribute was deprecated on structs. The new#[derive(bon::Builder)]
should be used to derive a builder from a struct. Starting withbon
2.3 (next minor release) all usages of#[bon::builder]
on structs will generate deprecation warnings. (#99).There is a CLI to assist in migrating to the new syntax. See the release blog post for details about that.
Added
Add the top-level
#[builder(derive(...))]
attribute to be able to deriveClone
andDebug
for the builder type itself (#113)Add support for conditional compilation with
cfg/cfg_attr
(#99)
Fixed
- Fix developer experience in Rust Rover. The new
#[derive(Builder)]
syntax should now be easier for Rust Rover to analyze (#99) - Fix a bug where a member of opaque
Option
type (i.e. theOption
type that was renamed to make the builder macro not detect it asOption
) was still optional. (#99) - Fix code generation for structs with default values for generic parameters (#108)
2.1.1 - 2024-09-03
Added
- Set MSRV to 1.70.0. Note that we plan to set an even lower MSRV. This is just an initial attempt to define the MSRV that should be good enough in the meantime while we work on lowering it even more (#101)
Fixed
- Fix lints triggered by generated code such as
private_bounds
,clippy::missing_const_for_fn
(#101) - Add more context to the messages such that it's clear what member isn't set in Rust Analyzer error messages (#98)
2.1.0 - 2024-09-01
See the blog post for this release that describes some of the most notable changes in detail.
Added
#[must_use]
on thebuild()
method for structs andcall()
for functions (if the original function has#[must_use]
) (#82). Thanks @EdJoPaTo for the contribution!
Changed
- Optimize
bon
's generated code type-checking performance and improve error messages (#84) - Improve builder() method docs (#76). Thanks @EdJoPaTo for the contribution!
Fixed
- Don't warn on
clippy::impl_trait_in_params
(#80). Thanks @EdJoPaTo for the contribution! - Fix typos in messages and code comments (#79). Thanks @EdJoPaTo for the contribution!
Other
- Add more tests for
#[must_use]
(#87)
2.0.1 - 2024-08-28
Docs
- Add a new section "
None
literals inference" to docs for "Into Conversions In-Depth" - Fix the docs about the comparison of Into conversions on the "Alternatives" page that were not updated during the v2 release
Fixed
- Fix capturing of generic params that appear only in return types (#72)
- Fix support for associated types (#72)
Internal
- Add more tests for various edge cases (#70)
2.0.0 - 2024-08-26
See the blog post for details.
1.2.1 - 2024-08-12
Other
1.2.0 - 2024-08-09
Added
Other
- Remove dependencies on
easy-ext
,heck
anditertools
(#42)
1.1.0 - 2024-08-07
Added
- Add
no_std
support (#36). Thanks @danielschemmel for the contribution! - Add asm comparison and benchmarks to docs (#29)
- Add
map!{}
andset![]
macros (#33). Thanks @korrat for the contribution!
Fixed
- Fix
missing_docs
lint in the generated code (#39)
1.0.6 - 2024-08-01
Fixed
- Explicitly specify the minimum required version of the darling dependency (#30)
1.0.5 - 2024-07-31
Added
- Add
#[must_use]
to the builder and other small improvements (#26)
1.0.4 - 2024-07-30
Fixed
- new() method is now hidden by default and the Builder type name is the same as when
#[builder]
is on top of astruct
(#19)
1.0.3 - 2024-07-30
Fixed
- Fix missing captured generics on an impl block that aren't referenced in the method (#17)
1.0.2 - 2024-07-29
Fixed
- Fix a bug of the
Default
trait requirement for types under anOption
(#13) - Fix the link to docs.rs to so that it references the latest version (#11)
1.0.1 - 2024-07-29
Fixed
- Fix handling of raw identifiers (#9)
Other
- Add example snippet to the docs for "adding builder to existing code" (#7)
1.0.0 - 2024-07-28
Added
- Initial release 🎉. See the
bon
crate overview for details.