Struct kdl::KdlDocument

pub struct KdlDocument { /* private fields */ }

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

impl KdlDocument

pub fn new() -> Self

Creates a new Document.

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

Gets the first child node with a matching name.

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

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

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()));

pub fn get_args(&self, name: &str) -> Vec<&KdlValue>

Gets 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.get_args("foo"), vec![&1.into(), &2.into(), &3.into()]);

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.

pub fn get_dash_vals(&self, name: &str) -> Vec<&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.get_dash_vals("foo"), vec![&1.into(), &2.into(), &false.into()]);

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

Returns a reference to this document’s child nodes.

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

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

pub fn leading(&self) -> Option<&str>

Gets leading text (whitespace, comments) for this KdlDocument.

pub fn set_leading(&mut self, leading: impl Into<String>)

Sets leading text (whitespace, comments) for this KdlDocument.

pub fn trailing(&self) -> Option<&str>

Gets trailing text (whitespace, comments) for this KdlDocument.

pub fn set_trailing(&mut self, trailing: impl Into<String>)

Sets trailing text (whitespace, comments) for this KdlDocument.

pub fn len(&self) -> usize

Length of this document when rendered as a string.

pub fn is_empty(&self) -> bool

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

pub fn clear_fmt(&mut self)

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

pub fn fmt(&mut self)

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

pub fn fmt_no_comments(&mut self)

Formats the document and removes all comments from the document.

Trait Implementations

impl Clone for KdlDocument

fn clone(&self) -> KdlDocument

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KdlDocument

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for KdlDocument

fn default() -> KdlDocument

Returns the “default value” for a type.

impl Display for KdlDocument

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for KdlDocument

type Err = KdlError

The associated error which can be returned from parsing.

fn from_str(input: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl IntoIterator for KdlDocument

type Item = KdlNode

The type of the elements being iterated over.

type IntoIter = IntoIter<<KdlDocument as IntoIterator>::Item, Global>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq<KdlDocument> for KdlDocument

fn eq(&self, other: &KdlDocument) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &KdlDocument) -> bool

This method tests for !=.

impl StructuralPartialEq for KdlDocument