Recursive AI

Find which YAML node owns a comment in Rust

oneyaml is a free, open-source YAML library for Rust from Recursive AI. MIT or Apache-2.0, no unsafe code.

Use explain_comment to see whether a note belongs to the map above it or the key below it.

Terminal
cargo add oneyaml
RUST
use oneyaml::{CommentOwner, Document};
 
fn main() {
    let yaml = concat!(
        "web:\n  port: 8080\n  # proxy note\n",
        "jobs: 2\n",
    );
    let doc = Document::parse(yaml)
        .expect("valid YAML");
    let info = doc.explain_comment(
        doc.comment_ids()[0]
    ).expect("explain comment");
    let web = doc.get("web").expect("web map");
    assert_eq!(info.owner(),
        CommentOwner::Footer(web.id()));
    println!("{}: footer of web", info.text());
    println!("Rule {}", info.rule().number());
}

Unzip the example, then cargo run.

Requires Rust 1.85 or later. The snippet identifies the owner and attachment rule:

Text
# proxy note: footer of web
Rule 6

The full program

The full program also adds # worker count on the jobs line, checks that it belongs to jobs, and prints the rule summary for both comments. explain_comment returns EditError::StaleNode if the ID refers to a comment removed by an edit or to another document.

RUST
use oneyaml::{CommentOwner, Document};
 
fn main() {
    let yaml = concat!(
        "web:\n  port: 8080\n  # proxy note\n",
        "jobs: 2 # worker count\n",
    );
    let doc = Document::parse(yaml)
        .expect("valid YAML");
    let info = doc.explain_comment(
        doc.comment_ids()[0]
    ).expect("explain comment");
    let web = doc.get("web").expect("web map");
    assert_eq!(info.owner(),
        CommentOwner::Footer(web.id()));
    println!("{}: footer of web", info.text());
    println!("Rule {}", info.rule().number());
 
    let jobs = doc.get("jobs").expect("jobs value")
        .key().expect("jobs key").id();
    let trailing = doc.explain_comment(doc.comment_ids()[1])
        .expect("explain worker count");
    assert_eq!(trailing.owner(), CommentOwner::Trailing(jobs));
 
    // Inspect the explanation for each comment in the document.
    for info in doc.explain_comments().expect("explain all comments") {
        println!("{}: {}", info.text(), info.rule().summary());
    }
}

cargo run prints:

Text
# proxy note: footer of web
Rule 6
# proxy note: collection footer: after the last child, deeper than what follows
# worker count: trailing: after content on its line

The short answer

Call doc.explain_comment(id) before editing. Its owner() says which node or document boundary owns the comment, and rule() says why. Here the # proxy note line is indented under web. The explanation is Footer(web.id()), rule 6. The note doesn’t lead jobs, even though jobs is the next key in the text.

What are the rules for indentation in YAML comments?

YAML itself doesn’t attach comments to nodes; the rules here are oneyaml-rust’s. In oneyaml-rust, an own-line comment after the last child of a block collection, farther right than the content that comes next, can be the footer of that collection. In this example, port is the last child of web, the note starts two spaces in, and jobs starts at the left margin. That’s the shape covered by rule 6 in the comment attachment rules.

Here, footer means a comment owned by the end of the nested collection, not by the end of the whole file. A same-line comment after port: 8080 would instead be trailing on that mapping entry (rule 5). Comparing the rule and owner is more reliable than guessing from the closest line when a note sits between two sections.

How can you tell whether a YAML comment belongs to a key or to the whole map?

Look at owner() first. For a mapping entry, Leading(id) or Trailing(id) names the key node. Footer(id) names the collection itself. DocumentHeader and DocumentFooter don’t name a node. For diagnostics, the explanation also gives the comment text, its UTF-8 byte span, and an optional span for the owner. Use those spans if you need to highlight the two locations in the same source, rather than searching for a matching fragment of text.

All oneyaml Rust recipes