Meziantou.FrameworkYamlReader Class
Reads YAML tokens for use by YamlConverter implementations.
public sealed class YamlReader : YamlReaderWriterBaseRemarks
This API is intentionally similar in spirit to System.Text.Json's reader, but it models YAML constructs (mappings, sequences, scalars).
- Inheritance
YamlReaderWriterBaseYamlReader
Properties
| Name | Description |
|---|---|
| Alias | Gets the current YAML alias when YamlReader.TokenType is YamlTokenType.Alias. |
| Anchor | Gets the current YAML anchor (when present) for the current token. |
| End | Gets the end location of the current token. |
| IsCurrentNodeDerivedTypeResolved | Gets a value indicating whether the derived type of the current node was already selected by its type discriminator or tag. |
| ScalarStyle | Gets the current scalar style when YamlReader.TokenType is YamlTokenType.Scalar. |
| ScalarValue | Gets the current scalar value when YamlReader.TokenType is YamlTokenType.Scalar. |
| SourceName | Gets the optional source name associated with the YAML payload (for example, a file path). |
| Start | Gets the start location of the current token. |
| Tag | Gets the current YAML tag (when present) for the current token. |
| TokenType | Gets the current token type. |
Alias
YamlReader.csGets the current YAML alias when YamlReader.TokenType is YamlTokenType.Alias.
public string? Alias { get; }Property value
Anchor
YamlReader.csIsCurrentNodeDerivedTypeResolved
YamlReader.csGets a value indicating whether the derived type of the current node was already selected by its type discriminator or tag.
public bool IsCurrentNodeDerivedTypeResolved { get; }Property value
Remarks
A polymorphic type reading a node flagged by YamlReader.MarkCurrentNodeDerivedTypeResolved is the derived type the node explicitly named. When the node has no type discriminator or tag of its own, the polymorphic type reads the node as itself instead of selecting its default derived type or running a type classifier.
ScalarStyle
YamlReader.csGets the current scalar style when YamlReader.TokenType is YamlTokenType.Scalar.
public ScalarStyle ScalarStyle { get; }Property value
ScalarValue
YamlReader.csGets the current scalar value when YamlReader.TokenType is YamlTokenType.Scalar.
public string? ScalarValue { get; }Property value
SourceName
YamlReader.csStart
YamlReader.csTokenType
YamlReader.csMethods
| Name | Description |
|---|---|
| BufferCurrentNodeToString(YamlReader) | Buffers the current YAML node to a string. |
| BufferCurrentNodeToStringAndFindDiscriminator(YamlReader, string, string?) | Buffers the current YAML node to a string while optionally extracting a discriminator value from the root mapping. |
| BufferCurrentNodeToStringAndRemoveDiscriminator(YamlReader, string?, bool, string?) | Buffers the current YAML node to a string, extracting the type discriminator of the root mapping and removing it, along with the tag of the root mapping when requested, from the buffered YAML. |
| Create(TextReader, YamlSerializerOptions?) | Creates a YAML reader over a text reader. |
| Create(string, YamlSerializerOptions?) | Creates a YAML reader over a string payload. |
| CreateReader(string) | Creates a YAML reader over a string payload that shares the current reader's reference anchor state. |
| GetScalarValue() | Ensures the current token is YamlTokenType.Scalar and returns its value. |
| MarkCurrentNodeDerivedTypeResolved() | Records that the derived type of the current node was selected by its type discriminator or tag, which polymorphic deserialization consumed. |
| Read() | Advances to the next token. |
| RegisterAnchor(string, object) | Registers an anchored value for later alias resolution. |
| Skip() | Skips the current node and any nested content. |
| TryReadAlias(object?) | Attempts to resolve the current alias token into an anchored object value. |
| TryReplayMappingAlias() | Replays the mapping node the current alias refers to, so that it can be read again as a new node. |
BufferCurrentNodeToString(YamlReader)
YamlReader.csBuffers the current YAML node to a string.
public static string BufferCurrentNodeToString(YamlReader reader)Parameters
readerYamlReader- The reader positioned at the start of the node.
Returns
string The buffered YAML for the node.
Exceptions
ArgumentNullExceptionreaderisnull.
Remarks
This method consumes the buffered node from reader and advances it past the node.
BufferCurrentNodeToStringAndFindDiscriminator(YamlReader, string, string?)
YamlReader.csBuffers the current YAML node to a string while optionally extracting a discriminator value from the root mapping.
public static string BufferCurrentNodeToStringAndFindDiscriminator(YamlReader reader, string discriminatorPropertyName, out string? discriminatorValue)Parameters
readerYamlReader- The reader positioned at the start of the node.
discriminatorPropertyNamestring- The mapping key name to treat as a discriminator.
discriminatorValuestring?- Receives the discriminator scalar value when present on the root mapping.
Returns
string The buffered YAML for the node.
Exceptions
ArgumentNullExceptionreaderordiscriminatorPropertyNameisnull.
Remarks
This method consumes the buffered node from reader and advances it past the node. It is primarily used by polymorphic deserialization implementations.
BufferCurrentNodeToStringAndRemoveDiscriminator(YamlReader, string?, bool, string?)
YamlReader.csBuffers the current YAML node to a string, extracting the type discriminator of the root mapping and removing it, along with the tag of the root mapping when requested, from the buffered YAML.
public static string BufferCurrentNodeToStringAndRemoveDiscriminator(YamlReader reader, string? discriminatorPropertyName, bool removeTag, out string? discriminatorValue)Parameters
readerYamlReader- The reader positioned at the start of the node.
discriminatorPropertyNamestring?- The mapping key holding the discriminator, or
nullto keep every entry of the root mapping. removeTagbool- Whether the tag of the root mapping is removed from the buffered YAML.
discriminatorValuestring?- Receives the discriminator scalar value when present on the root mapping.
Returns
string The buffered YAML for the node, without its type discriminator.
Exceptions
ArgumentNullExceptionreaderisnull.
Remarks
Polymorphic deserialization consumes the type discriminator to select the type to deserialize, so the selected type must not see it again: it is not a member of that type, and a type that is itself polymorphic would try to resolve it against its own derived types. Only the first matching entry of the root mapping is removed. This method consumes the buffered node from reader and advances it past the node.
Create overloads
Create(TextReader, YamlSerializerOptions?)
YamlReader.csCreates a YAML reader over a text reader.
public static YamlReader Create(TextReader reader, YamlSerializerOptions? options = null)Parameters
readerTextReader- The YAML payload reader.
optionsYamlSerializerOptions?- Options used for parsing behaviors such as reference handling.
Returns
Exceptions
ArgumentNullExceptionreaderisnull.
Create(string, YamlSerializerOptions?)
YamlReader.csCreates a YAML reader over a string payload.
public static YamlReader Create(string yaml, YamlSerializerOptions? options = null)Parameters
yamlstring- The YAML payload.
optionsYamlSerializerOptions?- Options used for parsing behaviors such as reference handling.
Returns
Exceptions
ArgumentNullExceptionyamlisnull.
CreateReader(string)
YamlReader.csCreates a YAML reader over a string payload that shares the current reader's reference anchor state.
public YamlReader CreateReader(string yaml)Parameters
yamlstring- The YAML payload.
Returns
YamlReader A new reader for yaml.
Exceptions
ArgumentNullExceptionyamlisnull.
Remarks
This is intended for advanced scenarios such as polymorphic deserialization that buffers a node and needs to re-parse it while preserving anchors and aliases.
GetScalarValue()
YamlReader.csEnsures the current token is YamlTokenType.Scalar and returns its value.
public string GetScalarValue()MarkCurrentNodeDerivedTypeResolved()
YamlReader.csRecords that the derived type of the current node was selected by its type discriminator or tag, which polymorphic deserialization consumed.
public void MarkCurrentNodeDerivedTypeResolved()Remarks
Polymorphic deserialization removes the discriminator from the node before reading it as the selected derived type. When that type is polymorphic itself, the node no longer tells it which type was selected, so without this flag it would select its own default derived type instead of itself.
The flag only applies to the current node, not to the nodes it contains. It is intended for generated serializers and custom polymorphic converters. See YamlReader.IsCurrentNodeDerivedTypeResolved.
Read()
YamlReader.csRegisterAnchor(string, object)
YamlReader.csSkip()
YamlReader.csSkips the current node and any nested content.
public void Skip()TryReadAlias(object?)
YamlReader.csTryReplayMappingAlias()
YamlReader.csReplays the mapping node the current alias refers to, so that it can be read again as a new node.
public bool TryReplayMappingAlias()Returns
bool true when the current token is an alias and reference handling is enabled: the reader is then positioned on the start of a copy of the anchored mapping node. false otherwise, and the reader does not move.
Exceptions
YamlException- The alias is unknown, does not refer to a mapping, refers to a mapping that contains it, or exceeds the alias expansion limit.
Remarks
This is how a merge key (<<: *defaults) reads its alias: the merge copies the entries of the anchored mapping node, as they appear in the document, and not the members of the value that node was deserialized into.
The copy is read like the original node, except that the anchors it contains are not defined again. An alias it contains still refers to the value its anchor was deserialized into. The replayed nodes count towards YamlSerializerOptions.MaxAliasExpansionNodeCount.