Struct KdlNode

pub struct KdlNode { /* private fields */ }

Represents an individual KDL Node inside a KDL Document.

Implementations

impl KdlNode

pub fn new(name: impl Into<KdlIdentifier>) -> Self

Creates a new KdlNode with a given name.

pub fn name(&self) -> &KdlIdentifier

Gets this node’s name.

pub fn name_mut(&mut self) -> &mut KdlIdentifier

Gets a mutable reference to this node’s name.

pub fn set_name(&mut self, name: impl Into<KdlIdentifier>)

Sets this node’s name.

pub fn span(&self) -> SourceSpan

Gets this node’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 node’s span.

pub fn ty(&self) -> Option<&KdlIdentifier>

Gets the node’s type identifier, if any.

pub fn ty_mut(&mut self) -> &mut Option<KdlIdentifier>

Gets a mutable reference to the node’s type identifier.

pub fn set_ty(&mut self, ty: impl Into<KdlIdentifier>)

Sets the node’s type identifier.

pub fn entries(&self) -> &[KdlEntry]

Returns a reference to this node’s entries (arguments and properties).

pub fn entries_mut(&mut self) -> &mut Vec<KdlEntry>

Returns a mutable reference to this node’s entries (arguments and properties).

pub fn clear_format(&mut self)

Clears leading and trailing text (whitespace, comments), as well as the space before the children block, if any. Individual entries and their formatting will be preserved.

If you want to clear formatting on all children and entries as well, use Self::clear_format_recursive.

pub fn clear_format_recursive(&mut self)

Clears leading and trailing text (whitespace, comments), as well as the space before the children block, if any. Individual entries and children formatting will also be cleared.

pub fn entry(&self, key: impl Into<NodeKey>) -> Option<&KdlEntry>

Fetches an entry by key. Number keys will look up arguments, strings will look up properties.

pub fn entry_mut(&mut self, key: impl Into<NodeKey>) -> Option<&mut KdlEntry>

Fetches a mutable referene to an entry by key. Number keys will look up arguments, strings will look up properties.

pub fn children(&self) -> Option<&KdlDocument>

Returns a reference to this node’s children, if any.

pub fn children_mut(&mut self) -> &mut Option<KdlDocument>

Returns a mutable reference to this node’s children, if any.

pub fn set_children(&mut self, children: KdlDocument)

Sets the KdlDocument representing this node’s children.

pub fn clear_children(&mut self)

Removes this node’s children completely.

pub fn ensure_children(&mut self) -> &mut KdlDocument

Returns a mutable reference to this node’s children KdlDocument, creating one first if one does not already exist.

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

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

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

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

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

Sets the formatting details for this node.

pub fn autoformat(&mut self)

Auto-formats this node and its contents.

pub fn autoformat_no_comments(&mut self)

Auto-formats this node and its contents, stripping comments.

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

Auto-formats this node and its contents according to config.

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

Parses a string into a node.

If the v1-fallback feature is enabled, this method will first try to parse the string as a KDL v2 node, and, if that fails, it will try to parse again as a KDL v1 node. If both fail, only the v2 parse errors will be returned.

pub fn ensure_v2(&mut self)

Makes sure this node is in v2 format.

impl KdlNode

pub fn iter(&self) -> EntryIter<'_>

Returns an iterator over the node’s entries, including properties.

pub fn iter_mut(&mut self) -> EntryIterMut<'_>

Returns a mutable iterator over the node’s entries, including properties.

pub fn iter_children(&self) -> ChildrenIter<'_>

Returns an iterator over the node’s children, if any. Nodes without children will return an empty iterator.

pub fn iter_children_mut(&mut self) -> ChildrenIterMut<'_>

Returns a mutable iterator over the node’s children, if any. Nodes without children will return an empty iterator.

pub fn get(&self, key: impl Into<NodeKey>) -> Option<&KdlValue>

Gets a value by key. Number keys will look up arguments, strings will look up properties.

pub fn get_mut(&mut self, key: impl Into<NodeKey>) -> Option<&mut KdlValue>

Fetches a mutable referene to an value by key. Number keys will look up arguments, strings will look up properties.

pub fn len(&self) -> usize

Number of entries in this node.

pub fn is_empty(&self) -> bool

Returns true if this node is completely empty (including whitespace).

pub fn clear(&mut self)

Shorthand for self.entries_mut().clear()

pub fn push(&mut self, entry: impl Into<KdlEntry>)

Shorthand for self.entries_mut().push(entry).

pub fn insert( &mut self, key: impl Into<NodeKey>, entry: impl Into<KdlEntry>, ) -> Option<KdlEntry>

Inserts an entry into this node. If an entry already exists with the same string key, it will be replaced and the previous entry will be returned.

Numerical keys will insert arguments, string keys will insert properties.

pub fn remove(&mut self, key: impl Into<NodeKey>) -> Option<KdlEntry>

Removes an entry from this node. If an entry already exists with the same key, it will be returned.

Numerical keys will remove arguments, string keys will remove properties.

pub fn retain<F>(&mut self, keep: F)

where F: FnMut(&KdlEntry) -> bool,

Retains only the elements specified by the predicate.

pub fn sort_by<F>(&mut self, compare: F)

where F: FnMut(&KdlEntry, &KdlEntry) -> Ordering,

Sorts the slice with a comparison function, preserving initial order of equal elements.

pub fn sort_by_key<K, F>(&mut self, f: F)

where F: FnMut(&KdlEntry) -> K, K: Ord,

Sorts the slice with a key extraction function, preserving initial order of equal elements.

Trait Implementations

impl Clone for KdlNode

fn clone(&self) -> KdlNode

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for KdlNode

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

Formats the value using the given formatter.

impl Display for KdlNode

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

Formats the value using the given formatter.

impl FromStr for KdlNode

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 Hash for KdlNode

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 Index<&str> for KdlNode

type Output = KdlValue

The returned type after indexing.

fn index(&self, key: &str) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<usize> for KdlNode

type Output = KdlValue

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl IndexMut<&str> for KdlNode

fn index_mut(&mut self, key: &str) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<usize> for KdlNode

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl PartialEq for KdlNode

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 KdlNode