Struct KdlDocument

Source

pub struct KdlDocument { /* private fields */ }

Expand description

Represents a KDL Document.

This type is also used to manage a KdlNode’s Children Block, when present.

§Examples

The easiest way to create a KdlDocument is to parse it:

let kdl: KdlDocument = "foo 1 2 3\nbar 4 5 6".parse().expect("parse failed");

Implementations§

Source §

impl KdlDocument

Source

pub fn new() -> Self

Creates a new Document.

Source

pub fn span(&self) -> SourceSpan

Available on crate feature span only.

Gets this document’s span.

This value will be properly initialized when created via KdlDocument::parse but may become invalidated if the document is mutated. We do not currently guarantee this to yield any particularly consistent results at that point.

Source

pub fn set_span(&mut self, span: impl Into<SourceSpan>)

Available on crate feature span only.

Sets this document’s span.

Source

pub fn get(&self, name: &str) -> Option<&KdlNode>

Gets the first child node with a matching name.

Source

pub fn get_mut(&mut self, name: &str) -> Option<&mut KdlNode>

Gets a reference to the first child node with a matching name.

Source

pub fn get_arg(&self, name: &str) -> Option<&KdlValue>

Gets the first argument (value) of the first child node with a matching name. This is a shorthand utility for cases where a document is being used as a key/value store.

§Examples

Given a document like this:

foo 1
bar false

You can fetch the value of foo in a single call like this:

assert_eq!(doc.get_arg("foo"), Some(&1.into()));

Source

pub fn iter_args(&self, name: &str) -> impl Iterator<Item = &KdlValue>

Returns an iterator of the all node arguments (value) of the first child node with a matching name. This is a shorthand utility for cases where a document is being used as a key/value store and the value is expected to be array-ish.

If a node has no arguments, this will return an empty array.

§Examples

Given a document like this:

foo 1 2 3
bar #false

You can fetch the arguments for foo in a single call like this:

assert_eq!(
  doc.iter_args("foo").collect::<Vec<&KdlValue>>(),
  vec![&1.into(), &2.into(), &3.into()]
);

Source

pub fn get_arg_mut(&mut self, name: &str) -> Option<&mut KdlValue>

Gets a mutable reference to the first argument (value) of the first child node with a matching name. This is a shorthand utility for cases where a document is being used as a key/value store.

Source

pub fn iter_dash_args(&self, name: &str) -> impl Iterator<Item = &KdlValue>

This utility makes it easy to interact with a KDL convention where child nodes named - are treated as array-ish values.

§Examples

Given a document like this:

foo {
  - 1
  - 2
  - #false
}

You can fetch the dashed child values of foo in a single call like this:

assert_eq!(
    doc.iter_dash_args("foo").collect::<Vec<&KdlValue>>(),
    vec![&1.into(), &2.into(), &false.into()]
);

Source

pub fn nodes(&self) -> &[KdlNode]

Returns a reference to this document’s child nodes.

Source

pub fn nodes_mut(&mut self) -> &mut Vec<KdlNode>

Returns a mutable reference to this document’s child nodes.

Source

pub fn format(&self) -> Option<&KdlDocumentFormat>

Gets the formatting details (including whitespace and comments) for this entry.

Source

pub fn format_mut(&mut self) -> Option<&mut KdlDocumentFormat>

Gets a mutable reference to this entry’s formatting details.

Source

pub fn set_format(&mut self, format: KdlDocumentFormat)

Sets the formatting details for this entry.

Source

pub fn len(&self) -> usize

Length of this document when rendered as a string.

Source

pub fn is_empty(&self) -> bool

Returns true if this document is completely empty (including whitespace)

Source

pub fn clear_format(&mut self)

Clears leading and trailing text (whitespace, comments). KdlNodes in this document will be unaffected.

If you need to clear the KdlNodes, use Self::clear_format_recursive.

Source

pub fn clear_format_recursive(&mut self)

Clears leading and trailing text (whitespace, comments), also clearing all the KdlNodes in the document.

Source

pub fn autoformat(&mut self)

Auto-formats this Document, making everything nice while preserving comments.

Source

pub fn autoformat_no_comments(&mut self)

Formats the document and removes all comments from the document.

Source

pub fn autoformat_config(&mut self, config: &FormatConfig<'_>)

Formats the document according to config.

Source

pub fn parse(s: &str) -> Result<Self, KdlError>

Parses a string into a document.

If the v1-fallback feature is enabled, this method will first try to parse the string as a KDL v2 document, and, if that fails, it will try to parse again as a KDL v1 document. If both fail, a heuristic will be applied to try and detect the “intended” KDL version, and that version’s error(s) will be returned.

Source