From cb79ad1d4b3fa505d5f5d5e8261813c69e05dee6 Mon Sep 17 00:00:00 2001 From: Ted Driggs Date: Mon, 26 Feb 2024 12:34:50 -0800 Subject: [PATCH] Update example style to remove #[macro_use] Fixes #211 --- derive_builder/README.md | 53 +++++++++-------- derive_builder/examples/channel.rs | 5 +- derive_builder/examples/custom_constructor.rs | 3 +- derive_builder/examples/custom_defaults.rs | 3 +- derive_builder/examples/custom_error.rs | 6 +- .../examples/custom_error_generic.rs | 5 +- derive_builder/examples/deny_missing_docs.rs | 3 +- derive_builder/examples/doc_example.rs | 3 +- derive_builder/examples/readme_example.rs | 3 +- derive_builder/examples/validation.rs | 5 +- derive_builder/src/lib.rs | 58 ++++++------------- 11 files changed, 57 insertions(+), 90 deletions(-) diff --git a/derive_builder/README.md b/derive_builder/README.md index bfc015d4..7118a154 100644 --- a/derive_builder/README.md +++ b/derive_builder/README.md @@ -12,8 +12,7 @@ ## How it Works ```rust -#[macro_use] -extern crate derive_builder; +use derive_builder::Builder; #[derive(Default, Builder, Debug)] #[builder(setter(into))] @@ -105,40 +104,40 @@ It's as simple as three steps: 1. Add `derive_builder` to your `Cargo.toml` either manually or with [cargo-edit](https://github.com/killercup/cargo-edit): -- `cargo add derive_builder` +- `cargo add derive_builder` 2. Add `use derive_builder::Builder;` 3. Annotate your struct with `#[derive(Builder)]` ## Usage and Features -- **Chaining**: The setter calls can be chained, because they consume and return `&mut self` by default. -- **Builder patterns**: You can opt into other builder patterns by preceding your struct (or field) with `#[builder(pattern = "owned")]` or `#[builder(pattern = "immutable")]`. -- **Extensible**: You can still define your own implementations for the builder struct and define additional methods. Just make sure to name them differently than the setter and build methods. -- **Documentation and attributes**: Setter methods can be documented by simply documenting the corresponding field. Similarly `#[cfg(...)]` and `#[allow(...)]` attributes are also applied to the setter methods. -- **Hidden fields**: You can skip setters via `#[builder(setter(skip))]` on each field individually. -- **Setter visibility**: You can opt into private setter by preceding your struct with `#[builder(private)]`. -- **Setter type conversions**: With `#[builder(setter(into))]`, setter methods will be generic over the input types – you can then supply every argument that implements the [`Into`][into] trait for the field type. -- **Setter strip option**: With `#[builder(setter(strip_option))]`, setter methods will take `T` as parameter'type for field of type `Option`. -- **Collection setters**: Adding `#[builder(setter(each(name = "method_name")))]` to fields whose types implement `Default` and `Extend` will generate a setter which adds items to the builder collection for that field. It's possible for these setters to be generic over the `Into` trait too, like so: `#[builder(setter(each(name = "foo", into)))]`. -- **Builder field visibility**: You can use `#[builder(field(private))]` or `..(public)`, to set field visibility of your builder. -- **Generic structs**: Are also supported, but you **must not** use a type parameter named `VALUE`, if you also activate setter type conversions. -- **Default values**: You can use `#[builder(default)]` to delegate to the `Default` implementation or any explicit value via ` = ".."`. This works both on the struct and field level. -- **Pre-build validation**: You can use `#[builder(build_fn(validate = "path::to::fn"))]` to add your own validation before the target struct is generated. -- **Build method suppression**: You can use `#[builder(build_fn(skip))]` to disable auto-implementation of the build method and provide your own. -- **Custom build method error types**: You can use `#[builder(build_fn(error = "path::to::Error"))]` to have your builder return an error type of your choosing. By default, the macro will emit an error type alongside the builder. -- **Builder derivations**: You can use `#[builder(derive(Trait1, Trait2, ...))]` to have the builder derive additonal traits. All builders derive `Default` and `Clone`, so you should not declare those in this attribute. -- **Pass-through attributes**: Use `#[builder_struct_attr(...)]`, `#[builder_impl_attr(...)]`, `#[builder_field_attr(...)]`, and `#[builder_setter_attr(...)]` to declare attributes that will be added to the relevant part of the generated builder. -- **no_std support**: Just add `#[builder(no_std)]` to your struct, use feature `alloc`, and add `extern crate alloc` to your crate. -- **No alloc no_std support**: Do not use `alloc` feature and then either add `#[builder(no_std, build_fn(error(validation_error = false)))]` or `#[builder(no_std, build_fn(error = "path::to::Error"))]` to your struct. -- **Renaming and re-export support**: Use `#[builder(crate = "...")]` to set the root for `derive_builder`. This is useful if you want to rename `derive_builder` in `Cargo.toml` or if your crate is re-exporting `derive_builder::Builder` and needs the generated code to not directly reference the `derive_builder` crate. +- **Chaining**: The setter calls can be chained, because they consume and return `&mut self` by default. +- **Builder patterns**: You can opt into other builder patterns by preceding your struct (or field) with `#[builder(pattern = "owned")]` or `#[builder(pattern = "immutable")]`. +- **Extensible**: You can still define your own implementations for the builder struct and define additional methods. Just make sure to name them differently than the setter and build methods. +- **Documentation and attributes**: Setter methods can be documented by simply documenting the corresponding field. Similarly `#[cfg(...)]` and `#[allow(...)]` attributes are also applied to the setter methods. +- **Hidden fields**: You can skip setters via `#[builder(setter(skip))]` on each field individually. +- **Setter visibility**: You can opt into private setter by preceding your struct with `#[builder(private)]`. +- **Setter type conversions**: With `#[builder(setter(into))]`, setter methods will be generic over the input types – you can then supply every argument that implements the [`Into`][into] trait for the field type. +- **Setter strip option**: With `#[builder(setter(strip_option))]`, setter methods will take `T` as parameter'type for field of type `Option`. +- **Collection setters**: Adding `#[builder(setter(each(name = "method_name")))]` to fields whose types implement `Default` and `Extend` will generate a setter which adds items to the builder collection for that field. It's possible for these setters to be generic over the `Into` trait too, like so: `#[builder(setter(each(name = "foo", into)))]`. +- **Builder field visibility**: You can use `#[builder(field(private))]` or `..(public)`, to set field visibility of your builder. +- **Generic structs**: Are also supported, but you **must not** use a type parameter named `VALUE`, if you also activate setter type conversions. +- **Default values**: You can use `#[builder(default)]` to delegate to the `Default` implementation or any explicit value via ` = ".."`. This works both on the struct and field level. +- **Pre-build validation**: You can use `#[builder(build_fn(validate = "path::to::fn"))]` to add your own validation before the target struct is generated. +- **Build method suppression**: You can use `#[builder(build_fn(skip))]` to disable auto-implementation of the build method and provide your own. +- **Custom build method error types**: You can use `#[builder(build_fn(error = "path::to::Error"))]` to have your builder return an error type of your choosing. By default, the macro will emit an error type alongside the builder. +- **Builder derivations**: You can use `#[builder(derive(Trait1, Trait2, ...))]` to have the builder derive additonal traits. All builders derive `Default` and `Clone`, so you should not declare those in this attribute. +- **Pass-through attributes**: Use `#[builder_struct_attr(...)]`, `#[builder_impl_attr(...)]`, `#[builder_field_attr(...)]`, and `#[builder_setter_attr(...)]` to declare attributes that will be added to the relevant part of the generated builder. +- **no_std support**: Just add `#[builder(no_std)]` to your struct, use feature `alloc`, and add `extern crate alloc` to your crate. +- **No alloc no_std support**: Do not use `alloc` feature and then either add `#[builder(no_std, build_fn(error(validation_error = false)))]` or `#[builder(no_std, build_fn(error = "path::to::Error"))]` to your struct. +- **Renaming and re-export support**: Use `#[builder(crate = "...")]` to set the root for `derive_builder`. This is useful if you want to rename `derive_builder` in `Cargo.toml` or if your crate is re-exporting `derive_builder::Builder` and needs the generated code to not directly reference the `derive_builder` crate. For more information and examples please take a look at our [documentation][doc]. ## Gotchas -- Tuple structs and unit structs are not supported as they have no field names. We do not intend to support them. -- When defining a generic struct, you cannot use `VALUE` as a generic parameter as this is what all setters are using. +- Tuple structs and unit structs are not supported as they have no field names. We do not intend to support them. +- When defining a generic struct, you cannot use `VALUE` as a generic parameter as this is what all setters are using. ## [Documentation][doc] @@ -157,8 +156,8 @@ Yes, we keep a changelog. Licensed under either of -- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or ) -- MIT license ([LICENSE-MIT](LICENSE-MIT) or ) +- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or ) +- MIT license ([LICENSE-MIT](LICENSE-MIT) or ) at your option. diff --git a/derive_builder/examples/channel.rs b/derive_builder/examples/channel.rs index 7c89701b..ebe17b53 100644 --- a/derive_builder/examples/channel.rs +++ b/derive_builder/examples/channel.rs @@ -1,10 +1,9 @@ #![allow(dead_code)] -#[macro_use] -extern crate derive_builder; - use std::convert::From; +use derive_builder::Builder; + #[derive(PartialEq, Default, Debug, Clone)] struct Uuid(i32); #[derive(PartialEq, Default, Debug, Clone)] diff --git a/derive_builder/examples/custom_constructor.rs b/derive_builder/examples/custom_constructor.rs index 9d9d6fdd..413201b0 100644 --- a/derive_builder/examples/custom_constructor.rs +++ b/derive_builder/examples/custom_constructor.rs @@ -1,7 +1,6 @@ #![allow(dead_code)] -#[macro_use] -extern crate derive_builder; +use derive_builder::Builder; #[derive(Debug, Clone)] pub enum ContentType { diff --git a/derive_builder/examples/custom_defaults.rs b/derive_builder/examples/custom_defaults.rs index bf493d9e..d39f7c55 100644 --- a/derive_builder/examples/custom_defaults.rs +++ b/derive_builder/examples/custom_defaults.rs @@ -1,5 +1,4 @@ -#[macro_use] -extern crate derive_builder; +use derive_builder::Builder; #[derive(Builder, PartialEq, Debug)] struct Lorem { diff --git a/derive_builder/examples/custom_error.rs b/derive_builder/examples/custom_error.rs index 409809ac..8cd1b493 100644 --- a/derive_builder/examples/custom_error.rs +++ b/derive_builder/examples/custom_error.rs @@ -5,12 +5,10 @@ //! the generated `FooBuilderError` type is valid. #![allow(dead_code)] -#[macro_use] -extern crate derive_builder; - -use derive_builder::UninitializedFieldError; use std::fmt; +use derive_builder::{Builder, UninitializedFieldError}; + fn validate_age(builder: &ExampleBuilder) -> Result<(), Error> { match builder.age { Some(age) if age > 150 => Err(Error::UnrealisticAge(age)), diff --git a/derive_builder/examples/custom_error_generic.rs b/derive_builder/examples/custom_error_generic.rs index 230d53eb..595b8a75 100644 --- a/derive_builder/examples/custom_error_generic.rs +++ b/derive_builder/examples/custom_error_generic.rs @@ -3,10 +3,7 @@ //! Note the use of the type parameter in the `#[builder(...)]` attribute. #![allow(dead_code)] -#[macro_use] -extern crate derive_builder; - -use derive_builder::UninitializedFieldError; +use derive_builder::{Builder, UninitializedFieldError}; trait Popular { fn is_popular(&self) -> bool; diff --git a/derive_builder/examples/deny_missing_docs.rs b/derive_builder/examples/deny_missing_docs.rs index 1121a1ec..c2441c10 100644 --- a/derive_builder/examples/deny_missing_docs.rs +++ b/derive_builder/examples/deny_missing_docs.rs @@ -3,8 +3,7 @@ //! NOTE: This can only be tested in examples, but not integration tests. #![deny(missing_docs)] -#[macro_use] -extern crate derive_builder; +use derive_builder::Builder; /// Traditional form of communication. #[derive(Debug, Builder)] diff --git a/derive_builder/examples/doc_example.rs b/derive_builder/examples/doc_example.rs index 43fddbf5..aac6f8ec 100644 --- a/derive_builder/examples/doc_example.rs +++ b/derive_builder/examples/doc_example.rs @@ -2,8 +2,7 @@ // // cargo expand --example doc_example -#[macro_use] -extern crate derive_builder; +use derive_builder::Builder; #[allow(dead_code)] #[derive(Builder)] diff --git a/derive_builder/examples/readme_example.rs b/derive_builder/examples/readme_example.rs index d227dc1e..b71c9626 100644 --- a/derive_builder/examples/readme_example.rs +++ b/derive_builder/examples/readme_example.rs @@ -3,8 +3,7 @@ // cargo expand --example readme_example #![allow(dead_code)] -#[macro_use] -extern crate derive_builder; +use derive_builder::Builder; #[derive(Default, Builder, Debug)] #[builder(setter(into))] diff --git a/derive_builder/examples/validation.rs b/derive_builder/examples/validation.rs index 154b937e..82810767 100644 --- a/derive_builder/examples/validation.rs +++ b/derive_builder/examples/validation.rs @@ -1,11 +1,10 @@ //! This example illustrates the use of `validate` to add a pre-build validation //! step. -#[macro_use] -extern crate derive_builder; +use derive_builder::Builder; #[derive(Builder, Debug, PartialEq)] -#[builder(build_fn(validate = "Self::validate"))] +#[builder(build_fn(validate = Self::validate))] struct Lorem { pub ipsum: u8, } diff --git a/derive_builder/src/lib.rs b/derive_builder/src/lib.rs index 05c5f61a..d475974d 100644 --- a/derive_builder/src/lib.rs +++ b/derive_builder/src/lib.rs @@ -12,8 +12,7 @@ //! ## What you write //! //! ```rust -//! #[macro_use] -//! extern crate derive_builder; +//! use derive_builder::Builder; //! //! #[derive(Builder)] //! struct Lorem { @@ -26,9 +25,7 @@ //! ## What you get //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; -//! # use derive_builder::UninitializedFieldError; +//! # use derive_builder::{Builder, UninitializedFieldError}; //! # //! # struct Lorem { //! # ipsum: u32, @@ -76,7 +73,7 @@ //! Let's look again at the example above. You can now build structs like this: //! //! ```rust -//! # #[macro_use] extern crate derive_builder; +//! # use derive_builder::Builder; //! # #[derive(Builder)] struct Lorem { ipsum: u32 } //! # fn try_main() -> Result<(), Box> { //! let x: Lorem = LoremBuilder::default().ipsum(42).build()?; @@ -89,7 +86,7 @@ //! So let's make this call conditional //! //! ```rust -//! # #[macro_use] extern crate derive_builder; +//! # use derive_builder::Builder; //! # #[derive(Builder)] struct Lorem { ipsum: u32 } //! # fn try_main() -> Result<(), Box> { //! # let geek = true; @@ -164,8 +161,7 @@ //! The types of skipped fields must implement `Default`. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder)] //! struct HiddenField { @@ -188,8 +184,7 @@ //! as `Option`. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder)] //! struct SetterOptOut { @@ -223,8 +218,7 @@ //! You can override this: //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder)] //! #[builder(name = "FooConstructor")] @@ -254,8 +248,7 @@ //! `#[builder(setter(into))]` to either a field or the whole struct. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder, Debug, PartialEq)] //! struct Lorem { @@ -279,8 +272,7 @@ //! `#[builder(setter(strip_option))]` to either a single field or the whole struct. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder, Debug, PartialEq)] //! struct Lorem { @@ -316,8 +308,7 @@ //! to add `#![feature(try_from)]` to your crate to use it. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! #[derive(Builder, Debug, PartialEq)] //! #[builder(try_setter, setter(into))] //! struct Lorem { @@ -356,8 +347,7 @@ //! The expression will be evaluated with each call to `build`. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder, Debug, PartialEq)] //! struct Lorem { @@ -390,8 +380,7 @@ //! [`Default`]: https://doc.rust-lang.org/std/default/trait.Default.html //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! # #[derive(Builder, PartialEq, Debug)] //! struct Lorem { @@ -431,8 +420,7 @@ //! ## Generic Structs //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder, Debug, PartialEq, Default, Clone)] //! struct GenLorem { @@ -464,8 +452,7 @@ //! the `Ok` variant is not used by the `build` method. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder, Debug, PartialEq)] //! #[builder(build_fn(validate = "Self::validate"))] @@ -505,8 +492,7 @@ //! You can derive additional traits on the builder, including traits defined by other crates: //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder, Clone)] //! #[builder(derive(Debug, PartialEq, Eq))] @@ -536,8 +522,7 @@ //! those used by Serde, Diesel, or others. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder)] //! struct Lorem { @@ -564,8 +549,7 @@ //! - `builder_setter_attr` adds attributes to the setter in the `impl` block. //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! # //! #[derive(Builder)] //! #[builder(derive(serde::Serialize))] @@ -587,7 +571,6 @@ //! By default, `build` returns an autogenerated error type: //! //! ```rust -//! # extern crate derive_builder; //! # use derive_builder::UninitializedFieldError; //! # use std::fmt::{self, Display}; //! # @@ -613,9 +596,7 @@ //! //! Alternatively, you can specify your own error type: //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; -//! # use derive_builder::UninitializedFieldError; +//! # use derive_builder::{Builder, UninitializedFieldError}; //! # //! #[derive(Builder, Debug, PartialEq)] //! #[builder(build_fn(error = "OurLoremError"))] @@ -640,8 +621,7 @@ //! Instead of having an `Option`, you can have whatever type you like: //! //! ```rust -//! # #[macro_use] -//! # extern crate derive_builder; +//! # use derive_builder::Builder; //! #[derive(Debug, PartialEq, Default, Builder, Clone)] //! #[builder(derive(Debug, PartialEq))] //! struct Lorem {