nondestructive

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:

• YAML support.

Working with documents

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.

use anyhow::Context;
use nondestructive::yaml;

let mut doc = yaml::from_slice(
    r"
    greeting: Hello World!
    "
)?;

// Access through the document:
assert_eq!(
    doc.as_ref().as_mapping().and_then(|m| m.get("greeting")?.as_str()),
    Some("Hello World!")
);

// Mutation through the document:
let mut mapping = doc.as_mut().into_mapping_mut().context("missing root mapping")?;
mapping.insert_str("greeting2", "Hello Rust!");

assert_eq!(
    doc.to_string(),
    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:

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 follow the recommendation and assign it to a local variable, however that wouldn't be possible if we were using combinators 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 before applying them.

use anyhow::Context;
use nondestructive::yaml;

let mut doc = yaml::from_slice(
    r"
    - 10
    - 24
    - 30
    "
)?;

let mut edits = Vec::new();

// Build a collection of edits:
for value in doc.as_ref().as_sequence().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, new_number) in edits {
    doc.value_mut(id).set_u32(new_number);
}

assert_eq!(
    doc.to_string(),
    r"
    - 1
    - 24
    - 3
    "
);

Examples

This provides a broader view of the available API, and the difference between accessors and mutators.

use anyhow::Context;
use nondestructive::yaml;

let mut doc = yaml::from_slice(
    r"
    name: Descartes
    country: Grece
    "
)?;

let mapping = doc.as_ref().as_mapping().context("missing mapping")?;
let name = mapping.get("name").context("missing name")?;
assert_eq!(name.as_str(), Some("Descartes"));

let mut mapping = doc.as_mut().into_mapping_mut().context("missing mapping")?;
let mut name = mapping.get_mut("name").context("missing name")?;
name.set_string("Plato");

let mut country = mapping.get_mut("country").context("missing country")?;
country.set_string("Greece");

assert_eq!(
    doc.to_string(),
    r"
    name: Plato
    country: Greece
    "
);