YamlNode
OfficeIMO.Yaml
A node of a YamlDocument: a YamlScalar, YamlMapping, YamlSequence or YamlAlias. Loaded nodes are views over the retained source text: they store offsets, not copies, and decode values only when asked. Nodes created by editing hold their values directly.
Inheritance
- object
- YamlNode
Derived Types
Remarks
Typed reads (, , and the others) look through aliases to the anchored node; the tree itself keeps every alias as a . Reading never changes the source text. Editing changes only what it touches. Saving copies every untouched node from the source and writes only the edited ones, so comments, quoting, indentation and spellings such as TRUE survive everywhere else. Methods that configure a node return it, so calls chain: mapping.Add("image", "nginx").SetComment("pinned by CI"). A loaded document can be read from several threads at once. Lazily built caches (decoded values, key indexes, positions) are computed idempotently. Editing is not thread-safe.
Usage
Explore 69 API references to this type
This type appears in these public API surfaces even when no hand-authored example is attached directly to the page.
Returned or exposed by 55
- Method YamlAlias.Select
- Method YamlAlias.SetAnchor
- Method YamlAlias.SetComment
- Method YamlAlias.SetCommentBefore
- Method YamlAlias.SetSpaceBefore
- Method YamlAlias.SetTag
- Property YamlAlias.Parent
- Property YamlAlias.Target
- Method YamlDocument.Add
- Method YamlDocument.Select
- Method YamlDocument.Set
- Property YamlDocument.Root
- Property YamlDocumentPart.Root
- Method YamlMapping.Add
- Method YamlMapping.Insert
- Method YamlMapping.Select
- Method YamlMapping.Set
- Method YamlMapping.SetAnchor
- Method YamlMapping.SetComment
- Method YamlMapping.SetCommentBefore
- Method YamlMapping.SetSpaceBefore
- Method YamlMapping.SetTag
- Property YamlMapping.Item
- Property YamlMapping.Parent
- Property YamlMappingEntry.Key
- Property YamlMappingEntry.Value
- Method YamlNode.op_Implicit
- Method YamlNode.Select
- Method YamlNode.SetAnchor
- Method YamlNode.SetComment
- Method YamlNode.SetCommentBefore
- Method YamlNode.SetSpaceBefore
- Method YamlNode.SetTag
- Property YamlNode.Parent
- Property Enumerator.Current
- Method YamlScalar.Select
- Method YamlScalar.SetAnchor
- Method YamlScalar.SetComment
- Method YamlScalar.SetCommentBefore
- Method YamlScalar.SetSpaceBefore
- Method YamlScalar.SetTag
- Property YamlScalar.Parent
- Method YamlSequence.Add
- Method YamlSequence.Insert
- Method YamlSequence.Select
- Method YamlSequence.SetAnchor
- Method YamlSequence.SetComment
- Method YamlSequence.SetCommentBefore
- Method YamlSequence.SetSpaceBefore
- Method YamlSequence.SetTag
- Property YamlSequence.Item
- Property YamlSequence.Parent
- Property Enumerator.Current
- Method YamlSerializer.SerializeToNode
- Method YamlSerializer.SerializeToNode``1
Accepted by parameters 14
- Constructor YamlAlias.YamlAlias
- Method YamlDocument.Add
- Method YamlDocument.AddDocument
- Method YamlDocument.Set
- Method YamlMapping.Add
- Method YamlMapping.Add
- Method YamlMapping.Insert
- Method YamlMapping.Insert
- Method YamlMapping.Set
- Method YamlMapping.TryGetValue
- Method YamlSequence.Add
- Method YamlSequence.Insert
- Method YamlSerializer.Deserialize
- Method YamlSerializer.Deserialize``1
Methods
public YamlMapping AsMapping() #Returns the mapping this node is, or the mapping an alias refers to.
Returns
YamlMappingExceptions
InvalidOperationException– The node is a scalar or sequence.
public YamlScalar AsScalar() #Returns the scalar this node is, or the scalar an alias refers to.
Returns
YamlScalarExceptions
InvalidOperationException– The node is a mapping or sequence.
public YamlSequence AsSequence() #Returns the sequence this node is, or the sequence an alias refers to.
Returns
YamlSequenceExceptions
InvalidOperationException– The node is a scalar or mapping.
public string AsString() #Returns the scalar's decoded text (folding, escapes and block chomping applied) whatever it resolves to, so ~ returns "~" and 0x1F returns "0x1F". Use YamlNode.GetValue for typed values.
Returns
stringExceptions
InvalidOperationException– The node is a mapping or sequence.
public YamlNodeWalk Descendants() #Enumerates this node and every node below it, depth first in document order: for a mapping, each key and then its value. Aliases are returned as themselves and not followed. The walk keeps one small stack and allocates nothing per node.
Returns
YamlNodeWalkpublic string GetPath() #Returns the path of this node from its document root, in the grammar YamlNode.Select reads.
Returns
stringExceptions
InvalidOperationException– The node is a mapping key; paths address values.
public T? GetValue<T>() #Reads the scalar as T through its document's schema. Supported types are string, bool, int, long, double, float, decimal and their nullable forms. A null scalar reads as null for string and nullable types. A string read returns the text of any non-null scalar, including custom-tagged ones.
Type Parameters
- T
Returns
T?Exceptions
InvalidOperationException– The node is a mapping or sequence.FormatException– The scalar does not resolve to T.NotSupportedException– T is not a supported type.
public static YamlNode op_Implicit(string? value) #Creates a string scalar; its style is chosen from its context when it joins a document.
Parameters
- value string?
Returns
YamlNodepublic static YamlNode op_Implicit(long value) #Creates an integer scalar.
Parameters
- value long
Returns
YamlNodepublic static YamlNode op_Implicit(double value) #Creates a floating-point scalar.
Parameters
- value double
Returns
YamlNodepublic YamlNode? Select(string path) #Returns the node a path addresses from here, or null when nothing matches. Paths share their grammar with the paths OfficeIMO.Reader.Yaml reports: .name selects a mapping value by key text. A name runs to the next . or [ and may contain any other character, spaces included; the leading dot of the first step may be omitted (spec.replicas). ["key"] selects any key, and is needed for keys that contain . or [, are empty, or start with $. The text is JSON-quoted: \", \\, \/, \b, \f, \n, \r, \t and \uXXXX (labels["app.kubernetes.io/name"], ["say \"hi\""]). [n] selects the zero-based item of a sequence. A mapping key that is a number is a key step: .0 or ["0"]. A leading $ stands for this node. On a with several documents, a leading $[n] picks the document. Key steps compare the step text with each scalar key's decoded value, whatever its style or type: 'a', "a" and a are all .a, and the integer key 0x1F is .0x1F. They follow aliases and << merge keys where merges apply. When no scalar key matches, a step matches a collection key by its YAML text, the form returns and OfficeIMO.Reader.Yaml reports: ["[a, b]"] for [a, b]: x. Keys with equal text resolve as lookups do, by the duplicate-key policy (by default the last); enumerate entries to reach the others, such as 1 next to "1". Paths address nodes; they do not evaluate expressions or wildcards. returns the path of a node, and , and edit by the same paths.
Parameters
- path string
Returns
YamlNode?Exceptions
ArgumentNullException– path is null.ArgumentException– path is malformed.
public YamlNode SetAnchor(string? name) #Sets, renames or removes (null) the node's anchor. Renaming updates every alias that refers to the node; removing an anchor that aliases still use fails.
Parameters
- name string?
Exceptions
ArgumentException– The name is not a valid anchor, or another node of the document already uses it.InvalidOperationException– The node is an alias, or aliases refer to the anchor being removed.
public YamlNode SetComment(string? text) #Sets the comment at the end of the node's line (value # text), or removes it with null.
Parameters
- text string?
Exceptions
ArgumentException– The text contains a line break.InvalidOperationException– The node has no line of its own: a block collection that is a sequence item or the root, a key whose value starts on its line, or a node inside a flow collection.
public YamlNode SetCommentBefore(string? text) #Replaces the comment lines above the node's entry; each line of text becomes one # line comment at the entry's indentation. null or an empty string removes them.
Parameters
- text string?
Exceptions
InvalidOperationException– The node is inside a flow collection, where comment lines cannot be placed.
public YamlNode SetSpaceBefore(bool value) #Sets whether a blank line separates the node's entry from the previous content.
Parameters
- value bool
Exceptions
InvalidOperationException– The node is inside a flow collection.
public YamlNode SetTag(string? tag) #Sets or removes (null) the node's tag, in the resolved form YamlNode.Tag reports (tag:yaml.org,2002:str, !Ref). Tags change how a scalar resolves; they never activate .NET types.
Parameters
- tag string?
Exceptions
InvalidOperationException– The node is an alias.
public override string ToString() #Returns the node's YAML text: its source text for a loaded, unchanged node, otherwise the text saving would write for it on its own.
Returns
stringpublic bool TryGetValue<T>(out T? value) #Tries to read the node as T through its document's schema, with the conversions of YamlNode.GetValue. Returns false for collections and for scalars that do not resolve.
Type Parameters
- T
Parameters
- value T?
Returns
boolExceptions
NotSupportedException– T is not a supported type.
Inherited Methods
Properties
public YamlStyle Style { get; } #Gets the presentation style: YamlStyle.Plain, a quoted or block scalar style, or YamlStyle.Block/YamlStyle.Flow for collections. Aliases report YamlStyle.None, and so does a new string scalar until it joins a document, which picks its style from its context.
public string? Tag { get; } #Gets the node's resolved tag (!!str becomes tag:yaml.org,2002:str, !Ref stays !Ref), or null when it has none. Custom tags are kept verbatim and never fail a load.
public string? Anchor { get; } #Gets the anchor name (without &) defined on this node, or null.
public YamlNode? Parent { get; } #Gets the mapping or sequence that holds the node, or null for a document root or a node not in a document.
public YamlPosition Start { get; } #Gets where the node starts in the loaded source, with its offset and one-based line and column: its first property (anchor or tag) when present, otherwise its content. Nodes whose content comes from editing (created, re-valued or moved) have no source position and return the default value, whose YamlPosition.Line is 0.
public YamlPosition End { get; } #Gets where the node ends in the loaded source. A block collection ends where its last content ends; an empty node is zero-width at the point where the omitted node would be. Nodes created by editing return the default value.
public bool IsModified { get; } #Gets whether editing changed the node or anything inside it since the document was loaded: its value, anchor, tag or comments, or a descendant's, or entries or items added or removed. It is true for nodes created by editing, and false for an untouched loaded node, whose source text between YamlNode.Start and YamlNode.End is what saving writes for it.
public bool IsNull { get; } #Gets whether the node resolves to null under its document's schema: an untagged plain scalar such as null, ~ or an empty node (core schema), or a scalar tagged !!null. Aliases answer for their anchored node; collections and quoted scalars are never null.
public string? CommentBefore { get; } #Gets the comment lines above the node's entry, joined with line breaks, without their # and one following space; null when there are none.
public string? Comment { get; } #Gets the comment at the end of the node's line, without its # and one following space, or null. A block scalar's comment is the one on its header line (key: | # comment); a block collection that is a mapping value reports its key's line (key: # comment). Other block collections have no line of their own: the comment after their last line belongs to the innermost node ending there. A key whose value starts on the same line has none; the comment after that value is the value's.
public bool SpaceBefore { get; } #Gets whether a blank line separates the node's entry from the previous content, above any YamlNode.CommentBefore lines. Mapping values and first entries share this with the same nodes as YamlNode.CommentBefore.