Nondestructive editing tries to preserve as much as possible of the existing structure, while allowing the document to be modified in place.
This project is as of yet, incomplete!
See the corresponding module for detailed documentation on how to use:
A document is deserialized into a large object from which all access and mutation must occur. This makes the API a bit harder to use than your typical serialization library but is necessary to ensure that it has access to all the necessary data to perform nondestructive editing.
One particular complication is that each method which provides mutable
access to the document needs to have two variations: as_<something>_mut
and into_<something>_mut. If we look at [ValueMut::as_mapping_mut] and
[ValueMut::into_mapping_mut] the difference is that the latter consumes
self and returns a [ValueMut] with its associated lifetime.
```rust use anyhow::Context; use nondestructive::yaml;
let mut doc = yaml::from_slice( r#" greeting: Hello World! "# )?;
// Access through the document: asserteq!( doc.asref().asmapping().andthen(|m| m.get("greeting")?.as_str()), Some("Hello World!") );
// Mutation through the document: let mut mapping = doc.asmut().intomappingmut().context("missing root mapping")?; mapping.insertstr("greeting2", "Hello Rust!");
asserteq!( doc.tostring(), r#" greeting: Hello World! greeting2: Hello Rust! "# ); ```
If we were to change the line which uses into_mapping_mut we would get a
lifetime error:
text
error[E0716]: temporary value dropped while borrowed
--> src\lib.rs:43:19
|
20 | let mut mapping = doc.as_mut().as_mapping_mut().context("missing root mapping")?;
| ^^^^^^^^^^^^ - temporary value is freed at the end of this statement
| |
| creates a temporary value which is freed while still in use
21 | mapping.insert_str("greeting2", "Hello Rust!");
| ---------------------------------------------- borrow later used here
|
help: consider using a `let` binding to create a longer lived value
|
20 + let binding = doc.as_mut();
21 ~ let mut mapping = binding.as_mapping_mut().context("missing root mapping")?;
|
We could following the recommendation and assign it to a local variable,
however that wouldn't be possible if we were using helper methods such as
[Option::and_then].
Another important aspect of working with documents is that we can address values globally through identifiers. This makes it easier to store desired modifications in a collection before applying them.
```rust use anyhow::Context; use nondestructive::yaml;
let mut doc = yaml::from_slice( r#" - 10 - 24 - 30 "# )?;
let mut edits = Vec::new();
for value in doc.asref().assequence().context("missing sequence")? { let Some(n) = value.as_u32() else { continue; };
if n % 10 == 0 {
edits.push((value.id(), n / 10));
}
}
// Apply stored edits: for (id, newnumber) in edits { doc.valuemut(id).setu32(newnumber); }
asserteq!( doc.tostring(), r#" - 1 - 24 - 3 "# ); ```
This provides a broader view of the available API, and the difference between accessors and mutators.
```rust use anyhow::Context; use nondestructive::yaml;
let mut doc = yaml::from_slice( r#" name: Descartes country: Grece "# )?;
let mapping = doc.asref().asmapping().context("missing mapping")?; let name = mapping.get("name").context("missing name")?; asserteq!(name.asstr(), Some("Descartes"));
let mut mapping = doc.asmut().intomappingmut().context("missing mapping")?; let mut name = mapping.getmut("name").context("missing name")?; name.set_string("Plato");
let mut country = mapping.getmut("country").context("missing country")?; country.setstring("Greece");
asserteq!( doc.tostring(), r#" name: Plato country: Greece "# ); ```