Trait Document 

pub trait Document {
    // Required methods
    fn to_source(&self) -> String;
    fn to_value(&self) -> Value;
    fn features(&self) -> &'static [Feature];
    fn apply(&mut self, expr: &Expr) -> Result<Vec<String>, EditError>;
    fn has_comments(&self) -> bool;

    // Provided methods
    fn to_values(&self) -> Vec<Value> { ... }
    fn to_commented(&self) -> Option<Commented> { ... }
    fn to_commented_all(&self) -> Vec<Commented> { ... }
    fn source_slice(&self, path: &[Step]) -> Vec<String> { ... }
    fn inner_format(&self) -> Option<&'static str> { ... }
    fn set_comment(
        &mut self,
        path: &[Step],
        kind: CommentKind,
        text: &str,
    ) -> Result<Vec<String>, EditError> { ... }
    fn delete_comment(
        &mut self,
        path: &[Step],
        kind: CommentKind,
    ) -> Result<(), EditError> { ... }
    fn set_comment_in_doc(
        &mut self,
        doc: usize,
        path: &[Step],
        kind: CommentKind,
        text: &str,
    ) -> Result<Vec<String>, EditError> { ... }
}

A parsed config document.

Each format module implements this over its own lossless CST. It is the interface the CLI drives, uniform across JSONC/INI/env: serialize losslessly, project to the Value model for querying/conversion, and report the format’s Feature set.

Mutation (set/delete/append) will extend this trait with M2; for now it covers the read/query path.

Required Methods

fn to_source(&self) -> String

Byte-identical serialization for an unedited document (the round-trip invariant). Reflects in-place edits once mutation lands.

fn to_value(&self) -> Value

Project to the value model for querying and conversion. Trivia (comments, layout) is dropped; this is the data-model view, not the source view.

fn features(&self) -> &'static [Feature]

The format’s capabilities.

fn apply(&mut self, expr: &Expr) -> Result<Vec<String>, EditError>

Apply a mutation expression (assignment / del) in place, format-preserving. Query expressions should be evaluated against Document::to_value instead; use Expr::is_mutation to choose. Returns any non-fatal warnings (e.g. a multi-document select predicate that could not be evaluated against some document, so that document was skipped) for the CLI to surface; an empty vec on a clean edit.

fn has_comments(&self) -> bool

Whether the source contains any comments; used to warn on conversion, which drops them.

Provided Methods

fn to_values(&self) -> Vec<Value>

Project to one value per top-level document. Only YAML has a multi-document stream (----separated); every other format is a single document, so the default is [to_value()]. The CLI evaluates a query against each in turn and concatenates the results, so .kind over a multi-doc stream yields one result per document.

fn to_commented(&self) -> Option<Commented>

Project to the comment-annotated value model (Commented) so conversion can carry comments across formats. Shape and order must match Document::to_value exactly (same keys, same merge/resolution rules) - the CLI pairs the two projections by position. None means the format doesn’t extract comments; conversion then falls back to the plain value path and warns that comments were dropped.

fn to_commented_all(&self) -> Vec<Commented>

One comment-annotated projection per top-level document (the comment analogue of Document::to_values). Only YAML has multiple; the default is the single Document::to_commented, so a comment query maps over every document of a multi-document stream.

fn source_slice(&self, path: &[Step]) -> Vec<String>

The original source text of each node selected by path, in document order (aligned 1:1 with crate::eval’s results for the same path). This is the format-preserving “get”: a structural query returns the exact bytes

• comments, indentation, quoting - rather than a re-serialized value.

The default returns empty, meaning “this format doesn’t source-slice”; the caller then falls back to emitting the value in the target format. Only formats with structural values (JSONC, YAML) need override it.

fn inner_format(&self) -> Option<&'static str>

The name of the format a query should default its output to, when this document’s own format isn’t itself emittable. A lens (frontmatter) is not an output format, so a query over it renders in the underlying block’s format ("yaml"/"toml"/"json") instead. None (the default) means “my own format is the natural output”: the ordinary case.

fn set_comment( &mut self, path: &[Step], kind: CommentKind, text: &str, ) -> Result<Vec<String>, EditError>

Set the kind comment on the node at path to text (raw, unwrapped), format-preserving: only that comment’s bytes change, or one comment line is inserted. Multi-line head/foot text is wrapped to the document’s envelope by the implementation. Returns any warnings (a layout that had to expand to hold the comment, or a kind remapped to one the format supports). The default rejects; comment editing is added per format.

fn delete_comment( &mut self, path: &[Step], kind: CommentKind, ) -> Result<(), EditError>

Delete the kind comment on the node at path (a miss is a no-op). The default rejects; added per format alongside Document::set_comment.

fn set_comment_in_doc( &mut self, doc: usize, path: &[Step], kind: CommentKind, text: &str, ) -> Result<Vec<String>, EditError>

Set the kind comment at path, scoped to a single document of a multi-document stream (used by bulk comments |= f, where each new comment derives from that comment’s own text and so must not leak across documents). Single-document formats have one document, so the default ignores doc and sets it the ordinary way.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Document for Env