22 releases (7 breaking)
0.8.6 | Oct 2, 2024 |
---|---|
0.8.4 | Aug 27, 2024 |
0.6.0 | Jul 29, 2024 |
0.4.1 | Oct 2, 2023 |
0.2.3 | Mar 4, 2023 |
#128 in Encoding
24,761 downloads per month
Used in 2 crates
35KB
743 lines
Struct Patch
A lib help you patch Rust instance, and easy to partial update configures.
Introduction
This crate provides the Patch
trait and an accompanying derive macro.
Deriving Patch
on a struct will generate a struct similar to the original one, but with all fields wrapped in an Option
.
An instance of such a patch struct can be applied onto the original struct, replacing values only if they are set to Some
, leaving them unchanged otherwise.
Quick Example
use struct_patch::Patch;
use serde::{Deserialize, Serialize};
#[derive(Default, Debug, PartialEq, Patch)]
#[patch(attribute(derive(Debug, Default, Deserialize, Serialize)))]
struct Item {
field_bool: bool,
field_int: usize,
field_string: String,
}
fn patch_json() {
let mut item = Item {
field_bool: true,
field_int: 42,
field_string: String::from("hello"),
};
let data = r#"{
"field_int": 7
}"#;
let patch: ItemPatch = serde_json::from_str(data).unwrap();
item.apply(patch);
// You can do
// `let new_item = item << patch;`
// For multiple patches,
// you can do this
// `let new_item = item << patch_1 << patch_2;`
// or make an aggregated one, but please make sure the patch fields do not conflict, else will panic
// ```
// let overall_patch = patch_1 + patch_2 + patch_3;
// let new_item = item << overall_patch;
// ```
assert_eq!(
item,
Item {
field_bool: true,
field_int: 7,
field_string: String::from("hello")
}
);
}
Documentation and Examples
Also, you can modify the patch structure by defining #[patch(...)]
attributes on the original struct or fields.
Struct attributes:
#[patch(name = "...")]
: change the name of the generated patch struct.#[patch(attribute(...))]
: add attributes to the generated patch struct.#[patch(attribute(derive(...)))]
: add derives to the generated patch struct.
Field attributes:
#[patch(skip)]
: skip the field in the generated patch struct.#[patch(name = "...")]
: change the type of the field in the generated patch struct.#[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.
Please check the traits of document to learn more.
The examples demo following scenarios.
- diff two instance for a patch
- create a patch from json string
- rename the patch structure
- check a patch is empty or not
- add attribute to patch struct
- show option field behavior
- show operators about patches
Features
This crate also includes the following optional features:
status
(default): implements thePatchStatus
trait for the patch struct, which provides theis_empty
method.op
(default): provide operators<<
between instance and patch, and+
for patches- default: when there is a field conflict between patches,
+
will add together if the#[patch(addable)]
or#[patch(add=fn)]
is provided, else it will panic. merge
(optional): implements theMerge
trait for the patch struct, which provides themerge
method, and<<
between patches.
- default: when there is a field conflict between patches,
std
(optional):box
: implements thePatch<Box<P>>
trait forT
whereT
implementsPatch<P>
. This let you patch a boxed (or not) struct with a boxed patch.option
: implements thePatch<Option<P>>
trait forOption<T>
whereT
implementsPatch<P>
, please take a look at the example to learn more.- default:
T
needs to implementFrom<P>
. When patching on None, it will based onfrom<P>
to cast T, and this let you patch structs containing fields with optional values. none_as_default
:T
needs to implementDefault
. When patching on None, it will patch on a default instance, and this also let you patch structs containing fields with optional values.keep_none
: When patching on None, it is still None.
- default:
Dependencies
~210–650KB
~15K SLoC