diff --git a/README.md b/README.md index 4120e54..d65d14c 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,8 @@ This library will support XML de/ser-ializing with all specific features. - [x] **namespace**: defines the namespace of the field - [x] **rename**: be able to rename a field - [x] **root**: rename the based element. Used only at the XML root. -- [x] **skip_serializing**: Exclude this field from the serialized output -- [x] **skip_serializing_if**: Skip the serialisation for this field if the condition is true +- [x] **skip_serializing**: Exclude this field from the serialized output. [More details...](doc/skip_serializing.md) +- [x] **skip_serializing_if**: Skip the serialisation for this field if the condition is true. [More details...](doc/skip_serializing.md) - [x] **text**: this field match to the text content ## Custom De/Ser-rializer diff --git a/doc/skip_serializing.md b/doc/skip_serializing.md new file mode 100644 index 0000000..e3ecfc6 --- /dev/null +++ b/doc/skip_serializing.md @@ -0,0 +1,139 @@ +# Skip Serializing + +## skip_serializing + +Attribute `skip_serializing_if` will skip the serialisation of the field if it is set to `true`. Default value is `false`. + +- `#[yaserde(skip_serializing = true)]` - Skip serialization of the field. +- `#[yaserde(skip_serializing = false)]` - The field will be serialized. Default value. +- Not set - The field will be serialized (same as `false`). + +### Full example + +```rust +use yaserde_derive::YaSerialize; + +#[derive(YaSerialize, PartialEq, Debug)] +struct Struct { + #[yaserde(skip_serializing = true)] + skip_value: String, + do_not_skip_value: String, +} + +fn main() { + let obj = Struct { + skip_value: "skipped".to_string(), + do_not_skip_value: "not skipped".to_string() + }; + + let yaserde_cfg = yaserde::ser::Config::default(); + + //Output: not skipped + print!("{}", yaserde::ser::to_string_with_config(&obj, &yaserde_cfg).ok().unwrap()); +} +``` + +## skip_serializing_if + +Attribute `skip_serializing_if` will skip the serialisation for this field if the condition is true. + +To conditionally skip serialization of a field a string needs to be set to `skip_serializing_if`, that refers to a +function name, implemented on for the struct. This function has one parameter (reference to the field value) and returns a `bool` value. +```rust +use yaserde_derive::YaSerialize; + +#[derive(YaSerialize, PartialEq, Debug)] +struct Struct { + #[yaserde(skip_serializing_if = "check_string")] + string_value: String, + + //... +} + +impl Struct { + // Skip serializing the field if the value is 'unset'. + fn check_string(&self, value: &str) -> bool { + value == "unset" + } + + //... +} +``` + +### Full example + +```rust +use yaserde_derive::YaSerialize; + +#[derive(YaSerialize, PartialEq, Debug)] +enum Enum { + Enum1, + Enum2, +} + +#[derive(YaSerialize, PartialEq, Debug)] +struct Struct { + #[yaserde(skip_serializing_if = "check_bool")] + bool_value: bool, + #[yaserde(skip_serializing_if = "check_string")] + string_value: String, + #[yaserde(skip_serializing_if = "check_i32")] + i32_value: i32, + #[yaserde(skip_serializing_if = "check_optional_string")] + optional_string_value: Option, + #[yaserde(skip_serializing_if = "check_enum")] + enum_value: Enum, +} + +impl Struct { + fn check_bool(&self, value: &bool) -> bool { + value == &false + } + + fn check_string(&self, value: &str) -> bool { + value == "unset" + } + + fn check_i32(&self, value: &i32) -> bool { + value < &10 + } + + fn check_optional_string(&self, value: &Option) -> bool { + value == &Some("unset".to_string()) + } + + fn check_enum(&self, value: &Enum) -> bool { + value == &Enum::Enum1 + } +} + +fn main() { + let obj_no_skip = Struct { + bool_value: true, + string_value: "testString".to_string(), + i32_value: 10, + optional_string_value: Some("optionalTestString".to_string()), + enum_value: Enum::Enum2, + }; + + let obj_skip_all = Struct { + bool_value: false, + string_value: "unset".to_string(), + i32_value: 9, + optional_string_value: Some("unset".to_string()), + enum_value: Enum::Enum1, + }; + + let yaserde_cfg = yaserde::ser::Config::default(); + + //Output: truetestString10optionalTestStringEnum2 + println!("{}", yaserde::ser::to_string_with_config(&obj_no_skip, &yaserde_cfg).ok().unwrap()); + + //Output: Enum1 + //Known issue, enum fields are not working as expected, see: https://github.com/media-io/yaserde/issues/139 + println!("{}", yaserde::ser::to_string_with_config(&obj_skip_all, &yaserde_cfg).ok().unwrap()); +} +``` + +### Known issues +- Currently, `enum` fields are not working with `skip_serializing_if`: https://github.com/media-io/yaserde/issues/139 \ No newline at end of file