YamlDocument
OfficeIMO.Yaml
A YAML file or stream loaded into a lossless model: every document, node, comment, blank line and spelling of the input is kept, and saving an unchanged document reproduces the input byte for byte, including its encoding and byte-order mark.
Inheritance
- object
- YamlDocument
Remarks
The document retains its decoded source text once; nodes are offsets into it, so a node costs about one object and comments and whitespace cost nothing until asked for. Values are decoded lazily and cached. Loading enforces the limits in , including the alias-expansion bound that stops "billion laughs" inputs, and resolves every alias to its anchor. Malformed input throws .
Usage
Explore 5 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 4
- Method YamlDocument.Create
- Method YamlDocument.Load
- Method YamlDocument.LoadAsync
- Method YamlDocument.Parse
Accepted by parameters 1
- Method YamlDocument.Merge
Methods
public YamlNode Add(string path, YamlNode? value) #Appends a value to the sequence at a path, creating the sequence and missing mappings on the way.
Parameters
- path string
- value OfficeIMO.Yaml.YamlNode?
Exceptions
InvalidOperationException– The path addresses something other than a sequence, or goes through a scalar.
public YamlDocumentPart AddDocument(YamlNode root) #Adds a document with the given root at the end of the stream, after a --- marker when it is not the first.
Parameters
- root OfficeIMO.Yaml.YamlNode
public static YamlDocument Create() #Creates an empty document in memory, with no YAML documents in its stream. Set YamlDocument.Root, call YamlDocument.Set with a path, or YamlDocument.AddDocument to give it content; saving writes UTF-8 without a byte-order mark.
Returns
YamlDocumentExamples
using var doc = YamlDocument.Create();
doc.Set("name", "web");
doc.Set("spec.replicas", 3);
doc.Add("spec.ports", 80);
doc.Save("service.yaml");public static YamlDocument Create(string path) #Creates an empty document in memory associated with a path, without writing a file. YamlDocument.Save writes it there.
Parameters
- path string
- The file the document will be saved to.
Returns
YamlDocumentpublic void Dispose() #Returns the document's pooled storage: its node table and, for a document loaded from a file or stream, its input bytes. The document holds only managed memory. Do not use the document after disposing it: nodes reached before keep their values, and reaching any other node throws ObjectDisposedException.
public static YamlDocument Load(string path, YamlLoadOptions? options = null, CancellationToken cancellationToken = default) #Loads a YAML file. The encoding (UTF-8, UTF-16 or UTF-32, either byte order) is detected from a byte-order mark or the first bytes as the YAML specification requires, and recorded so YamlDocument.Save reproduces it.
Parameters
- path string
- The file to read.
- options OfficeIMO.Yaml.YamlLoadOptions? = null
- Load settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Observed while reading and, at bounded intervals, while parsing.
Returns
YamlDocumentExceptions
YamlException– The input is malformed, not valid in its encoding, or exceeds a limit.
public static YamlDocument Load(Stream stream, YamlLoadOptions? options = null, CancellationToken cancellationToken = default) #Loads YAML from a caller-owned stream, reading from its current position to the end. The encoding is detected as for YamlDocument.Load. The stream is not disposed.
Parameters
- stream System.IO.Stream
- A readable stream.
- options OfficeIMO.Yaml.YamlLoadOptions? = null
- Load settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Observed between reads and, at bounded intervals, while parsing.
Returns
YamlDocumentExceptions
YamlException– The input is malformed, not valid in its encoding, or exceeds a limit.
public static async Task<YamlDocument> LoadAsync(string path, YamlLoadOptions? options = null, CancellationToken cancellationToken = default) #Loads a YAML file asynchronously; see YamlDocument.Load.
Parameters
- path string
- The file to read.
- options OfficeIMO.Yaml.YamlLoadOptions? = null
- Load settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Observed while reading and, at bounded intervals, while parsing.
Returns
Task<YamlDocument>Exceptions
YamlException– The input is malformed, not valid in its encoding, or exceeds a limit.
public static async Task<YamlDocument> LoadAsync(Stream stream, YamlLoadOptions? options = null, CancellationToken cancellationToken = default) #Loads YAML from a caller-owned stream asynchronously; see YamlDocument.Load.
Parameters
- stream System.IO.Stream
- A readable stream. It is not disposed.
- options OfficeIMO.Yaml.YamlLoadOptions? = null
- Load settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Observed while reading and, at bounded intervals, while parsing.
Returns
Task<YamlDocument>Exceptions
YamlException– The input is malformed, not valid in its encoding, or exceeds a limit.
public YamlMergeReport Merge(YamlDocument overlay, YamlMergeOptions? options = null) #Deep-merges an overlay document into this one, document part by part in order, the way Helm combines values files. Mappings merge key by key; overlay scalars are assigned, so an equal value keeps this document's spelling; sequences follow YamlMergeOptions.Sequences; new keys are appended with the overlay's comments in this document's layout. When a value changes kind (a mapping over a scalar, for example) the overlay wins and the conflict is reported. The overlay is not changed, and saving writes only what the merge touched.
Parameters
- overlay OfficeIMO.Yaml.YamlDocument
- options OfficeIMO.Yaml.YamlMergeOptions? = null
Exceptions
ArgumentNullException– overlay is null.ArgumentException– overlay is this document.
Examples
using var values = YamlDocument.Load("values.yaml");
using var production = YamlDocument.Load("values.prod.yaml");
YamlMergeReport report = values.Merge(production, new YamlMergeOptions { NullRemovesKey = true });
values.Save("values.merged.yaml");public static YamlDocument Parse(string yaml, YamlLoadOptions? options = null, CancellationToken cancellationToken = default) #Parses YAML text. The text is retained as is, so YamlDocument.ToString returns it unchanged and YamlDocument.Save writes it as UTF-8 without adding a byte-order mark.
Parameters
- yaml string
- The YAML text.
- options OfficeIMO.Yaml.YamlLoadOptions? = null
- Load settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Checked at bounded intervals while parsing.
Returns
YamlDocumentExceptions
YamlException– The input is malformed or exceeds a limit.
public bool Remove(string path) #Removes the mapping entry or sequence item a path addresses, with its comment lines and its line.
Parameters
- path string
Returns
bool true when something was removed; false when nothing is at the path.Exceptions
ArgumentException– The path is malformed or addresses a document root.InvalidOperationException– The path goes through a scalar, or aliases refer to an anchor inside the removed node.
public void Save() #Saves the document to its YamlDocument.FilePath, in the encoding it was loaded with. Untouched text is copied from the source; only edited nodes are written anew.
Exceptions
InvalidOperationException– The document has no associated path.
public void Save(string path, YamlSaveOptions? options = null) #Saves the document to a file in the encoding it was loaded with, writing its byte-order mark when the input had one, and makes the file its YamlDocument.FilePath. The file is replaced atomically, so a failed save leaves the old contents. An unchanged document reproduces the loaded bytes exactly; an edited one changes only the edited nodes' text.
Parameters
- path string
- The file to create or overwrite.
- options OfficeIMO.Yaml.YamlSaveOptions? = null
- Save settings, or null for a minimal-change save.
public void Save(Stream stream, YamlSaveOptions? options = null) #Saves the document to a caller-owned stream in the encoding it was loaded with, including its byte-order mark. The stream is not disposed.
Parameters
- stream System.IO.Stream
- A writable stream.
- options OfficeIMO.Yaml.YamlSaveOptions? = null
- Save settings, or null for a minimal-change save.
public Task SaveAsync(CancellationToken cancellationToken = default) #Saves the document to its YamlDocument.FilePath asynchronously; see YamlDocument.Save.
Parameters
- cancellationToken System.Threading.CancellationToken = default
- Observed between writes.
Returns
Taskpublic async Task SaveAsync(string path, YamlSaveOptions? options = null, CancellationToken cancellationToken = default) #Saves the document to a file asynchronously; see YamlDocument.Save.
Parameters
- path string
- The file to create or overwrite.
- options OfficeIMO.Yaml.YamlSaveOptions? = null
- Save settings, or null for a minimal-change save.
- cancellationToken System.Threading.CancellationToken = default
- Observed between writes.
Returns
Taskpublic Task SaveAsync(Stream stream, YamlSaveOptions? options = null, CancellationToken cancellationToken = default) #Saves the document to a caller-owned stream asynchronously; see YamlDocument.Save.
Parameters
- stream System.IO.Stream
- A writable stream. It is not disposed.
- options OfficeIMO.Yaml.YamlSaveOptions? = null
- Save settings, or null for a minimal-change save.
- cancellationToken System.Threading.CancellationToken = default
- Observed between writes.
Returns
Taskpublic YamlNode? Select(string path) #Returns the node a path addresses, or null. With one document the path starts at its root; with several, a leading $[n] picks the zero-based document, as the paths OfficeIMO.Reader.Yaml reports for multi-document streams do, and paths without it start at the first document. See YamlNode.Select for the grammar.
Parameters
- path string
Returns
YamlNode?Exceptions
ArgumentNullException– path is null.ArgumentException– path is malformed.
public YamlNode Set(string path, YamlNode? value) #Sets the value at a path, creating missing mappings on the way (and a sequence where the next step is an index), in the layout of their neighbors. The last step sets a mapping value as YamlMapping.Set does, replaces a sequence item, or appends when the index equals the sequence's count. $ or an empty path sets the root.
Parameters
- path string
- value OfficeIMO.Yaml.YamlNode?
Exceptions
ArgumentException– The path is malformed.ArgumentOutOfRangeException– An index is past the end of its sequence.InvalidOperationException– The path goes through a scalar, or a key step meets a sequence or an index step a mapping.
public override string ToString() #Returns the document as YAML text, as YamlDocument.Save would write it. An unchanged document returns its source text: the string passed to YamlDocument.Parse, or the decoded file or stream without its byte-order mark.
Returns
stringpublic string ToString(YamlSaveOptions? options) #Returns the document as YAML text with save settings; see YamlDocument.ToString.
Parameters
- options OfficeIMO.Yaml.YamlSaveOptions?
Returns
stringInherited Methods
Properties
public string? FilePath { get; } #Gets the full path that YamlDocument.Save writes to: the path of YamlDocument.Create, or of the last file load or save. Documents parsed from text or loaded from a stream have none until they are saved to a path.
public IReadOnlyList<YamlDocumentPart> Documents { get; } #Gets the documents of the stream in source order. An empty or comment-only stream has none.
public YamlNode? Root { get; set; } #Gets the root node of the first document, or null when the stream has no documents. Setting it replaces that root, or adds a first document to an empty stream.
public IReadOnlyList<OfficeDiagnostic> Diagnostics { get; } #Gets findings recorded while loading and editing, with a line and column as the location: each duplicate key a non-strict load or a lenient YamlDuplicateKeyPolicy admitted (OfficeDiagnosticCodes.YamlDuplicateKey), each indentation the specification rejects that a non-strict load accepted (OfficeDiagnosticCodes.YamlLenientIndentation), one note per document part that uses << merge keys without a %YAML 1.1 directive (OfficeDiagnosticCodes.YamlMergeKeyWithoutDirective), and each edit of a node that aliases share (OfficeDiagnosticCodes.YamlAliasedNodeEdited).