SharpYaml

https://github.com/xoofx/sharpyaml
Admin
SharpYaml is a high-performance .NET YAML parser, emitter, and object serializer with NativeAOT...
Tokens:27,080
Snippets:352
Trust Score:10
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Build and Serve Documentation Site

Source: https://github.com/xoofx/sharpyaml/blob/main/site/AGENTS.md

Commands to install the Lunet tool and build or serve the documentation site locally.

```sh
# Prerequisite: install lunet as a .NET global tool (once)
dotnet tool install -g lunet

# From this directory (site/)
lunet build          # production build -> .lunet/build/www/
lunet serve          # dev server with live reload at http://localhost:4000
```

--------------------------------

### Build Documentation Site

Source: https://github.com/xoofx/sharpyaml/blob/main/AGENTS.md

Prerequisite installation and build commands for the Lunet-based documentation site.

```sh
# prerequisite (once)
dotnet tool install -g lunet

# build the documentation site
cd site
lunet build
```

--------------------------------

### YAML Sequences Example

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/yaml-basics.md

Demonstrates a YAML sequence, which represents an ordered list of items, similar to a JSON array. This example lists names.

```yaml
names:
  - Ada
  - Bob
```

--------------------------------

### YAML Mappings Example

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/yaml-basics.md

Shows a basic YAML mapping, which represents key-value pairs, similar to a JSON object. This example defines server configuration with host and port.

```yaml
server:
  host: localhost
  port: 8080
```

--------------------------------

### Serialize and Deserialize YAML with SharpYaml

Source: https://github.com/xoofx/sharpyaml/blob/main/site/readme.md

Demonstrates basic YAML serialization and deserialization using YamlSerializer. This example assumes a 'Person' class is defined elsewhere.

```csharp
using SharpYaml;

var yaml = YamlSerializer.Serialize(new { Name = "Ada", Age = 37 });

// Name: Ada
// Age: 37

var model = YamlSerializer.Deserialize<Person>(yaml);
```

--------------------------------

### Implement a source generation context

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

Example of a partial class inheriting from YamlSerializerContext to drive source generation for specific types.

```csharp
using SharpYaml.Serialization;

[YamlSourceGenerationOptions(WriteIndented = true)]
[YamlSerializable(typeof(MyConfig))]
[YamlSerializable(typeof(List<MyItem>))]
internal partial class MyYamlContext : YamlSerializerContext
{
}
```

--------------------------------

### YAML Multi-Document Stream Example

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/yaml-basics.md

Illustrates how multiple YAML documents can be included in a single stream, separated by '---'. Each document is parsed independently.

```yaml
---
name: a
---
name: b
```

--------------------------------

### Add SharpYaml Package

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/getting-started.md

Install the SharpYaml NuGet package using the .NET CLI. This package supports .NET 8.0, .NET 10.0, and .NET Standard 2.0.

```sh
dotnet add package SharpYaml
```

--------------------------------

### Configure YamlSerializer Options

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/getting-started.md

Customize serialization behavior using YamlSerializerOptions. Options include property naming policy, indentation, and null value handling. This example demonstrates camel case naming, indented output with 4 spaces, and ignoring null values during writing.

```csharp
using System.Text.Json;
using SharpYaml;

var options = new YamlSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true,
    IndentSize = 4,
    DefaultIgnoreCondition = YamlIgnoreCondition.WhenWritingNull,
};

var yaml = YamlSerializer.Serialize(config, options);
var config2 = YamlSerializer.Deserialize<MyConfig>(yaml, options);
```

--------------------------------

### YAML Scalars Example

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/yaml-basics.md

Demonstrates various scalar types in YAML: strings, integers, booleans, floating-point numbers, and null values.

```yaml
name: Ada
age: 37
enabled: true
pi: 3.14159
missing: null
```

--------------------------------

### YAML Block Scalars Example

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/yaml-basics.md

Illustrates the use of literal and folded block scalars for multi-line strings in YAML. Literal scalars preserve newlines, while folded scalars treat newlines as spaces unless they are followed by a blank line.

```yaml
literal: |
  line 1
  line 2
```

```yaml
folded: >
  line 1
  line 2
```

--------------------------------

### Run All Benchmarks

Source: https://github.com/xoofx/sharpyaml/blob/main/site/benchmarks.md

Execute all benchmark scenarios from the repository root. Ensure you are in the 'src' directory.

```bash
cd src
dotnet run -c Release --project SharpYaml.Benchmarks -- --filter "*"
```

--------------------------------

### Run all benchmarks

Source: https://github.com/xoofx/sharpyaml/blob/main/src/SharpYaml.Benchmarks/README.md

Executes the benchmark suite for all scenarios using the Release configuration.

```bash
dotnet run -c Release --project SharpYaml.Benchmarks -- --filter "*"
```

--------------------------------

### Build and Test SharpYaml

Source: https://github.com/xoofx/sharpyaml/blob/main/AGENTS.md

Commands to compile the library and execute the test suite from the project root.

```sh
# from the project root (this folder)
cd src
dotnet build -c Release
dotnet test -c Release
```

--------------------------------

### Run Source-Generated Benchmarks

Source: https://github.com/xoofx/sharpyaml/blob/main/site/benchmarks.md

Execute only the source-generated benchmark scenarios. Navigate to the 'src' directory first.

```bash
cd src
dotnet run -c Release --project SharpYaml.Benchmarks -- --filter "*SourceGenerated*"
```

--------------------------------

### Object Creation Handling

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Configuring how SharpYaml handles object population versus replacement during deserialization.

```APIDOC
## Object Creation Handling

### Description
Controls whether members are replaced or populated during deserialization. By default, values are replaced.

### Usage Example
```csharp
using System.Text.Json.Serialization;
using SharpYaml;

var options = new YamlSerializerOptions
{
    PreferredObjectCreationHandling = JsonObjectCreationHandling.Populate,
};
```

### Notes
- Replace: Default behavior.
- Populate: Reuses existing mutable reference-type members (e.g., List, Dictionary).
- Member-level [JsonObjectCreationHandling(...)] overrides defaults.
```

--------------------------------

### SharpYaml Reader/Writer Foundations (Span<char>)

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

SharpYaml's internal implementation is structured to minimize allocations by operating on spans as much as possible. It introduces abstractions for input and output to support span-based operations.

```APIDOC
## Reader/Writer Foundations (Span<char>)

### Text-first APIs
- Primary IO surface is UTF-16 text (`string`, `TextReader`, `TextWriter`).

### Span-based Implementation (Allocation Control)
- Scanner/parser operates on `ReadOnlySpan<char>` windows.
- Scalars remain spans until type conversion.
- Uses `ArrayPool<char>` for temporary buffer pooling.

### Internal Abstractions
- `IYamlInput`: Returns `ReadOnlySpan<char>` windows (with `TextReader`-backed implementation).
- `IYamlOutput`: Writes to `TextWriter`.
```

--------------------------------

### Serialize and Deserialize .NET Objects to YAML

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Demonstrates basic serialization of a .NET object to YAML and deserialization back to an object using YamlSerializer. Supports generic and non-generic deserialization.

```csharp
using SharpYaml;

// Define a simple model
public class Person
{
    public string Name { get; set; } = "";
    public int Age { get; set; }
    public List<string> Skills { get; set; } = new();
}

// Serialize an object to YAML
var person = new Person
{
    Name = "Ada Lovelace",
    Age = 37,
    Skills = ["Programming", "Mathematics", "Analytics"]
};

string yaml = YamlSerializer.Serialize(person);
// Output:
// Name: Ada Lovelace
// Age: 37
// Skills:
// - Programming
// - Mathematics
// - Analytics

// Deserialize YAML back to an object
var restored = YamlSerializer.Deserialize<Person>(yaml);
Console.WriteLine($"{restored.Name}, Age: {restored.Age}");
// Output: Ada Lovelace, Age: 37

// Deserialize with explicit type
object? dynamicResult = YamlSerializer.Deserialize(yaml, typeof(Person));
```

--------------------------------

### Configure Object Creation Handling

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Sets the preferred object creation handling to Populate, allowing reuse of existing mutable reference-type members.

```csharp
using System.Text.Json.Serialization;
using SharpYaml;

var options = new YamlSerializerOptions
{
    PreferredObjectCreationHandling = JsonObjectCreationHandling.Populate,
};
```

--------------------------------

### SharpYaml Serialization Methods

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

Provides static methods for serializing objects to YAML and deserializing YAML strings to objects. Supports various overloads for different input/output types and options, including TypeInfo overloads for NativeAOT.

```csharp
namespace SharpYaml;

public static class YamlSerializer
{
    // Similar to System.Text.Json.JsonSerializer.IsReflectionEnabledByDefault (controlled via AppContext switch).
    public static bool IsReflectionEnabledByDefault { get; }

    public static string Serialize<T>(T value, YamlSerializerOptions? options = null);
    public static string Serialize(object? value, Type inputType, YamlSerializerOptions? options = null);

    public static void Serialize<T>(TextWriter writer, T value, YamlSerializerOptions? options = null);
    public static void Serialize(TextWriter writer, object? value, Type inputType, YamlSerializerOptions? options = null);

    public static T? Deserialize<T>(string yaml, YamlSerializerOptions? options = null);
    public static object? Deserialize(string yaml, Type returnType, YamlSerializerOptions? options = null);

    // Span<char> and streaming (configuration-first; UTF-16 text is the primary surface in v3):
    public static T? Deserialize<T>(TextReader reader, YamlSerializerOptions? options = null);
    public static object? Deserialize(TextReader reader, Type returnType, YamlSerializerOptions? options = null);
    public static T? Deserialize<T>(ReadOnlySpan<char> yaml, YamlSerializerOptions? options = null);
    public static object? Deserialize(ReadOnlySpan<char> yaml, Type returnType, YamlSerializerOptions? options = null);

    // TypeInfo overloads (source-gen path):
    public static string Serialize<T>(T value, YamlTypeInfo<T> typeInfo);
    public static T? Deserialize<T>(string yaml, YamlTypeInfo<T> typeInfo);
    public static T? Deserialize<T>(ReadOnlySpan<char> yaml, YamlTypeInfo<T> typeInfo);
}
```

--------------------------------

### Source Generation for NativeAOT with SharpYaml

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Define models, declare a source-generated context with serialization options, and use generated YamlTypeInfo<T> for reflection-free serialization and deserialization. This is useful for NativeAOT publishing and trimmed applications.

```csharp
using SharpYaml;
using SharpYaml.Serialization;

// Define your models
public class ServerConfig
{
    public string Host { get; set; } = "localhost";
    public int Port { get; set; } = 8080;
    public List<string> AllowedOrigins { get; set; } = new();
}

public class DatabaseConfig
{
    public string ConnectionString { get; set; } = "";
    public int PoolSize { get; set; } = 10;
}

// Declare a source-generated context with serialization options
[YamlSourceGenerationOptions(
    WriteIndented = true,
    PropertyNamingPolicy = System.Text.Json.JsonKnownNamingPolicy.CamelCase,
    PreferredObjectCreationHandling = System.Text.Json.Serialization.JsonObjectCreationHandling.Populate)]
[YamlSerializable(typeof(ServerConfig))]
[YamlSerializable(typeof(DatabaseConfig))]
[YamlSerializable(typeof(List<string>))]
internal partial class AppYamlContext : YamlSerializerContext
{
}

// Usage with generated YamlTypeInfo<T>
var context = AppYamlContext.Default;

var serverConfig = new ServerConfig
{
    Host = "api.example.com",
    Port = 443,
    AllowedOrigins = ["https://app.example.com", "https://admin.example.com"]
};

// Serialize using generated metadata (reflection-free)
string yaml = YamlSerializer.Serialize(serverConfig, context.ServerConfig);

// Deserialize using generated metadata
var restored = YamlSerializer.Deserialize(yaml, context.ServerConfig);

// For APIs that take Type, use context overloads
string yaml2 = YamlSerializer.Serialize(serverConfig, typeof(ServerConfig), context);
var restored2 = YamlSerializer.Deserialize(yaml2, typeof(ServerConfig), context);
```

--------------------------------

### YamlSerializerOptions Configuration

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Reference table for available configuration options in YamlSerializerOptions.

```APIDOC
## YamlSerializerOptions Reference

### Description
Configuration options for customizing YAML serialization and deserialization behavior.

### Options
| Option | Default | Meaning |
| --- | --- | --- |
| PropertyNamingPolicy | null | Optional renaming for CLR member names. |
| DictionaryKeyPolicy | null | Optional renaming for dictionary keys during serialization. |
| PropertyNameCaseInsensitive | false | Case-insensitive property matching when reading. |
| PreferredObjectCreationHandling | JsonObjectCreationHandling.Replace | Controls whether members are replaced or populated during deserialization. |
| DefaultIgnoreCondition | YamlIgnoreCondition.Never | Skips null/default values when writing. |
| WriteIndented | true | Enables indentation. |
| IndentSize | 2 | Spaces per indent level when WriteIndented is enabled. |
| MappingOrder | YamlMappingOrderPolicy.Declaration | Preserves declaration order by default. |
| Schema | YamlSchemaKind.Core | Controls scalar resolution rules (YAML 1.2). |
| DuplicateKeyHandling | YamlDuplicateKeyHandling.Error | Controls behavior when duplicate keys are encountered. |
| ReferenceHandling | YamlReferenceHandling.None | Enables anchor/alias preservation when needed. |
| UnsafeAllowDeserializeFromTagTypeName | false | Allows tag-based activation by runtime type name. |
| TypeInfoResolver | null | Provides metadata for reflection-free serialization. |
| SourceName | null | Used for error messages when throwing YamlException. |
```

--------------------------------

### Configure Duplicate Key Handling

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/compatibility.md

Specify how duplicate keys in mappings should be handled. YamlDuplicateKeyHandling.Error will throw an exception.

```csharp
var options = new YamlSerializerOptions
{
    DuplicateKeyHandling = YamlDuplicateKeyHandling.Error,
};

```

--------------------------------

### Run source-generated benchmarks

Source: https://github.com/xoofx/sharpyaml/blob/main/src/SharpYaml.Benchmarks/README.md

Executes only the benchmarks related to source-generated serialization.

```bash
dotnet run -c Release --project SharpYaml.Benchmarks -- --filter "*SourceGenerated*"
```

--------------------------------

### Tokenize YAML using Low-Level Scanner

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Use the low-level scanner to tokenize YAML input into individual tokens (e.g., Key, Value, Newline). This provides a granular view of the YAML structure.

```csharp
using SharpYaml;

// Low-level scanner for tokenization
var scanner = new Scanner<StringLookAheadBuffer>(new StringLookAheadBuffer("key: value\n"));
while (scanner.MoveNext())
{
    var token = scanner.Current;
    Console.WriteLine($"Token: {token.GetType().Name}");
}
```

--------------------------------

### Configure Serialization Options

Source: https://github.com/xoofx/sharpyaml/blob/main/README.md

Customize YAML output and parsing behavior using YamlSerializerOptions.

```csharp
var options = new YamlSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true,
    IndentSize = 4,
    DefaultIgnoreCondition = YamlIgnoreCondition.WhenWritingNull,
};

var yaml = YamlSerializer.Serialize(config, options);
var model = YamlSerializer.Deserialize<MyConfig>(yaml, options);
```

--------------------------------

### Dictionary-based extension data

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/extension-data.md

Use this when you need to capture unknown keys as a dictionary. If the property is null, SharpYaml creates a new dictionary. If no unknown keys are found, the property remains null.

```csharp
using SharpYaml.Serialization;

public sealed class Config
{
    public int Known { get; set; }

    [YamlExtensionData]
    public Dictionary<string, object?>? Extra { get; set; }
}
```

--------------------------------

### Migrate Serialization API

Source: https://github.com/xoofx/sharpyaml/blob/main/site/migration.md

Replaces the legacy Serializer instance-based API with static YamlSerializer methods using YamlSerializerOptions.

```csharp
var serializer = new Serializer(new SerializerSettings());
var yaml = serializer.Serialize(value);
var model = serializer.Deserialize<MyType>(yaml);
```

```csharp
var options = new YamlSerializerOptions();
var yaml = YamlSerializer.Serialize(value, options);
var model = YamlSerializer.Deserialize<MyType>(yaml, options);
```

--------------------------------

### Create YAML Programmatically using Model Layer

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Construct YAML structures programmatically using the model layer. This enables dynamic creation of YAML content.

```csharp
using System.IO;
using SharpYaml.Model;

// Create YAML programmatically
var newRoot = new YamlMapping
{
    { new YamlValue("server"), new YamlMapping
        {
            { new YamlValue("name"), new YamlValue("api-server") },
            { new YamlValue("port"), new YamlValue(8080) }
        }
    },
    { new YamlValue("enabled"), new YamlValue(true) }
};

var newDoc = new YamlDocument { Contents = newRoot };
string output = newDoc.ToString();
```

--------------------------------

### Serialize Object to IBufferWriter<char> (Zero-Copy)

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Perform zero-copy serialization to an IBufferWriter<char> for efficient buffer management.

```csharp
using System.Buffers;
using SharpYaml;

// Zero-copy with IBufferWriter<char>
var buffer = new ArrayBufferWriter<char>();
YamlSerializer.Serialize(buffer, new Config { Name = "Buffered", Value = 100 });
string yaml = new string(buffer.WrittenSpan);
```

--------------------------------

### Configure YamlSerializerOptions for Custom Behavior

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Illustrates how to configure YamlSerializerOptions to control naming policies, indentation, null handling, duplicate key behavior, schema, and reference handling. Useful for customizing serialization output and input parsing.

```csharp
using System.Text.Json;
using SharpYaml;

var options = new YamlSerializerOptions
{
    // Naming policies
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    DictionaryKeyPolicy = JsonNamingPolicy.SnakeCaseLower,
    PropertyNameCaseInsensitive = true,

    // Formatting
    WriteIndented = true,
    IndentSize = 4,

    // Null/default handling
    DefaultIgnoreCondition = YamlIgnoreCondition.WhenWritingNull,

    // YAML-specific
    Schema = YamlSchemaKind.Core,
    DuplicateKeyHandling = YamlDuplicateKeyHandling.Error,
    MappingOrder = YamlMappingOrderPolicy.Declaration,

    // Reference handling (anchors/aliases)
    ReferenceHandling = YamlReferenceHandling.None,

    // Error context
    SourceName = "config.yaml"
};

public class AppConfig
{
    public string DatabaseUrl { get; set; } = "";
    public int? MaxConnections { get; set; }
    public string? OptionalSetting { get; set; }
}

var config = new AppConfig
{
    DatabaseUrl = "localhost:5432",
    MaxConnections = 100,
    OptionalSetting = null  // Will be omitted due to WhenWritingNull
};

string yaml = YamlSerializer.Serialize(config, options);
// Output (with camelCase naming):
// databaseUrl: localhost:5432
// maxConnections: 100

var loaded = YamlSerializer.Deserialize<AppConfig>(yaml, options);
```

--------------------------------

### Serialize and Deserialize with SharpYaml

Source: https://github.com/xoofx/sharpyaml/blob/main/README.md

Perform basic object serialization and deserialization using the YamlSerializer class.

```csharp
using SharpYaml;

// Serialize
var yaml = YamlSerializer.Serialize(new { Name = "Ada", Age = 37 });

// Deserialize
var person = YamlSerializer.Deserialize<Person>(yaml);
```

--------------------------------

### Programmatically Author YAML

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/model/nodes.md

Create YAML structures by instantiating YamlMapping and YamlValue objects. Assign them to a YamlDocument's Contents property and then convert the document to a string.

```csharp
using SharpYaml.Model;

var root = new YamlMapping
{
    { new YamlValue("name"), new YamlValue("Ada") },
    { new YamlValue("age"), new YamlValue(37) },
};

var doc = new YamlDocument { Contents = root };
var yaml = doc.ToString();
```

--------------------------------

### SharpYaml Lossless Syntax Layer (Perfect Roundtrip + Source Spans)

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

SharpYaml provides a low-level API for perfect roundtrip parsing and accurate source span information, intended for editors and tooling. This API preserves comments, whitespace, and quoting style.

```APIDOC
## Lossless Syntax Layer (Perfect Roundtrip + Source Spans)

### Requirements
- **Perfect Roundtrip**: Parsing + emitting preserves original text exactly (including comments, whitespace, quoting style, line endings).
- **Accurate Source Spans**: Tokens and nodes expose absolute offsets and line/column information for syntax highlighting and diagnostics.
- Object mapping (`YamlSerializer`) does not guarantee formatting/comment preservation.

### Proposed API Shape
```csharp
namespace SharpYaml.Syntax;

public sealed class YamlSyntaxTree
{
    public static YamlSyntaxTree Parse(string yaml, YamlSyntaxOptions? options = null);

    public string Text { get; } // original text
    public YamlSyntaxNode Root { get; } 
    public IReadOnlyList<YamlSyntaxToken> Tokens { get; } // includes trivia when enabled

    // Perfect roundtrip for the parsed text (when unmodified).
    public string ToFullString();
    public void WriteTo(TextWriter writer);
}

public sealed class YamlSyntaxOptions
{
    public bool IncludeTrivia { get; set; } // default: true (comments/whitespace)
}

public abstract class YamlSyntaxNode
{
    public YamlSourceSpan Span { get; } // span of the syntactic construct (no trivia)
    public YamlSourceSpan FullSpan { get; } // span including trivia (when available)
}

public readonly struct YamlSyntaxToken
{
    public YamlSyntaxKind Kind { get; } 
    public YamlSourceSpan Span { get; }
}

public readonly struct YamlSourceSpan
{
    public Mark Start { get; } 
    public Mark End { get; }
}

public enum YamlSyntaxKind
{
    // Includes at minimum: CommentTrivia, WhitespaceTrivia, NewLineTrivia,
    // Scalar, Indicators/Punctuation needed for highlighting, Directives, Tags, Anchors, etc.
}
```

### Behavioral Requirements
- `YamlSyntaxTree.Parse(text).ToFullString()` must equal `text` exactly for valid YAML input.
- All spans must be consistent with the source text:
  - `Mark.Index` is 0-based absolute offset in `Text`.
  - `Mark.Line` and `Mark.Column` are 0-based.
- Parse errors must surface `YamlException` with correct `Start`/`End` marks for the offending region.
```

--------------------------------

### Emit a YAML Mapping from Parsing Events

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/low-level/emitter.md

Use the Emitter to write YAML text by emitting individual parsing events like StreamStart, DocumentStart, MappingStart, Scalars, and their corresponding end events. This is useful for tooling and transformations operating on event streams.

```csharp
using System.IO;
using SharpYaml;
using SharpYaml.Events;

var writer = new StringWriter();
var emitter = new Emitter(writer);

emitter.Emit(new StreamStart());
emitter.Emit(new DocumentStart());
emitter.Emit(new MappingStart());

emitter.Emit(new Scalar("name"));
emitter.Emit(new Scalar("Ada"));

emitter.Emit(new Scalar("age"));
emitter.Emit(new Scalar("37"));

emitter.Emit(new MappingEnd());
emitter.Emit(new DocumentEnd());
emitter.Emit(new StreamEnd());

var yaml = writer.ToString();
```

--------------------------------

### Define SharpYaml Syntax API Structure

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

Defines the core classes and structures for the low-level YAML syntax API, enabling perfect roundtrip parsing and source span tracking.

```csharp
namespace SharpYaml.Syntax;

public sealed class YamlSyntaxTree
{
    public static YamlSyntaxTree Parse(string yaml, YamlSyntaxOptions? options = null);

    public string Text { get; } // original text
    public YamlSyntaxNode Root { get; }
    public IReadOnlyList<YamlSyntaxToken> Tokens { get; } // includes trivia when enabled

    // Perfect roundtrip for the parsed text (when unmodified).
    public string ToFullString();
    public void WriteTo(TextWriter writer);
}

public sealed class YamlSyntaxOptions
{
    public bool IncludeTrivia { get; set; } // default: true (comments/whitespace)
}

public abstract class YamlSyntaxNode
{
    public YamlSourceSpan Span { get; } // span of the syntactic construct (no trivia)
    public YamlSourceSpan FullSpan { get; } // span including trivia (when available)
}

public readonly struct YamlSyntaxToken
{
    public YamlSyntaxKind Kind { get; }
    public YamlSourceSpan Span { get; }
}

public readonly struct YamlSourceSpan
{
    public Mark Start { get; }
    public Mark End { get; }
}

public enum YamlSyntaxKind
{
    // Includes at minimum: CommentTrivia, WhitespaceTrivia, NewLineTrivia,
    // Scalar, Indicators/Punctuation needed for highlighting, Directives, Tags, Anchors, etc.
}
```

--------------------------------

### SharpYaml Core APIs

Source: https://github.com/xoofx/sharpyaml/blob/main/src/SharpYaml/apidocs/SharpYaml.md

This section provides an overview of the core components of the SharpYaml library for YAML processing.

```APIDOC
## SharpYaml Core APIs

### Description
Top-level APIs for parsing, emitting, and serializing YAML with SharpYaml. This namespace contains the main entry points for most applications.

### Key Components

- **YamlSerializer** and **YamlSerializerOptions**: Used for object serialization and deserialization.
- **Scanner**, **Parser**, and **Emitter**: Low-level types for token/event based YAML processing.
```

--------------------------------

### Parse YAML into Events using Low-Level Parser

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Process YAML by iterating through a stream of events (StreamStart, Scalar, MappingEnd, etc.) using the low-level parser. This is useful for custom tooling and analysis.

```csharp
using System.IO;
using SharpYaml;
using SharpYaml.Events;

string yaml = """
    name: Ada
    age: 37
    skills:
      - Programming
      - Mathematics
    """;

// Parse YAML into events
var parser = Parser.CreateParser(new StringReader(yaml));

while (parser.MoveNext())
{
    var evt = parser.Current;
    switch (evt)
    {
        case StreamStart:
            Console.WriteLine("Stream started");
            break;
        case DocumentStart:
            Console.WriteLine("Document started");
            break;
        case MappingStart:
            Console.WriteLine("Mapping started");
            break;
        case Scalar scalar:
            Console.WriteLine($"Scalar: {scalar.Value}");
            break;
        case SequenceStart:
            Console.WriteLine("Sequence started");
            break;
        case SequenceEnd:
            Console.WriteLine("Sequence ended");
            break;
        case MappingEnd:
            Console.WriteLine("Mapping ended");
            break;
        case DocumentEnd:
            Console.WriteLine("Document ended");
            break;
        case StreamEnd:
            Console.WriteLine("Stream ended");
            break;
    }
}
```

--------------------------------

### Serialize with YamlTypeInfo<T>

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Use the generated YamlTypeInfo<T> property for serialization. This is the recommended approach for most cases.

```csharp
var yaml = YamlSerializer.Serialize(value, MyYamlContext.Default.MyConfig);
```

--------------------------------

### Serialize and Deserialize with YamlSerializer

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Basic usage of the YamlSerializer to convert objects to YAML strings and back to typed models.

```csharp
using SharpYaml;

var yaml = YamlSerializer.Serialize(new { Name = "Ada" });
var model = YamlSerializer.Deserialize<Person>(yaml);
```

--------------------------------

### SharpYaml Anchors and Aliases (Reference Preservation)

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

SharpYaml provides options for handling object references, allowing for the preservation of object graphs using anchors and aliases. It supports cycle detection and stable anchor naming.

```APIDOC
## Anchors / Aliases (Reference Preservation)

### `YamlReferenceHandling.None` (default)
- No alias emission; repeated references become repeated values.

### `YamlReferenceHandling.Preserve`
- Emit anchors/aliases to preserve object reference graphs.
- Must detect cycles and preserve correctly.
- Uses stable anchor naming (`id001`, `id002`, ...).
```

--------------------------------

### Write a YamlStream Model to a Writer

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/low-level/emitter.md

If you are using the model layer, such as YamlStream, you can write it back to a string writer using the WriteTo method. This is a convenient way to serialize SharpYaml models.

```csharp
using SharpYaml.Model;

var stream = YamlStream.Load(new StringReader("a: 1\n"));
var doc = stream[0];

var sb = new StringWriter();
doc.WriteTo(sb);
```

--------------------------------

### SharpYaml Serialization Attributes Reference

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/yaml-attributes.md

A comprehensive list of attributes available in SharpYaml.Serialization to customize YAML serialization behavior.

```APIDOC
## SharpYaml Serialization Attributes

### Description
Attributes used to configure serialization and deserialization behavior for members, types, and constructors in SharpYaml.

### Attributes
- **YamlPropertyNameAttribute** (Member) - Overrides the serialized property name.
- **YamlPropertyOrderAttribute** (Member) - Controls ordering within a mapping.
- **YamlIgnoreAttribute** (Member) - Ignores a member for serialization/deserialization.
- **YamlIncludeAttribute** (Member) - Includes a non-public member when supported.
- **YamlRequiredAttribute** (Member) - Missing required members throw YamlException.
- **YamlExtensionDataAttribute** (Member) - Captures extra keys into a dictionary or YamlMapping.
- **YamlConverterAttribute** (Type/Member) - Assigns a custom converter.
- **YamlConstructorAttribute** (Constructor) - Selects which constructor to use for deserialization.
- **YamlPolymorphicAttribute** (Type) - Configures polymorphism (discriminator style).
- **YamlDerivedTypeAttribute** (Type) - Registers a derived type and optional tag/discriminator.

### Precedence
If both YAML and JSON attributes are present on a member, YAML attributes take precedence.
```

--------------------------------

### Reflection vs Metadata

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Configuring metadata resolution strategies for serialization, including disabling reflection for NativeAOT support.

```APIDOC
## Reflection vs Metadata

### Description
SharpYaml supports two metadata resolution strategies: reflection-based (default) and generated metadata (recommended for NativeAOT).

### Disabling Reflection
To disable reflection-based serialization, use the following AppContext switch:

```csharp
AppContext.SetSwitch("SharpYaml.YamlSerializer.IsReflectionEnabledByDefault", false);
```

### Metadata Resolution
- Generated metadata: Uses YamlSerializerContext and YamlTypeInfo<T>.
- Reflection fallback: Enabled by default; requires YamlTypeInfo<T> or YamlSerializerOptions.TypeInfoResolver if reflection is disabled.
```

--------------------------------

### Bridge Model Layer and Object Mapping

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Use YamlNode.FromObject to convert C# objects to YAML nodes and ToObject to convert YAML nodes back to C# objects.

```csharp
using SharpYaml.Model;

// Bridge between model and object mapping
var element = YamlNode.FromObject(new { Name = "Ada", Age = 37 });
var person = element.ToObject<Person>();
```

--------------------------------

### Configure Compile-time Options for YamlContext

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/source-generation.md

Use YamlSourceGenerationOptionsAttribute to set default YamlSerializerOptions at build time, including converter registration. PreferredObjectCreationHandling defaults to Replace and can be set to Populate to reuse existing mutable members.

```csharp
[YamlSourceGenerationOptions(
    WriteIndented = false,
    PropertyNamingPolicy = System.Text.Json.JsonKnownNamingPolicy.CamelCase,
    PreferredObjectCreationHandling = System.Text.Json.Serialization.JsonObjectCreationHandling.Populate,
    Converters = new[] { typeof(MyCustomConverter) })]
internal partial class MyYamlContext : YamlSerializerContext
{
}
```

--------------------------------

### Configure YAML Polymorphism Options

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

Defines the configuration class for handling type discriminators and unknown derived types during serialization.

```csharp
public sealed class YamlPolymorphismOptions
{
    public YamlTypeDiscriminatorStyle DiscriminatorStyle { get; set; } // default: Property (JSON-like). Tag / Property / Both
    public string TypeDiscriminatorPropertyName { get; set; } // default: "$type"
    public YamlUnknownDerivedTypeHandling UnknownDerivedTypeHandling { get; set; } // Fail / FallBackToBase
}
```

--------------------------------

### Serialize Object with Context at Runtime

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/getting-started.md

When resolving metadata by type at runtime (e.g., Serialize(object, Type, ...)), use overloads that accept a context for proper type handling with source generation.

```csharp
var yaml = YamlSerializer.Serialize(config, typeof(MyConfig), context);
```

--------------------------------

### Create Custom Converters

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Implement YamlConverter<T> or YamlConverterFactory to handle specialized serialization logic for custom types or generic wrappers.

```csharp
using System.Globalization;
using System.Net;
using SharpYaml;
using SharpYaml.Serialization;

// Simple converter for IPAddress
public sealed class IPAddressConverter : YamlConverter<IPAddress>
{
    public override IPAddress? Read(YamlReader reader)
    {
        var text = reader.ScalarValue;
        reader.Read();
        return text is null ? null : IPAddress.Parse(text);
    }

    public override void Write(YamlWriter writer, IPAddress? value)
        => writer.WriteScalar(value?.ToString() ?? "");
}

// Converter for custom Temperature type
public readonly struct Temperature
{
    public double Value { get; init; }
    public string Unit { get; init; }
}

[YamlConverter(typeof(TemperatureConverter))]
public readonly struct AnnotatedTemperature
{
    public double Value { get; init; }
    public string Unit { get; init; }
}

public sealed class TemperatureConverter : YamlConverter<Temperature>
{
    public override Temperature Read(YamlReader reader)
    {
        var text = reader.ScalarValue!;
        reader.Read();

        var unit = text[^1..];
        var value = double.Parse(text[..^1], CultureInfo.InvariantCulture);
        return new Temperature { Value = value, Unit = unit };
    }

    public override void Write(YamlWriter writer, Temperature value)
        => writer.WriteScalar($"{value.Value.ToString("G", CultureInfo.InvariantCulture)}{value.Unit}");
}

// Converter factory for generic types
public sealed class NullableConverterFactory : YamlConverterFactory
{
    public override bool CanConvert(Type typeToConvert)
        => Nullable.GetUnderlyingType(typeToConvert) is not null;

    public override YamlConverter CreateConverter(Type typeToConvert, YamlSerializerOptions options)
    {
        var innerType = Nullable.GetUnderlyingType(typeToConvert)!;
        var converterType = typeof(NullableConverter<>).MakeGenericType(innerType);
        return (YamlConverter)Activator.CreateInstance(converterType)!;
    }
}

// Register converters via options
var options = new YamlSerializerOptions
{
    Converters =
    [
        new IPAddressConverter(),
        new TemperatureConverter(),
    ]
};

public class ServerEndpoint
{
    public IPAddress Address { get; set; } = IPAddress.Loopback;
    public int Port { get; set; }
    public Temperature MaxTemp { get; set; }
}

var endpoint = new ServerEndpoint
{
    Address = IPAddress.Parse("192.168.1.100"),
    Port = 8080,
    MaxTemp = new Temperature { Value = 85.5, Unit = "C" }
};

string yaml = YamlSerializer.Serialize(endpoint, options);
// Output:
// Address: 192.168.1.100
// Port: 8080
// MaxTemp: 85.5C
```

--------------------------------

### Serialize to BufferWriter

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Write YAML directly to an IBufferWriter<char> to minimize string allocations during serialization.

```csharp
using System.Buffers;
using SharpYaml;

var buffer = new ArrayBufferWriter<char>();
YamlSerializer.Serialize(buffer, new { Name = "Ada" });

var yaml = new string(buffer.WrittenSpan);
```

--------------------------------

### SharpYamlSerializerOptions Class

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

Configuration object for YamlSerializer, analogous to JsonSerializerOptions. Allows customization of naming policies, null handling, formatting, mapping order, schema, duplicate key handling, and polymorphism.

```csharp
namespace SharpYaml;

public sealed class YamlSerializerOptions
{
    public static YamlSerializerOptions Default { get; }

    // Naming
    public YamlNamingPolicy? PropertyNamingPolicy { get; set; }
    public YamlNamingPolicy? DictionaryKeyPolicy { get; set; }
    public bool PropertyNameCaseInsensitive { get; set; } // default: false

    // Null / default handling
    public YamlIgnoreCondition DefaultIgnoreCondition { get; set; } // Never/WhenWritingNull/WhenWritingDefault

    // Formatting
    public bool WriteIndented { get; set; }
    public int IndentSize { get; set; } // default: 2

    // Mapping/member ordering
    public YamlMappingOrderPolicy MappingOrder { get; set; } // default: Declaration

    // YAML specifics
    public YamlSchemaKind Schema { get; set; } // default: Core (YAML 1.2 core)
    public YamlDuplicateKeyHandling DuplicateKeyHandling { get; set; } // Error / LastWins / FirstWins
    public YamlScalarStylePreferences ScalarStylePreferences { get; set; }

    // Polymorphism
    public YamlPolymorphismOptions PolymorphismOptions { get; }

    // References (anchors/aliases)
    public YamlReferenceHandling ReferenceHandling { get; set; } // None / Preserve

    // Metadata / resolvers
    public IYamlTypeInfoResolver? TypeInfoResolver { get; set; }
}
```

--------------------------------

### Configure YamlSerializerOptions

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Define immutable serialization options such as naming policies and ignore conditions for reuse.

```csharp
using System.Text.Json;
using SharpYaml;

var options = new YamlSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    DefaultIgnoreCondition = YamlIgnoreCondition.WhenWritingNull,
};
```

--------------------------------

### Object Creation Handling with JsonObjectCreationHandlingAttribute

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/json-attributes.md

Control object creation behavior using `JsonObjectCreationHandlingAttribute`. When applied to a type, it sets the default handling for members. `Populate` reuses existing member instances if the type supports it, while `Replace` overwrites them. Note that `Populate` on struct properties requires a setter and will throw a runtime error if the struct member is readonly.

```csharp
using System.Collections.Generic;
using System.Text.Json.Serialization;

[JsonObjectCreationHandling(JsonObjectCreationHandling.Populate)]
public sealed class AppConfig
{
    public DatabaseConfig Database { get; } = new();

    [JsonObjectCreationHandling(JsonObjectCreationHandling.Replace)]
    public List<string> Tags { get; } = new();
}
```

--------------------------------

### Register Polymorphic Types via Reflection

Source: https://github.com/xoofx/sharpyaml/blob/main/README.md

Configure derived type mappings at runtime using YamlPolymorphismOptions.

```csharp
var options = new YamlSerializerOptions
{
    PolymorphismOptions = new YamlPolymorphismOptions
    {
        DerivedTypeMappings =
        {
            [typeof(Animal)] =
            [
                new YamlDerivedType(typeof(Dog), "dog") { Tag = "!dog" },
                new YamlDerivedType(typeof(Cat), "cat") { Tag = "!cat" },
            ]
        }
    }
};
```

--------------------------------

### YAML and JSON Attribute Support in SharpYaml

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Annotate models with YAML-specific attributes (e.g., YamlPropertyName, YamlRequired) or System.Text.Json attributes (e.g., JsonPropertyName). YAML attributes take precedence. This allows for fine-grained control over serialization behavior, including property naming, order, ignoring, including non-public members, and capturing unknown keys.

```csharp
using System.Text.Json.Serialization;
using SharpYaml;
using SharpYaml.Serialization;

public class Employee
{
    // YAML attribute (takes precedence)
    [YamlPropertyName("employee_id")]
    public int Id { get; set; }

    // JSON attribute (also supported)
    [JsonPropertyName("full_name")]
    public string Name { get; set; } = "";

    // Control property order
    [YamlPropertyOrder(1)]
    public string Department { get; set; } = "";

    // Ignore during serialization
    [YamlIgnore]
    public string InternalCode { get; set; } = "";

    // Include non-public member
    [YamlInclude]
    internal string Notes { get; set; } = "";

    // Required member (throws if missing during deserialization)
    [YamlRequired]
    public string Email { get; set; } = "";

    // Capture unknown keys
    [YamlExtensionData]
    public Dictionary<string, object?>? ExtraData { get; set; }
}

var employee = new Employee
{
    Id = 123,
    Name = "Jane Smith",
    Department = "Engineering",
    Email = "jane@example.com",
    InternalCode = "SECRET",
    Notes = "Internal note"
};

string yaml = YamlSerializer.Serialize(employee);
// Output:
// employee_id: 123
// full_name: Jane Smith
// Department: Engineering
// Email: jane@example.com
// Notes: Internal note

// Deserialize with extension data capturing unknown keys
string yamlWithExtra = """
    employee_id: 456
    full_name: John Doe
    Department: Sales
    Email: john@example.com
    custom_field: extra value
    """;

var loaded = YamlSerializer.Deserialize<Employee>(yamlWithExtra);
// loaded.ExtraData contains {"custom_field": "extra value"}
```

--------------------------------

### Serialize and Deserialize with Reference Handling in C#

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Use YamlSerializerOptions with ReferenceHandling set to Preserve to enable anchors and aliases. This ensures that shared object references and cycles in the object graph are correctly serialized and restored during deserialization, maintaining object identity.

```csharp
using SharpYaml;

public class Node
{
    public string Name { get; set; } = "";
    public Node? Parent { get; set; }
    public List<Node> Children { get; set; } = new();
}

// Enable reference handling
var options = new YamlSerializerOptions
{
    ReferenceHandling = YamlReferenceHandling.Preserve
};

// Create object graph with cycles
var root = new Node { Name = "Root" };
var child1 = new Node { Name = "Child1", Parent = root };
var child2 = new Node { Name = "Child2", Parent = root };
root.Children.Add(child1);
root.Children.Add(child2);

// Serialize with anchors/aliases
string yaml = YamlSerializer.Serialize(root, options);
// Output includes anchors (&id001) and aliases (*id001) for references

// Deserialize preserves object identity
var restored = YamlSerializer.Deserialize<Node>(yaml, options);
// restored.Children[0].Parent == restored (same reference)
```

--------------------------------

### Mapping-based extension data

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/extension-data.md

Use this for a YAML-native representation to preserve YAML shapes. It utilizes SharpYaml.Model.YamlMapping to store extension data.

```csharp
using SharpYaml.Model;
using SharpYaml.Serialization;

public sealed class Config
{
    [YamlExtensionData]
    public YamlMapping? Extra { get; set; }
}
```

--------------------------------

### Load and Inspect YAML Content

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/model/nodes.md

Use YamlStream.Load to parse YAML from a string reader and access its contents as nodes. Cast the document contents to YamlMapping to access key-value pairs.

```csharp
using System.IO;
using SharpYaml.Model;

var stream = YamlStream.Load(new StringReader("a: 1\nb: 2\n"));
var doc = stream[0];

var mapping = (YamlMapping)doc.Contents!;
var a = (YamlValue)mapping[new YamlValue("a")]!;

var value = a.Value; // "1"
```

--------------------------------

### Serialize with Type and YamlSerializerContext

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/serialization/overview.md

Use overloads that accept a Type and YamlSerializerContext when APIs require a Type. This method is less performant due to reflection.

```csharp
var yaml = YamlSerializer.Serialize(value, typeof(MyConfig), MyYamlContext.Default);
```

--------------------------------

### Scan YAML tokens with Scanner

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/low-level/parser.md

Tokenizes raw YAML input using a low-level scanner. This operates at a lower level than the parser and provides access to token types, spans, and scalar values.

```csharp
using SharpYaml;

var scanner = new Scanner<StringLookAheadBuffer>(new StringLookAheadBuffer("a: 1\n"));
while (scanner.MoveNext())
{
    var token = scanner.Current;
    // Inspect token type, spans, and scalar values.
}
```

--------------------------------

### Use Generated Serialization Metadata

Source: https://github.com/xoofx/sharpyaml/blob/main/README.md

Utilize the generated context to perform serialization and deserialization.

```csharp
var context = MyYamlContext.Default;
var yaml = YamlSerializer.Serialize(config, context.MyConfig);
var roundTrip = YamlSerializer.Deserialize(yaml, context.MyConfig);
```

--------------------------------

### SharpYaml Collections Support

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

SharpYaml supports common collection types for serialization and deserialization, including arrays, lists, and dictionaries. It also provides options for handling non-string dictionary keys.

```APIDOC
## Collections Support

### Supported Types
- `T[]`, `List<T>`, `IList<T>`, `IReadOnlyList<T>`, `ICollection<T>`, `IEnumerable<T>`.
- `Dictionary<string, TValue>`, `IDictionary<string, TValue>`, `IReadOnlyDictionary<string, TValue>`.

### Non-string Dictionary Keys
- Supported when keys are scalars that can be emitted as YAML plain scalars.
- Controlled by `DictionaryKeyPolicy` and a “key converter” policy.
```

--------------------------------

### Load and Inspect YAML using Model Layer

Source: https://context7.com/xoofx/sharpyaml/llms.txt

Load YAML into a stream of documents and nodes using the model layer. This allows for reading and manipulating YAML without binding to CLR types.

```csharp
using System.IO;
using SharpYaml.Model;

// Load and inspect YAML
string yaml = """
database:
  host: localhost
  port: 5432
features:
  - auth
  - logging
"""

var stream = YamlStream.Load(new StringReader(yaml));
var doc = stream[0];

var root = (YamlMapping)doc.Contents!;
var database = (YamlMapping)root[new YamlValue("database")]!;
var host = (YamlValue)database[new YamlValue("host")]!;
Console.WriteLine($"Host: {host.Value}");  // Output: Host: localhost

var features = (YamlSequence)root[new YamlValue("features")]!;
foreach (var feature in features)
{
    Console.WriteLine($"Feature: {((YamlValue)feature).Value}");
}
```

--------------------------------

### Enable Reflection with MSBuild for NativeAOT

Source: https://github.com/xoofx/sharpyaml/blob/main/README.md

Override the default reflection behavior when publishing with NativeAOT by setting this MSBuild property in your app project.

```xml
<PropertyGroup>
  <SharpYamlIsReflectionEnabledByDefault>true</SharpYamlIsReflectionEnabledByDefault>
</PropertyGroup>
```

--------------------------------

### Parse YAML Document

Source: https://github.com/xoofx/sharpyaml/blob/main/site/docs/low-level/syntax-tree.md

Use YamlSyntaxTree.Parse to parse a YAML string into a syntax tree. This method includes trivia tokens by default.

```csharp
using SharpYaml.Syntax;

var text = "a: 1\n";
var tree = YamlSyntaxTree.Parse(text);
```

--------------------------------

### YamlSerializerOptions Configuration

Source: https://github.com/xoofx/sharpyaml/blob/main/site/specs/sharpyaml3_specs.md

Configuration class used to customize the behavior of the YamlSerializer, including naming policies, formatting, and YAML-specific settings.

```APIDOC
## YamlSerializerOptions

### Description
Defines settings for the serialization process, such as indentation, naming policies, and schema handling.

### Properties
- **PropertyNamingPolicy** (YamlNamingPolicy) - Optional - Naming policy for properties.
- **DictionaryKeyPolicy** (YamlNamingPolicy) - Optional - Naming policy for dictionary keys.
- **PropertyNameCaseInsensitive** (bool) - Optional - Whether property matching is case-insensitive.
- **DefaultIgnoreCondition** (YamlIgnoreCondition) - Optional - Condition for ignoring null or default values.
- **WriteIndented** (bool) - Optional - Whether to format the output with indentation.
- **IndentSize** (int) - Optional - Number of spaces for indentation (default: 2).
- **MappingOrder** (YamlMappingOrderPolicy) - Optional - Ordering policy for mappings (Declaration or Sorted).
- **Schema** (YamlSchemaKind) - Optional - YAML schema version (default: Core).
- **DuplicateKeyHandling** (YamlDuplicateKeyHandling) - Optional - Strategy for handling duplicate keys.
- **ReferenceHandling** (YamlReferenceHandling) - Optional - Handling of anchors and aliases.
```
Tokens:
Raw