Struct 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 span(&self) -> SourceSpan

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.

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

Sets this document’s span.

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

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

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 format(&self) -> Option<&KdlDocumentFormat>

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

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

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

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

Sets the formatting details for this entry.

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_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.

pub fn clear_format_recursive(&mut self)

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

pub fn autoformat(&mut self)

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

pub fn autoformat_no_comments(&mut self)

Formats the document and removes all comments from the document.

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

Formats the document according to config.

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.

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

Parses a KDL v2 string into a document.

pub fn ensure_v2(&mut self)

Makes sure this document is in v2 format.

Trait Implementations

impl Clone for KdlDocument

fn clone(&self) -> KdlDocument

Returns a duplicate 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() -> Self

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(s: &str) -> Result<Self, Self::Err>

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

impl Hash for KdlDocument

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoIterator for KdlDocument

type Item = KdlNode

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for KdlDocument

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for KdlDocument