#139 Adding documentation for skip_serializing

This commit is contained in:
mracsko 2022-04-07 12:28:47 +02:00
parent 427bab7e34
commit 391d2a0355
2 changed files with 141 additions and 2 deletions

View File

@ -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

139
doc/skip_serializing.md Normal file
View File

@ -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: <?xml version="1.0" encoding="utf-8"?><Struct><do_not_skip_value>not skipped</do_not_skip_value></Struct>
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<String>,
#[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<String>) -> 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: <?xml version=\"1.0\" encoding=\"utf-8\"?><Struct><bool_value>true</bool_value><string_value>testString</string_value><i32_value>10</i32_value><optional_string_value>optionalTestString</optional_string_value><enum_value>Enum2</enum_value></Struct>
println!("{}", yaserde::ser::to_string_with_config(&obj_no_skip, &yaserde_cfg).ok().unwrap());
//Output: <?xml version="1.0" encoding="utf-8"?><Struct><enum_value>Enum1</enum_value></Struct>
//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