diff --git a/Cargo.lock b/Cargo.lock index 138c6a83..28194c26 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -76,7 +76,7 @@ dependencies = [ [[package]] name = "bon" -version = "2.3.0" +version = "3.0.0-rc" dependencies = [ "bon-macros", "expect-test", @@ -87,7 +87,7 @@ dependencies = [ [[package]] name = "bon-cli" -version = "0.2.0" +version = "3.0.0-rc" dependencies = [ "anyhow", "ra_ap_parser", @@ -97,7 +97,7 @@ dependencies = [ [[package]] name = "bon-macros" -version = "2.3.0" +version = "3.0.0-rc" dependencies = [ "darling", "expect-test", @@ -111,7 +111,7 @@ dependencies = [ [[package]] name = "bon-sandbox" -version = "2.3.0" +version = "3.0.0-rc" dependencies = [ "bon", "buildstructor", diff --git a/README.md b/README.md index 3e3903bd..b2929a50 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,11 @@ - bon home -

+

github - docs.rs -

+
-`bon` is a Rust crate for generating compile-time-checked builders for functions and structs. It also provides idiomatic partial application with optional and named parameters for functions and methods. +
+ + + + + + + + + + + +
📖 Guide BookNarrative introduction
🔍 API ReferenceAttributes API index
+
-Visit the [guide for a complete overview of the crate](https://bon-rs.com/guide/overview). + -## Quick examples +# Announcement -### Builder for a free function +Release `3.0.0-rc` (release-candidate) was published 🎉. The ultimate stable `3.0.0` release is scheduled for 13-th of November. You are encouraged to use the `3.0.0-rc` version in the meantime and post your feedback in [#156](https://github.com/elastio/bon/issues/156). The release blog post will be ready on the scheduled release date, until then see the [changelog](https://bon-rs.com/changelog) for details. -You can turn a function with positional parameters into a function with named parameters just by placing the `#[builder]` attribute on top of it. +# Overview + +`bon` is a Rust crate for generating compile-time-checked builders for structs and functions. It also provides idiomatic partial application with optional and named parameters for functions and methods. + +If you wonder "Why would I use builders?", see the [motivational blog post](https://bon-rs.com/blog/how-to-do-named-function-arguments-in-rust). + +## Function Builder + +You can turn a function with positional parameters into a function with named parameters with `#[builder]`. ```rust use bon::builder; @@ -60,9 +77,44 @@ let greeting = greet() assert_eq!(greeting, "Hello Bon! Your level is 24"); ``` -### Builder for an associated method +Any syntax for functions is supported including `async`, fallible, generic functions, `impl Trait`, etc. + +Many things are customizable with additional attributes described in the [API reference](https://bon-rs.com/reference/builder), but let's see what else `bon` has to offer. + +## Struct Builder -For associated methods you also need to add the `#[bon]` macro on top of the impl block. +Use `#[derive(Builder)]` to generate a builder for a struct. + +```rust +use bon::Builder; + +#[derive(Builder)] +struct User { + name: String, + is_admin: bool, + level: Option, +} + +let user = User::builder() + .name("Bon".to_owned()) + // `level` is optional, we could omit it here + .level(24) + // call setters in any order + .is_admin(true) + .build(); + +assert_eq!(user.name, "Bon"); +assert_eq!(user.level, Some(24)); +assert!(user.is_admin); +``` + +## Method Builder + +Associated methods require `#[bon]` on top of the impl block additionally. + +### Method `new` + +The method named `new` generates `builder()/build()` methods. ```rust use bon::bon; @@ -72,74 +124,122 @@ struct User { name: String, } -#[bon] // <- this attribute is required on impl blocks that contain `#[builder]` +#[bon] impl User { #[builder] fn new(id: u32, name: String) -> Self { Self { id, name } } +} + +let user = User::builder() + .id(1) + .name("Bon".to_owned()) + .build(); + +assert_eq!(user.id, 1); +assert_eq!(user.name, "Bon"); +``` + +`#[derive(Builder)]` on a struct generates builder API that is fully compatible with placing `#[builder]` on the `new()` method with a signature similar to the struct's fields (more details on the [Compatibility](https://bon-rs.com/guide/basics/compatibility#switching-between-derive-builder-and-builder-on-the-new-method) page). + +### Other Methods +All other methods generate `{method_name}()/call()` methods. + +```rust +use bon::bon; + +struct Greeter { + name: String, +} + +#[bon] +impl Greeter { #[builder] - fn greet(&self, target: &str, level: Option<&str>) -> String { - let level = level.unwrap_or("INFO"); + fn greet(&self, target: &str, prefix: Option<&str>) -> String { + let prefix = prefix.unwrap_or("INFO"); let name = &self.name; - format!("[{level}] {name} says hello to {target}") + format!("[{prefix}] {name} says hello to {target}") } } -// The method named `new` generates `builder()/build()` methods -let user = User::builder() - .id(1) - .name("Bon".to_owned()) - .build(); +let greeter = Greeter { name: "Bon".to_owned() }; -// All other methods generate `method_name()/call()` methods -let greeting = user +let greeting = greeter .greet() .target("the world") - // `level` is optional, we can omit it here + // `prefix` is optional, omitting it is fine .call(); -assert_eq!(user.id, 1); -assert_eq!(user.name, "Bon"); assert_eq!(greeting, "[INFO] Bon says hello to the world"); ``` -### Builder for a struct +Methods with or without `self` are both supported. -The `#[derive(Builder)]` macro generates a builder for a struct. +## No Panics Possible -```rust -use bon::Builder; +Builders generated by `bon`'s macros use the typestate pattern to ensure all required parameters are filled, and the same setters aren't called repeatedly to prevent unintentional overwrites. If something is wrong, a compile error will be created. -#[derive(Builder)] -struct User { - name: String, - is_admin: bool, - level: Option, -} +| ⭐ Don't forget to give our repo a [star on Github ⭐](https://github.com/elastio/bon)! | +| --------------------------------------------------------------------------------------- | -let user = User::builder() - .name("Bon".to_owned()) - // `level` is optional, we could omit it here - .level(24) - // call setters in any order - .is_admin(true) - .build(); +## What's Next? -assert_eq!(user.name, "Bon"); -assert_eq!(user.level, Some(24)); -assert!(user.is_admin); +What you've seen above is the first page of the 📖 Guide Book. If you want to learn more, jump to the [Basics](https://bon-rs.com/guide/basics) section. And remember: knowledge is power 🐱! + +Feel free to jump to code and use the `#[builder]` and `#[derive(Builder)]` once you've seen enough docs to get started. + +The [🔍 API Reference](https://bon-rs.com/reference/builder) will help you navigate the attributes once you feel comfortable with the basics of `bon`. Both `#[derive(Builder)]` on structs and `#[builder]` on functions/methods have almost identical attributes API, so the documentation for them is common. + +## Installation + +Add `bon` to your `Cargo.toml`. + +```toml +[dependencies] +bon = "2.3" ``` -See [the guide](https://bon-rs.com/guide/overview) for more. +You can opt out of `std` and `alloc` cargo features with `default-features = false` for `no_std` environments. + +## Acknowledgments + +This project was heavily inspired by such awesome crates as [`buildstructor`](https://docs.rs/buildstructor), [`typed-builder`](https://docs.rs/typed-builder) and [`derive_builder`](https://docs.rs/derive_builder). This crate was designed with many lessons learned from them. + +See [alternatives](https://bon-rs.com/guide/alternatives) for comparison. + +## Who's Using `bon`? ---- +Some notable users: -If you like the idea of this crate and want to say "thank you" or "keep doing this" consider giving us a [star ⭐ on Github](https://github.com/elastio/bon). Any support and contribution are appreciated 🐱! +- [`crates.io` backend](https://github.com/rust-lang/crates.io) +- [`ractor`](https://github.com/slawlor/ractor) +- [`comrak`](https://github.com/kivikakk/comrak) +- [`soldeer`](https://github.com/mario-eth/soldeer) (package manager endorsed by [`foundry`](https://github.com/foundry-rs/foundry)) +- [`tachyonfx`](https://github.com/junkdog/tachyonfx) -#### License +## Getting Help + +If you can't figure something out, consult the docs and maybe use the `🔍 Search` bar on our [docs website](https://bon-rs.com). You may also create an issue or a discussion on the [Github repository](https://github.com/elastio/bon) for help or write us a message on [Discord](https://bon-rs.com/discord). + +## Socials + + + + + + + + + + + + +
DiscordHere you can leave feedback, ask questions, report bugs, or just write "thank you".
X (Twitter)Profile of the maintainer. There are only posts about bon and Rust in general here.
+ +## License Licensed under either of Apache License, Version @@ -153,3 +253,5 @@ Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. + + diff --git a/README.v3.md b/README.v3.md deleted file mode 100644 index 1117c9b2..00000000 --- a/README.v3.md +++ /dev/null @@ -1,253 +0,0 @@ - - bon home - - -
- github - crates.io - docs.rs - docs.rs -
- -
- - - - - - - - - - - -
📖 Guide BookNarrative introduction
🔍 API ReferenceAttributes API index
-
- - - -# Overview - -`bon` is a Rust crate for generating compile-time-checked builders for structs and functions. It also provides idiomatic partial application with optional and named parameters for functions and methods. - -If you wonder "Why would I use builders?", see the [motivational blog post](https://bon-rs.com/blog/how-to-do-named-function-arguments-in-rust). - -## Function Builder - -You can turn a function with positional parameters into a function with named parameters with `#[builder]`. - -```rust -use bon::builder; - -#[builder] -fn greet(name: &str, level: Option) -> String { - let level = level.unwrap_or(0); - - format!("Hello {name}! Your level is {level}") -} - -let greeting = greet() - .name("Bon") - .level(24) // <- setting `level` is optional, we could omit it - .call(); - -assert_eq!(greeting, "Hello Bon! Your level is 24"); -``` - -Any syntax for functions is supported including `async`, fallible, generic functions, `impl Trait`, etc. - -Many things are customizable with additional attributes described in the [API reference](https://bon-rs.com/reference/builder), but let's see what else `bon` has to offer. - -## Struct Builder - -Use `#[derive(Builder)]` to generate a builder for a struct. - -```rust -use bon::Builder; - -#[derive(Builder)] -struct User { - name: String, - is_admin: bool, - level: Option, -} - -let user = User::builder() - .name("Bon".to_owned()) - // `level` is optional, we could omit it here - .level(24) - // call setters in any order - .is_admin(true) - .build(); - -assert_eq!(user.name, "Bon"); -assert_eq!(user.level, Some(24)); -assert!(user.is_admin); -``` - -## Method Builder - -Associated methods require `#[bon]` on top of the impl block additionally. - -### Method `new` - -The method named `new` generates `builder()/build()` methods. - -```rust -use bon::bon; - -struct User { - id: u32, - name: String, -} - -#[bon] -impl User { - #[builder] - fn new(id: u32, name: String) -> Self { - Self { id, name } - } -} - -let user = User::builder() - .id(1) - .name("Bon".to_owned()) - .build(); - -assert_eq!(user.id, 1); -assert_eq!(user.name, "Bon"); -``` - -`#[derive(Builder)]` on a struct generates builder API that is fully compatible with placing `#[builder]` on the `new()` method with a signature similar to the struct's fields (more details on the [Compatibility](https://bon-rs.com/guide/basics/compatibility#switching-between-derive-builder-and-builder-on-the-new-method) page). - -### Other Methods - -All other methods generate `{method_name}()/call()` methods. - -```rust -use bon::bon; - -struct Greeter { - name: String, -} - -#[bon] -impl Greeter { - #[builder] - fn greet(&self, target: &str, prefix: Option<&str>) -> String { - let prefix = prefix.unwrap_or("INFO"); - let name = &self.name; - - format!("[{prefix}] {name} says hello to {target}") - } -} - -let greeter = Greeter { name: "Bon".to_owned() }; - -let greeting = greeter - .greet() - .target("the world") - // `prefix` is optional, omitting it is fine - .call(); - -assert_eq!(greeting, "[INFO] Bon says hello to the world"); -``` - -Methods with or without `self` are both supported. - -## No Panics Possible - -Builders generated by `bon`'s macros use the typestate pattern to ensure all required parameters are filled, and the same setters aren't called repeatedly to prevent unintentional overwrites. If something is wrong, a compile error will be created. - -| ⭐ Don't forget to give our repo a [star on Github ⭐](https://github.com/elastio/bon)! | -| --------------------------------------------------------------------------------------- | - -## What's Next? - -What you've seen above is the first page of the 📖 Guide Book. If you want to learn more, jump to the [Basics](https://bon-rs.com/guide/basics) section. And remember: knowledge is power 🐱! - -Feel free to jump to code and use the `#[builder]` and `#[derive(Builder)]` once you've seen enough docs to get started. - -The [🔍 API Reference](https://bon-rs.com/reference/builder) will help you navigate the attributes once you feel comfortable with the basics of `bon`. Both `#[derive(Builder)]` on structs and `#[builder]` on functions/methods have almost identical attributes API, so the documentation for them is common. - -## Installation - -Add `bon` to your `Cargo.toml`. - -```toml -[dependencies] -bon = "2.3" -``` - -You can opt out of `std` and `alloc` cargo features with `default-features = false` for `no_std` environments. - -## Acknowledgments - -This project was heavily inspired by such awesome crates as [`buildstructor`](https://docs.rs/buildstructor), [`typed-builder`](https://docs.rs/typed-builder) and [`derive_builder`](https://docs.rs/derive_builder). This crate was designed with many lessons learned from them. - -See [alternatives](https://bon-rs.com/guide/alternatives) for comparison. - -## Who's Using `bon`? - -Some notable users: - -- [`crates.io` backend](https://github.com/rust-lang/crates.io) -- [`ractor`](https://github.com/slawlor/ractor) -- [`comrak`](https://github.com/kivikakk/comrak) -- [`soldeer`](https://github.com/mario-eth/soldeer) (package manager endorsed by [`foundry`](https://github.com/foundry-rs/foundry)) -- [`tachyonfx`](https://github.com/junkdog/tachyonfx) - -## Getting Help - -If you can't figure something out, consult the docs and maybe use the `🔍 Search` bar on our [docs website](https://bon-rs.com). You may also create an issue or a discussion on the [Github repository](https://github.com/elastio/bon) for help or write us a message on [Discord](https://bon-rs.com/discord). - -## Socials - - - - - - - - - - - - -
DiscordHere you can leave feedback, ask questions, report bugs, or just write "thank you".
X (Twitter)Profile of the maintainer. There are only posts about bon and Rust in general here.
- -## License - - -Licensed under either of Apache License, Version -2.0 or MIT license at your option. - - -
- - -Unless you explicitly state otherwise, any contribution intentionally submitted -for inclusion in the work by you, as defined in the Apache-2.0 license, shall be -dual licensed as above, without any additional terms or conditions. - - - diff --git a/bon-cli/Cargo.toml b/bon-cli/Cargo.toml index ebf73851..54b9f17b 100644 --- a/bon-cli/Cargo.toml +++ b/bon-cli/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "bon-cli" -version = "0.2.0" +version = "3.0.0-rc" description = "Dev tool for working with the `bon` crate" diff --git a/bon-macros/Cargo.toml b/bon-macros/Cargo.toml index bb54fa34..e8f0e096 100644 --- a/bon-macros/Cargo.toml +++ b/bon-macros/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "bon-macros" -version = "2.3.0" +version = "3.0.0-rc" description = """ This is a proc-macro crate that is supposed to be a private implementation diff --git a/bon-sandbox/Cargo.toml b/bon-sandbox/Cargo.toml index 02c364b5..6422d8b8 100644 --- a/bon-sandbox/Cargo.toml +++ b/bon-sandbox/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "bon-sandbox" -version = "2.3.0" +version = "3.0.0-rc" description = """ Not a real crate! It's just a showcase of examples used by `bon`'s documentation @@ -29,7 +29,7 @@ targets = ["x86_64-unknown-linux-gnu"] workspace = true [dependencies] -bon = { path = "../bon", version = "=2.3.0", features = ["experimental-overwritable"] } +bon = { path = "../bon", version = "=3.0.0-rc", features = ["experimental-overwritable"] } buildstructor = "0.5" derive_builder = "0.20" typed-builder = "0.20" diff --git a/bon/Cargo.toml b/bon/Cargo.toml index 49dcc9cd..6e2d5075 100644 --- a/bon/Cargo.toml +++ b/bon/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "bon" -version = "2.3.0" +version = "3.0.0-rc" description = "Next-gen compile-time-checked builder generator, named function's arguments, and more!" @@ -45,7 +45,7 @@ workspace = true # The version of the macro crate is pinned to a specific one because the code # generated by the macros uses private APIs from the runtime crate that are not # guarded by semver. -bon-macros = { path = "../bon-macros", version = "=2.3.0" } +bon-macros = { path = "../bon-macros", version = "=3.0.0-rc" } rustversion = "1" [dev-dependencies] diff --git a/website/src/changelog.md b/website/src/changelog.md index f3bbb3dd..6f51e28c 100644 --- a/website/src/changelog.md +++ b/website/src/changelog.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [3.0.0-rc](https://github.com/elastio/bon/compare/v2.3.0...v3.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 diff --git a/website/src/reference/bon.md b/website/src/reference/bon.md index 08be8819..360ac7dc 100644 --- a/website/src/reference/bon.md +++ b/website/src/reference/bon.md @@ -5,6 +5,6 @@ where you want to define methods with the [`builder`] macro. It provides the necessary context to the [`builder`] macros on top of the functions inside of the `impl` block. You'll get compile errors without that context. -For the examples of the usage of this macro and the reason why it's needed, see this paragraph in [the overview](../guide/overview#builder-for-an-associated-method). +For the examples of the usage of this macro, see this paragraph in [the overview](../guide/overview#method-builder). [`builder`]: ./builder