From 63d98fbdad59034f92c6222dbe3a9daeb21c0cd0 Mon Sep 17 00:00:00 2001 From: Antonio Yang Date: Tue, 12 May 2026 19:51:15 +0800 Subject: [PATCH 1/2] bump 0.12.0 --- Cargo.toml | 2 +- README.md | 39 +++++++++++++++++++++----------------- complex-example/Cargo.toml | 2 +- lib/Cargo.toml | 2 +- no-std-examples/Cargo.toml | 2 +- 5 files changed, 26 insertions(+), 21 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index ad791a6..df2734e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ exclude = [ [workspace.package] authors = ["Antonio Yang "] -version = "0.11.0" +version = "0.12.0" edition = "2021" categories = ["development-tools"] keywords = ["struct", "patch", "macro", "derive", "overlay"] diff --git a/README.md b/README.md index 23a9440..f8f4950 100644 --- a/README.md +++ b/README.md @@ -3,20 +3,25 @@ [![MIT licensed][mit-badge]][mit-url] [![Docs][doc-badge]][doc-url] -A lib help you modify the config struct, you can -- patch an instance, and easy to partial update with `Patch` derive macro -- fill up an instance with `Filler` derive macro -- extend with extra fields with `Substrate` and `Catalyst` derive macros +A library to help you modify config structs. It provides: + +- `Patch` derive macro for partial updates +- `Filler` derive macro to fill empty fields +- `Substrate` and `Catalyst` derive macros to extend with extra fields ## Introduction -This crate provides the `Patch`, `Filler` traits and accompanying derive macro. -If the any field in `Patch` is some then it will overwrite the field of instance when apply. -If the any field in the instance is none then it will try to fill the field with the `Filler`. -Currently, `Filler` only support `Option` and `Vec` fields, and also you can check this [template](https://github.com/yanganto/ConfigTemplate) -if you already work on a big project with a lot of configs. -This crate support `no_std`, please check [no-std-examples](./no-std-examples). -When extending a config, the base struct should be expose in the build script with `Substrate` trait, then a catalyst struct can bind and produce complex struct, -please check [complex-example](./complex-example) and the [Quick Example: case 3](#case-3---extend-a-struct-from-a-crate). + +This crate provides the `Patch`, `Filler`, `Substrate`, `Catalyst` and `Complex` traits with accompanying derive macros in following 3 using cases. + +- If any field in `Patch` is `Some`, it will overwrite the corresponding field when applied. +- If any field in the instance is `None`, `Filler` will try to fill it, only supports `Option` and `Vec` fields. +- With `catalyst` feature, `Substrate`, `Catalyst` and `Complex` traits with accompanying derive macros help you extend struct with extra fields. + +This crate supports `no_std` — check the [no-std-examples](./no-std-examples). + +Following are more specific case, help you to learn the details. +- A project with config from environments, files, command line, you can easy to use `Patch` make your config organized. Please check this [template](https://github.com/yanganto/ConfigTemplate). +- A project extended from another project, and only some fields of config are different. We can use `catalyst` feature to expose the base struct in the build script with `Substrate`, then a `Catalyst` struct can bind to it and produce a complex struct. Check the [complex-example](./complex-example) and [Quick Example: case 3](#case-3---extend-a-struct-from-a-crate). ## Quick Example #### Case 1 - Patch on a Config @@ -111,7 +116,7 @@ Deriving `Substrate` on a struct will help you expose the field information, and Deriving `Catalyst` on can read the field information of Substrate and generate a new Complex struct. All the fields in substrate and catalyst need be public, and the fields in complex are also public. The overall behavior likes chemical catalysts, a catalyst **bind** on a substrate to form a complex struct, which has all fields from substrate and catalyst. -Also, a complex can **decouple** and return a catalyst and substrate, please check [complex-example](./complex-example/catalyst/src/lib.rs). +Also, a complex can **decouple** and return a catalyst and substrate. Check the [complex-example](./complex-example/catalyst/src/lib.rs). ```rust /// In $dependency_crate/src/lib.rs @@ -148,7 +153,7 @@ struct Amyloid { ``` ## Documentation and Examples -Also, you can modify the patch structure by defining `#[patch(...)]`, `#[filler(...)]` or `#[complex(...)]`, `#[catalyst(...)]` attributes on the original struct or fields. +You can modify the patch structure by defining `#[patch(...)]`, `#[filler(...)]` or `#[complex(...)]`, `#[catalyst(...)]` attributes on the original struct or fields. Struct attributes: - `#[patch(name = "...")]`: change the name of the generated patch struct. @@ -164,13 +169,13 @@ Field attributes: - `#[patch(attribute(...))]`: add attributes to the field in the generated patch struct. - `#[patch(attribute(derive(...)))]`: add derives to the field in the generated patch struct. - `#[patch(empty_value = ...)]`: define a value as empty, so the corresponding field of patch will not wrapped by Option, and apply patch when the field is empty. -- `#[filler(extendable)]`: use the struct of field for filler, the struct needs implement `Default`, `Extend`, `IntoIterator` and `is_empty`. +- `#[filler(extendable)]`: use the field of the struct for filler, the struct needs implement `Default`, `Extend`, `IntoIterator` and `is_empty`. - `#[filler(empty_value = ...)]`: define a value as empty, so the corresponding field of Filler will be applied, even the field is not `Option` or `Extendable`. Please check the [traits][doc-traits] of document to learn more. The [examples][examples] demo following scenarios. -- diff two instance for a patch +- diff two instances for a patch - create a patch from json string - rename the patch structure - check a patch is empty or not @@ -203,4 +208,4 @@ This crate also includes the following optional features: [doc-badge]: https://img.shields.io/badge/docs-rs-orange.svg [doc-url]: https://docs.rs/struct-patch/ [doc-traits]: https://docs.rs/struct-patch/latest/struct_patch/traits/trait.Patch.html#container-attributes -[examples]: /struct-patch/examples +[examples]: /lib/examples diff --git a/complex-example/Cargo.toml b/complex-example/Cargo.toml index c221c03..bfa947c 100644 --- a/complex-example/Cargo.toml +++ b/complex-example/Cargo.toml @@ -9,7 +9,7 @@ struct-patch = { path = "../lib", features = ["catalyst"] } [workspace.package] authors = ["Antonio Yang "] -version = "0.11.0" +version = "0.12.0" edition = "2021" categories = ["development-tools"] keywords = ["struct", "patch", "macro", "derive", "overlay"] diff --git a/lib/Cargo.toml b/lib/Cargo.toml index 7616d8c..176c7a2 100644 --- a/lib/Cargo.toml +++ b/lib/Cargo.toml @@ -12,7 +12,7 @@ readme.workspace = true rust-version.workspace = true [dependencies] -struct-patch-derive = { version = "=0.11.0", path = "../derive" } +struct-patch-derive = { version = "=0.12.0", path = "../derive" } [dev-dependencies] serde_json = "1.0" diff --git a/no-std-examples/Cargo.toml b/no-std-examples/Cargo.toml index 9a6c89e..538ad68 100644 --- a/no-std-examples/Cargo.toml +++ b/no-std-examples/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "no-std-examples" authors = ["Antonio Yang "] -version = "0.11.0" +version = "0.12.0" edition = "2021" license = "MIT" From b72aa992a0fa9d1cd96d78feb7ff30e976b1ac8b Mon Sep 17 00:00:00 2001 From: Antonio Yang Date: Tue, 12 May 2026 19:53:52 +0800 Subject: [PATCH 2/2] ci: fix check-catalyst --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 777fc4b..5d70420 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -75,4 +75,4 @@ jobs: nix develop .#no-std -c cargo run --features=option --bin no-std-option - name: Test with catalyst - nix develop .#ci -c check-catalyst + run: nix develop .#ci -c check-catalyst