YamlReader
OfficeIMO.Yaml
A forward-only, low-allocation pull reader for YAML 1.2 text, modeled on Utf8JsonReader and XmlReader. Each YamlReader.Read advances to the next event of the serialization tree: stream, document, collection start and end, scalar, alias and (optionally) comment.
Inheritance
- object
- YamlReader
Remarks
Reading allocates nothing per event. Strings are created only when , or is called, and plain scalars without folding are copied straight from the source. and the other span-based members are valid only until the next . Positions are precise enough to rebuild the input: the text between consecutive events is whitespace, comments, line breaks and the indicators -, ?, : and ,. Malformed input throws ; after an exception the reader cannot continue. A reader is not thread-safe. Dispose it to return pooled buffers; the reader never disposes a caller's stream or text reader.
Usage
Explore 2 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.
Accepted by parameters 2
- Method YamlSerializer.Deserialize
- Method YamlSerializer.Deserialize``1
Constructors
public YamlReader(string yaml, YamlReaderOptions? options = null, CancellationToken cancellationToken = default) #Creates a reader over YAML text.
Parameters
- yaml string
- The YAML text. A leading U+FEFF byte-order mark is skipped.
- options OfficeIMO.Yaml.YamlReaderOptions? = null
- Reader settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Checked at bounded intervals while scanning.
public YamlReader(ReadOnlyMemory<char> yaml, YamlReaderOptions? options = null, CancellationToken cancellationToken = default) #Creates a reader over YAML text held in memory. The memory must not change while the reader is used.
Parameters
- yaml System.ReadOnlyMemory<char>
- The YAML text. A leading U+FEFF byte-order mark is skipped.
- options OfficeIMO.Yaml.YamlReaderOptions? = null
- Reader settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Checked at bounded intervals while scanning.
public YamlReader(TextReader reader, YamlReaderOptions? options = null, CancellationToken cancellationToken = default) #Creates a reader over a caller-owned TextReader. Text is read into a pooled sliding buffer that keeps only what the current event needs; it grows only while a single token is longer than the buffer.
Parameters
- reader System.IO.TextReader
- The source of YAML text. It is not disposed by the reader.
- options OfficeIMO.Yaml.YamlReaderOptions? = null
- Reader settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Checked at bounded intervals while scanning and reading.
public YamlReader(Stream stream, YamlReaderOptions? options = null, CancellationToken cancellationToken = default) #Creates a reader over a caller-owned byte stream. 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; invalid bytes throw YamlException with code YamlErrorCodes.InvalidEncoding. Decoded text is read into a pooled sliding buffer.
Parameters
- stream System.IO.Stream
- A readable stream. It is not disposed by the reader.
- options OfficeIMO.Yaml.YamlReaderOptions? = null
- Reader settings, or null for the defaults.
- cancellationToken System.Threading.CancellationToken = default
- Checked at bounded intervals while scanning and reading.
Methods
public void Dispose() #Returns pooled buffers. The caller's stream or text reader is not disposed.
public string GetString() #Returns the decoded value of the current scalar (folding, escapes and block chomping applied), the text of the current comment after #, or the name the current alias refers to. The string is created once per event; mapping keys that repeat return the same instance.
Returns
stringExceptions
InvalidOperationException– The current event is not a scalar, comment or alias.
public bool IsNull() #Returns whether the current node is null under the active schema: an untagged plain scalar such as null, ~ or an empty node (core schema), or a node tagged !!null. Quoted scalars are never null.
Returns
boolpublic bool Read() #Advances to the next event. Returns false after YamlTokenType.StreamEnd has been read.
Returns
boolExceptions
YamlException– The input is malformed or exceeds a limit.OperationCanceledException– The cancellation token was signaled.
public bool TryGetBoolean(out bool value) #Reads the current scalar as a boolean under the active schema (true/false in the 1.2 schemas, plus yes/no/on/off/y/n under YAML 1.1) or a !!bool tag. Returns false for any other node, including quoted text.
Parameters
- value bool
Returns
boolpublic bool TryGetDecimal(out decimal value) #Reads the current scalar as a decimal: any integer or finite floating-point value under the active schema, or a node tagged !!int or !!float. Infinity, NaN and out-of-range values return false.
Parameters
- value decimal
Returns
boolpublic bool TryGetDouble(out double value) #Reads the current scalar as a double: any integer or floating-point value under the active schema, including .inf, -.inf and .nan, or a node tagged !!int or !!float.
Parameters
- value double
Returns
boolpublic bool TryGetInt64(out long value) #Reads the current scalar as a 64-bit integer under the active schema (decimal, plus 0o/0x in the core schema and 0b, 0-octal, underscores and sexagesimal under YAML 1.1) or an !!int tag. Returns false for other nodes and for values outside the long range.
Parameters
- value long
Returns
boolInherited Methods
Properties
public YamlTokenType TokenType { get; } #Gets the type of the current event, or YamlTokenType.None before the first YamlReader.Read and after the last.
public YamlStyle Style { get; } #Gets the style of the current scalar or collection, or YamlStyle.None for other events.
public bool IsImplicit { get; } #Gets whether the current document start or end has no marker (--- or ...) in the source, or whether the current mapping is an implicit single-pair mapping inside a flow sequence ([ key: value ]).
public YamlPosition Start { get; } #Gets where the current event starts. Node events start at their first property (anchor or tag).
public YamlPosition End { get; } #Gets where the current event ends. Block collection ends are zero-width at the end of their last content; empty scalars are zero-width where the omitted node would be.
public ReadOnlySpan<char> ValueSpan { get; } #Gets the raw source of the current value without decoding: a scalar's text between its quotes (escapes intact) or a block scalar's content lines (indentation intact), a comment's text after #, or an alias's name. Empty for other events. Valid until the next YamlReader.Read; use YamlReader.GetString for the value.
public YamlSchema Schema { get; } #Gets the schema the current document resolves untagged plain scalars with: YamlReaderOptions.Schema when set; otherwise YamlSchema.Yaml11 for a document that declares %YAML 1.1 and YamlSchema.Core for any other. It changes at each YamlTokenType.DocumentStart, so a streaming consumer resolves values exactly as a loaded YamlDocument does.
public IReadOnlyList<OfficeDiagnostic> Diagnostics { get; } #Gets the findings so far, in source order: each indentation the specification rejects that the reader accepted because YamlReaderOptions.Strict is off (OfficeDiagnosticCodes.YamlLenientIndentation), once per outermost flow collection and once per quoted scalar, with a line and column as the location. Empty, and free, while there are none; the list grows as reading continues.
public string? Tag { get; } #Gets the resolved tag of the current node, or null when it has none. Shorthand tags are expanded through the document's %TAG directives (!!str becomes tag:yaml.org,2002:str), percent escapes are decoded, and the non-specific tag is !. Untagged nodes return null even when the schema would resolve them; use the typed accessors for resolution.
public string? Anchor { get; } #Gets the anchor name of the current node (without &), the name an alias refers to (without *), or null. Repeated names return the same string instance.