Tomlyn

https://github.com/xoofx/tomlyn
Admin
High-performance TOML 1.1 parser and serializer for .NET with round-trippable syntax tree and...
Tokens:93,233
Snippets:593
Trust Score:10
License:BSD-2-Clause
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Lunet and build/serve the documentation site

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

Install the Lunet .NET global tool once, then build the site for production or serve it locally with live reload.

```sh
dotnet tool install -g lunet
```

```sh
lunet build          # production build -> .lunet/build/www/
lunet serve          # dev server with live reload at http://localhost:4000
```

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

### Quick Start: Serialize and Deserialize with Tomlyn

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

Shows basic usage of TomlSerializer.Serialize and Deserialize with an anonymous type and a Person class. Requires the Tomlyn namespace.

```csharp
using Tomlyn;

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

// Deserialize
var person = TomlSerializer.Deserialize<Person>(toml);
```

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

### Install Tomlyn package with dotnet add package

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

Adds the Tomlyn NuGet package to the project. Supports net8.0, net10.0, and netstandard2.0.

```sh
dotnet add package Tomlyn
```

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

### Serialize and deserialize with streams and TextWriter

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

Shows how to use the Stream and TextWriter overloads of TomlSerializer. The first example reads from a file stream (UTF-8) and the second writes to a TextWriter.

```csharp
// From a file stream (UTF-8)
using var stream = File.OpenRead("config.toml");
var config = TomlSerializer.Deserialize<MyConfig>(stream);

// To a TextWriter
using var writer = new StreamWriter("output.toml");
TomlSerializer.Serialize(writer, config);
```

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

### Represent date/time values with TomlDateTime

Source: https://github.com/xoofx/tomlyn/blob/main/site/docs/dom.md

Shows how to create offset date-time, local date-time, local date, and local time values using TomlDateTime and TomlDateTimeKind. The table below lists the TOML examples for each kind.

```csharp
using Tomlyn;

// Offset date-time
var odt = new TomlDateTime(new DateTimeOffset(2023, 7, 15, 12, 0, 0, TimeSpan.FromHours(2)), 0, TomlDateTimeKind.OffsetDateTimeByNumber);

// Local date-time (no timezone)
var ldt = new TomlDateTime(new DateTime(2023, 7, 15, 12, 0, 0), 0, TomlDateTimeKind.LocalDateTime);

// Local date
var ld = new TomlDateTime(2023, 7, 15);

// Local time
var lt = new TomlDateTime(new DateTimeOffset(1, 1, 1, 12, 30, 0, TimeSpan.Zero), 0, TomlDateTimeKind.LocalTime);
```

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

### Define and use a source-generated TomlSerializerContext

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

Create a partial class deriving from TomlSerializerContext, decorated with [TomlSerializable(typeof(MyConfig))]. Use the Default property to get the context and pass its generated property (MyConfig) to TomlSerializer.Serialize and Deserialize for strongly-typed round-tripping.

```csharp
using Tomlyn;
using Tomlyn.Serialization;

[TomlSerializable(typeof(MyConfig))]
internal partial class MyTomlContext : TomlSerializerContext { }

var context = MyTomlContext.Default;
var toml = TomlSerializer.Serialize(config, context.MyConfig);
var roundTrip = TomlSerializer.Deserialize(toml, context.MyConfig);
```

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

### Use Type-based overloads with a source-generated context

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

For APIs that accept a Type, use the overloads that take a context parameter. This example shows serializing and deserializing with typeof(MyConfig) and the context.

```csharp
var toml = TomlSerializer.Serialize(value, typeof(MyConfig), context);
var roundTrip = TomlSerializer.Deserialize(toml, typeof(MyConfig), context);
```

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

### Deserialize TOML with metadata store

Source: https://github.com/xoofx/tomlyn/blob/main/site/docs/dom.md

Deserializes a TOML string into a TomlTable while capturing metadata into a TomlMetadataStore. The example shows how to retrieve property metadata and access trivia, span, and display kind.

```csharp
using Tomlyn;
using Tomlyn.Model;
using Tomlyn.Serialization;

var toml = """
    # Application title
    title = "My App"

    # Database settings
    [database]
    host = "localhost" # primary host
    """;

var store = new TomlMetadataStore();
var options = new TomlSerializerOptions { MetadataStore = store };

var table = TomlSerializer.Deserialize<TomlTable>(toml, options)!;

// Retrieve metadata for a specific object
if (store.TryGetProperties(table, out var metadata) && metadata is not null)
{
    if (metadata.TryGetProperty("title", out var prop) && prop is not null)
    {
        // prop.LeadingTrivia  - comments before the key ("# Application title")
        // prop.TrailingTrivia - comments after the value
        // prop.Span           - source location (line, column, offset)
        // prop.DisplayKind    - how the value was written in the source
    }
}
```

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

### Serialized TOML output for array of tables

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

The TOML output produced for the Config example, using array-of-table headers. Empty collections write as ordinary empty arrays instead.

```toml
[[Package]]
Name = "core"

[[Package]]
Name = "tools"
```

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

### Set compile-time options with TomlSourceGenerationOptionsAttribute

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

Use TomlSourceGenerationOptionsAttribute to fix serialization options at build time. The example sets PropertyNamingPolicy to SnakeCaseLower, PreferredObjectCreationHandling to Replace, WriteIndented to true, IndentSize to 2, MaxDepth to 64, and DefaultIgnoreCondition to WhenWritingNull. PreferredObjectCreationHandling matches System.Text.Json: default is Replace, and Populate must be opted into explicitly to reuse mutable read-only members during deserialization.

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

[TomlSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.SnakeCaseLower,
    PreferredObjectCreationHandling = JsonObjectCreationHandling.Replace,
    WriteIndented = true,
    IndentSize = 2,
    MaxDepth = 64,
    DefaultIgnoreCondition = TomlIgnoreCondition.WhenWritingNull)]
[TomlSerializable(typeof(ServerConfig))]
internal partial class MyTomlContext : TomlSerializerContext { }
```

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

### TOML input for polymorphic deserialization

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

Example TOML input that uses the $type discriminator to select the derived type. The discriminator key defaults to $type and can be customized.

```toml
[[ animals ]]
"$type" = "cat"
Name = "Whiskers"
Indoor = true

[[ animals ]]
"$type" = "dog"
Name = "Rex"
Breed = "Labrador"
```

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

### TomlParser.Depth

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

Gets the current nesting depth of tables or arrays.

```APIDOC
## TomlParser.Depth

### Description
Gets the current nesting depth of tables or arrays.

### Method
Depth

### Endpoint
int Depth

### Parameters
None

### Request Example
```csharp
Console.WriteLine($"[table depth={parser.Depth}]");
```

### Response
#### Success Response
- **int** (integer) - The current depth.

### Response Example
```csharp
Console.WriteLine($"[table depth={parser.Depth}]");
```
```

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

### Old v0.x pattern: Toml.ToModel and Toml.FromModel

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

Shows the common v0.x pattern for converting TOML to a model and back using Toml.ToModel and Toml.FromModel.

```csharp
var model = Toml.ToModel(toml);            // TomlTable
var tomlOut = Toml.FromModel(model);
```

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

### TomlParser.Current

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

Gets the current parse event as a readonly reference. The event provides access to its kind and value accessors.

```APIDOC
## TomlParser.Current

### Description
Gets the current parse event as a readonly reference. The event provides access to its kind and value accessors.

### Method
Current

### Endpoint
ref readonly TomlParseEvent Current

### Parameters
None

### Request Example
```csharp
ref readonly var evt = ref parser.Current;
```

### Response
#### Success Response
- **TomlParseEvent** (TomlParseEvent) - The current parse event.

### Response Example
```csharp
ref readonly var evt = ref parser.Current;
```
```

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

### Registering Converters via Options

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

Shows how to register a converter at runtime using TomlSerializerOptions.Converters.

```APIDOC
## Registering Converters via Options

### Description
Converters can be registered at runtime by adding them to the Converters collection of TomlSerializerOptions.

### Method
Set the `Converters` property on `TomlSerializerOptions`.

### Parameters
- **Converters** (collection) - Required - A collection of converter instances.

### Request Example
```csharp
var options = new TomlSerializerOptions
{
    Converters = [new UpperCaseStringConverter()]
};
```
```

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

### Build and serialize a basic TOML table

Source: https://github.com/xoofx/tomlyn/blob/main/site/docs/dom.md

Creates a TomlTable with nested tables and an array, then serializes it to a TOML string. The output shows the resulting TOML with a top-level key and a [database] table.

```csharp
using Tomlyn;
using Tomlyn.Model;

var table = new TomlTable
{
    ["title"] = "My App",
    ["database"] = new TomlTable
    {
        ["host"] = "localhost",
        ["port"] = 5432L,
        ["enabled"] = true,
        ["ports"] = new TomlArray { 8000L, 8001L, 8002L },
    }
};

var toml = TomlSerializer.Serialize(table);
```

```toml
title = "My App"

[database]
host = "localhost"
port = 5432
enabled = true
ports = [8000, 8001, 8002]
```

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

### Configure TomlParserOptions and TomlSerializerOptions

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

Shows how to create TomlParserOptions with Tolerant mode, DecodeScalars, CaptureTrivia, and EagerStringValues, and TomlSerializerOptions with MaxDepth. These options are passed to TomlParser.Create.

```csharp
var parserOptions = new TomlParserOptions
{
    Mode = TomlParserMode.Tolerant,   // collect errors instead of throwing
    DecodeScalars = true,             // decode escape sequences
    CaptureTrivia = true,             // include comments/whitespace in events
    EagerStringValues = false,        // defer string materialization
};

var serializerOptions = new TomlSerializerOptions
{
    MaxDepth = 64,
};

var parser = TomlParser.Create(toml, parserOptions, serializerOptions);
```

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

### Serialize and deserialize TOML with TomlSerializer

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

Shows the main entry point TomlSerializer, which works like System.Text.Json.JsonSerializer. Defines a ServerConfig class, serializes an instance to TOML, then deserializes it back. By default, null properties are omitted from the output.

```csharp
using Tomlyn;

public sealed class ServerConfig
{
    public string Host { get; set; } = "localhost";
    public int Port { get; set; } = 8080;
    public bool Ssl { get; set; }
}

// Serialize to TOML
var config = new ServerConfig { Host = "example.com", Port = 443, Ssl = true };
var toml = TomlSerializer.Serialize(config);

// Deserialize from TOML
var roundTrip = TomlSerializer.Deserialize<ServerConfig>(toml)!;
```

```toml
Host = "example.com"
Port = 443
Ssl = true
```

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

### Configure TomlSerializerOptions

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

Shows how to configure TomlSerializerOptions with property naming, object creation handling, indentation, max depth, and ignore conditions. Notes that PropertyNamingPolicy defaults to null, MaxDepth=0 uses 64, and Replace matches System.Text.Json behavior.

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

var options = new TomlSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    PreferredObjectCreationHandling = JsonObjectCreationHandling.Replace,
    WriteIndented = true,
    IndentSize = 4,
    MaxDepth = 64,
    DefaultIgnoreCondition = TomlIgnoreCondition.WhenWritingNull,
};

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

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

### Opt into Populate globally with PreferredObjectCreationHandling

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

Shows a type-level JsonObjectCreationHandlingAttribute and a TomlSerializerOptions with PreferredObjectCreationHandling set to Populate. Under Populate, existing mutable collections are reused and appended to; read-only members without setters are left unchanged unless the attribute is applied at member level, which can throw.

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

[JsonObjectCreationHandling(JsonObjectCreationHandling.Populate)]
public sealed class ReleaserConfiguration
{
    public List<string> Channels { get; } = ["stable"];
}

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

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

### Configure TomlSerializerOptions for serialization

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

Create a TomlSerializerOptions instance with custom settings: SnakeCaseLower naming policy, Replace object creation handling, indented output with 4 spaces, max depth 64, and ignoring null values. Reuse the options instance to avoid repeated reflection/compilation overhead.

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

var options = new TomlSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
    PreferredObjectCreationHandling = JsonObjectCreationHandling.Replace,
    WriteIndented = true,
    IndentSize = 4,
    MaxDepth = 64,
    DefaultIgnoreCondition = TomlIgnoreCondition.WhenWritingNull,
};

var toml = TomlSerializer.Serialize(config, options);
```

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

### Traverse syntax tree with visitor and enumerable extensions

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

Shows two ways to traverse the DocumentSyntax tree: using a custom visitor (MyVisitor) and using the Descendants() and Tokens() enumerable extensions. The Tokens() method accepts includeCommentsAndWhitespaces parameter.

```csharp
using Tomlyn.Syntax;

// Visitor pattern
var visitor = new MyVisitor();
visitor.Visit(doc);

// Enumerable extensions
foreach (var node in doc.Descendants())
{
    if (node is StringValueSyntax str)
        Console.WriteLine(str.Value);
}

foreach (var token in doc.Tokens(includeCommentsAndWhitespaces: true))
{
    // Process every token
}
```

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

### Handle parsing errors with TomlException

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

Shows how to catch TomlException when deserializing invalid TOML. The exception provides SourceName, Line, and Column properties for precise error locations. The example uses a SourceName option to identify the source.

```csharp
try
{
    var config = TomlSerializer.Deserialize<ServerConfig>(
        "bad = [",
        new TomlSerializerOptions { SourceName = "config.toml" });
}
catch (TomlException ex)
{
    // ex.SourceName  → "config.toml"
    // ex.Line        → 1
    // ex.Column      → 7
    Console.WriteLine(ex.Message);
}
```

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

### Source generation with TomlSerializerContext (NativeAOT)

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

Declare a TomlSerializerContext with [TomlSerializable] to generate metadata for trimming/NativeAOT. Use the context's properties for serialization and deserialization.

```csharp
using Tomlyn;
using Tomlyn.Serialization;

[TomlSerializable(typeof(ServerConfig))]
internal partial class MyTomlContext : TomlSerializerContext { }

var toml = TomlSerializer.Serialize(config, MyTomlContext.Default.ServerConfig);
var roundTrip = TomlSerializer.Deserialize(toml, MyTomlContext.Default.ServerConfig);
```

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

### Parse TOML into a TomlTable and access values with casts

Source: https://github.com/xoofx/tomlyn/blob/main/site/docs/dom.md

Deserializes a TOML string into a TomlTable using TomlSerializer.Deserialize<TomlTable>. Values are accessed with casts: string for strings, long for integers, bool for booleans, and TomlArray for arrays. The example shows how to navigate nested tables and array elements.

```csharp
using Tomlyn;
using Tomlyn.Model;

var toml = """
    title = "My App"

    [database]
    host = "localhost"
    port = 5432
    enabled = true
    ports = [8000, 8001, 8002]
    """;

var table = TomlSerializer.Deserialize<TomlTable>(toml)!;

// Access values with casts
var title = (string)table["title"]!;               // "My App"
var db = (TomlTable)table["database"]!;
var host = (string)db["host"]!;                    // "localhost"
var port = (long)db["port"]!;                      // 5432
var enabled = (bool)db["enabled"]!;                // true
var ports = (TomlArray)db["ports"]!;
var firstPort = (long)ports[0]!;                   // 8000
```

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

### Registering Converters via Source Generation

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

Shows how to register converters at compile time using TomlSourceGenerationOptions and TomlSerializable attributes.

```APIDOC
## Registering Converters via Source Generation

### Description
Converters can be registered at compile time using source generation attributes on a TomlSerializerContext.

### Method
Apply `[TomlSourceGenerationOptions]` and `[TomlSerializable]` attributes to a partial class deriving from TomlSerializerContext.

### Parameters
- **Converters** (array of Type) - Required - The converter types to include.
- **type** (Type) - Required - The type to make serializable.

### Request Example
```csharp
[TomlSourceGenerationOptions(Converters = [typeof(UpperCaseStringConverter)])]
[TomlSerializable(typeof(Config))]
internal partial class MyTomlContext : TomlSerializerContext { }
```
```

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

### Create TomlParser from a TextReader

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

Shows how to create a TomlParser from a file stream using a StreamReader. The parser accepts string and TextReader inputs.

```csharp
// From a file stream
using var reader = new StreamReader("config.toml");
var parser = TomlParser.Create(reader);
```

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

### TomlLexer.Create

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

Creates a TomlLexer instance to tokenize TOML input. Use it for syntax highlighting, quick validation, or building custom parsers.

```APIDOC
## TomlLexer.Create

### Description
Creates a lexer that produces a flat stream of tokens from TOML input.

### Method
Create

### Parameters
- **toml** (string) - Required - The TOML content to tokenize.
- **options** (TomlLexerOptions) - Optional - Controls decoding behavior.
- **sourceName** (string) - Optional - The source name for diagnostics.

### Request Example
```csharp
var lexer = TomlLexer.Create("name = \"Ada\"", sourceName: "config.toml");
```

### Response
Returns a TomlLexer instance that can be iterated with MoveNext().

### Usage Example
```csharp
using Tomlyn.Parsing;

var lexer = TomlLexer.Create("name = \"Ada\"", sourceName: "config.toml");
while (lexer.MoveNext())
{
    var token = lexer.Current;
    Console.WriteLine($"{token.Kind} = {token.StringValue} @ {lexer.CurrentSpan}");
}
```
```

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

### Create an inline table with TomlTable(inline: true)

Source: https://github.com/xoofx/tomlyn/blob/main/site/docs/dom.md

Passes true to the TomlTable constructor to emit an inline table. The comment shows the serialized output: point = { x = 1, y = 2 }.

```csharp
var table = new TomlTable
{
    ["point"] = new TomlTable(inline: true)
    {
        ["x"] = 1L,
        ["y"] = 2L,
    }
};

var toml = TomlSerializer.Serialize(table);
// point = { x = 1, y = 2 }
```

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

### Implement a custom TomlConverter<T>

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

Shows a concrete converter that uppercases strings on read and lowercases on write. Override Read and Write to customize type mapping.

```csharp
using Tomlyn.Serialization;

public sealed class UpperCaseStringConverter : TomlConverter<string>
{
    public override string? Read(TomlReader reader)
        => reader.GetString().ToUpperInvariant();

    public override void Write(TomlWriter writer, string value)
        => writer.WriteStringValue(value.ToLowerInvariant());
}
```

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

### SyntaxVisitor.Visit

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

Visits a syntax node using the visitor pattern. Override Visit methods for specific node types to process them.

```APIDOC
## SyntaxVisitor.Visit

### Description
Visits a syntax node using the visitor pattern. Override Visit methods for specific node types to process them.

### Method
Visit

### Signature
`public void Visit(SyntaxNode node)`

### Parameters
- **node** (SyntaxNode) - Required - The node to visit.

### Example
```csharp
using Tomlyn.Syntax;

public sealed class StringCollector : SyntaxVisitor
{
    public List<string> Strings { get; } = new();

    protected override void Visit(StringValueSyntax node)
    {
        if (node.Value is not null)
            Strings.Add(node.Value);
        base.Visit(node);
    }
}

var collector = new StringCollector();
collector.Visit(doc);
```
```

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

### Basic TomlSerializer usage

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

Shows the new TomlSerializer.Serialize and Deserialize methods replacing Toml.FromModel and Toml.ToModel. The first line serializes a value to TOML, the second deserializes a TOML string into a strongly-typed model.

```csharp
using Tomlyn;

var toml = TomlSerializer.Serialize(value);
var model = TomlSerializer.Deserialize<MyType>(toml);
```

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

### Read and write TOML using Stream overloads

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

Shows how to use Tomlyn's Stream overloads to avoid manual StreamReader/StreamWriter boilerplate. Reads from a file stream and writes to another. Note that Tomlyn reads the entire stream into memory before parsing.

```csharp
using System.IO;
using Tomlyn;

// Read from a file stream
using var input = File.OpenRead("config.toml");
var config = TomlSerializer.Deserialize<ServerConfig>(input)!;

// Write to a file stream
using var output = File.Create("config_out.toml");
TomlSerializer.Serialize(output, config);
```

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

### TomlConverterFactory Implementation

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

Shows how to implement a converter factory for open generic types or types needing runtime inspection.

```APIDOC
## TomlConverterFactory Implementation

### Description
Converter factories allow dynamic converter creation for types that cannot be handled by a single TomlConverter<T>.

### Method
Override `CanConvert(Type typeToConvert)` and `CreateConverter(Type typeToConvert, TomlSerializerOptions options)`.

### Parameters
- **typeToConvert** (Type) - Required - The type to convert.
- **options** (TomlSerializerOptions) - Required - The serializer options.

### Request Example
```csharp
public sealed class MyConverterFactory : TomlConverterFactory
{
    public override bool CanConvert(Type typeToConvert)
        => typeToConvert.IsEnum;

    public override TomlConverter CreateConverter(Type typeToConvert, TomlSerializerOptions options)
        => /* return a concrete TomlConverter<T> for the enum type */;
}
```
```

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

### Configure TomlStringStylePreferences for serialization

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

Shows how to set TomlStringStylePreferences on TomlSerializerOptions to control string emission. The defaults are Basic style, PreferLiteralWhenNoEscapes false, and AllowHexEscapes true.

```csharp
var options = new TomlSerializerOptions
{
    StringStylePreferences = new TomlStringStylePreferences
    {
        DefaultStyle = TomlStringStyle.Basic,           // default
        PreferLiteralWhenNoEscapes = false,             // default
        AllowHexEscapes = true,                         // default
    }
};
```

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

### TomlConverter<T> Implementation

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

Shows how to implement a custom converter by deriving from TomlConverter<T> and overriding Read and Write methods.

```APIDOC
## TomlConverter<T> Implementation

### Description
Custom converters are implemented by deriving from TomlConverter<T> and overriding the Read and Write methods to customize type mapping.

### Method
Override `Read(TomlReader reader)` and `Write(TomlWriter writer, T value)`.

### Parameters
- **reader** (TomlReader) - Required - The reader used to read the TOML value.
- **writer** (TomlWriter) - Required - The writer used to write the TOML value.
- **value** (T) - Required - The value to write.

### Request Example
```csharp
public sealed class UpperCaseStringConverter : TomlConverter<string>
{
    public override string? Read(TomlReader reader)
        => reader.GetString().ToUpperInvariant();

    public override void Write(TomlWriter writer, string value)
        => writer.WriteStringValue(value.ToLowerInvariant());
}
```

### Response
#### Success Response
No return value for Write; Read returns the converted value.
```

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

### Implement a TomlConverterFactory

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

Shows a factory for open generic types or types needing runtime inspection. CanConvert checks the type and CreateConverter returns a concrete converter.

```csharp
using Tomlyn.Serialization;

public sealed class MyConverterFactory : TomlConverterFactory
{
    public override bool CanConvert(Type typeToConvert)
        => typeToConvert.IsEnum;

    public override TomlConverter CreateConverter(Type typeToConvert, TomlSerializerOptions options)
        => /* return a concrete TomlConverter<T> for the enum type */;
}
```

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

### Serialize and deserialize a record with TomlSerializer

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

Shows how to use TomlSerializer with TomlSerializerOptions and a camelCase naming policy. The serialized output is shown in comments: name = "Ada" and age = 37. Deserialization uses the same options.

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

public sealed record Person(string Name, int Age);

var options = new TomlSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };

var toml = TomlSerializer.Serialize(new Person("Ada", 37), options);

// name = "Ada"
// age = 37

var person = TomlSerializer.Deserialize<Person>(toml, options);
```

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

### Registering Converters via Attribute

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

Shows how to apply a converter to a property using the TomlConverter attribute.

```APIDOC
## Registering Converters via Attribute

### Description
Converters can be applied to individual properties using the TomlConverter attribute, which works with reflection-based serialization.

### Method
Apply the `[TomlConverter(typeof(ConverterType))]` attribute to a property.

### Parameters
- **type** (Type) - Required - The converter type to use.

### Request Example
```csharp
public sealed class Config
{
    [TomlConverter(typeof(UpperCaseStringConverter))]
    public string Name { get; set; } = "";
}
```
```

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

### TomlParser.Create(string, TomlParserOptions, TomlSerializerOptions)

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

Creates a TomlParser instance with custom parser and serializer options.

```APIDOC
## TomlParser.Create(string, TomlParserOptions, TomlSerializerOptions)

### Description
Creates a TomlParser instance with custom parser and serializer options.

### Method
Create

### Endpoint
TomlParser.Create(string toml, TomlParserOptions parserOptions, TomlSerializerOptions serializerOptions)

### Parameters
#### Parameters
- **toml** (string) - Required - The TOML content to parse.
- **parserOptions** (TomlParserOptions) - Required - Options controlling parsing behavior.
- **serializerOptions** (TomlSerializerOptions) - Required - Options controlling serialization limits.

### Request Example
```csharp
var parserOptions = new TomlParserOptions
{
    Mode = TomlParserMode.Tolerant,
    DecodeScalars = true,
    CaptureTrivia = true,
    EagerStringValues = false,
};

var serializerOptions = new TomlSerializerOptions
{
    MaxDepth = 64,
};

var parser = TomlParser.Create(toml, parserOptions, serializerOptions);
```

### Response
#### Success Response
- **parser** (TomlParser) - The parser instance.

### Response Example
```csharp
var parser = TomlParser.Create(toml, parserOptions, serializerOptions);
```
```

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

### Source Generation with TomlSerializerContext

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

Defines a TomlSerializerContext with source-generated metadata for MyConfig. Uses TomlSourceGenerationOptions and TomlSerializable attributes, then serializes/deserializes with the context.

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

public sealed class MyConfig
{
    public string? Global { get; set; }
}

[TomlSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    PreferredObjectCreationHandling = JsonObjectCreationHandling.Replace)]
[TomlSerializable(typeof(MyConfig))]
internal partial class MyTomlContext : TomlSerializerContext
{
}

var config = TomlSerializer.Deserialize(toml, MyTomlContext.Default.MyConfig);
var tomlOut = TomlSerializer.Serialize(config, MyTomlContext.Default.MyConfig);
```

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

### Single Value Or Array Collections with TomlSingleOrArray

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

Defines a PackagingConfiguration class with a RuntimeIdentifiers list annotated with TomlSingleOrArray and JsonPropertyName. Allows TOML payloads to use a single value or an array for the 'rid' key.

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

public sealed class PackagingConfiguration
{
    public PackagingConfiguration()
    {
        RuntimeIdentifiers = new List<string>();
    }

    [TomlSingleOrArray]
    [JsonPropertyName("rid")]
    public List<string> RuntimeIdentifiers { get; }
}
```

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

### Apply Tomlyn serialization formatting attributes to a class

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

Shows how to apply TomlMappingOrder, TomlDottedKeyHandling, TomlTableArrayStyle, TomlInlineTable, and TomlStringStyle attributes to a class to override global formatting options for serialization. These attributes work with both reflection-based metadata and source-generated TomlSerializerContext metadata.

```csharp
using Tomlyn;
using Tomlyn.Serialization;

[TomlMappingOrder(TomlMappingOrderPolicy.Alphabetical)]
[TomlDottedKeyHandling(TomlDottedKeyHandling.Expand)]
public sealed class Config
{
    [TomlTableArrayStyle(TomlTableArrayStyle.Headers)]
    public Package[] Package { get; set; } = [];

    [TomlInlineTable(TomlInlineTablePolicy.Always)]
    public Owner Owner { get; set; } = new();

    [TomlStringStyle(TomlStringStyle.Literal, PreferLiteralWhenNoEscapes = TomlBooleanPreference.True)]
    public string Description { get; set; } = "plain text";
}
```

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

### ITomlMetadataStore.TryGetProperties

Source: https://github.com/xoofx/tomlyn/blob/main/site/docs/dom.md

Retrieves metadata for a specified object instance from the metadata store.

```APIDOC
## TryGetProperties

### Description
Retrieves metadata for a specified object instance from the metadata store.

### Method
TryGetProperties

### Signature
bool TryGetProperties(object instance, out TomlPropertiesMetadata? metadata)

### Parameters
- **instance** (object) - Required - The object instance for which to retrieve metadata.
- **metadata** (TomlPropertiesMetadata?) - Output parameter that receives the metadata if found.

### Returns
- **bool** - True if metadata was found; otherwise, false.

### Remarks
This method is part of the ITomlMetadataStore interface. The built-in TomlMetadataStore implementation uses a ConditionalWeakTable so metadata is garbage-collected along with the target object.
```

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

### Define a TomlSerializerContext for source generation

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

Shows how to define a partial TomlSerializerContext class with the TomlSerializableAttribute to enable source generation for a type.

```csharp
using Tomlyn.Serialization;

[TomlSerializable(typeof(MyType))]
internal partial class MyTomlContext : TomlSerializerContext
{
}
```

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

### Serialize typed collections as arrays of tables

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

Shows a Config class with a Package array property and a Package class. When serialized, the collection writes as semantic array-of-table headers ([[Package]]) by default.

```csharp
public sealed class Config
{
    public Package[] Package { get; set; } = [];
}

public sealed class Package
{
    public string Name { get; set; } = "";
}
```

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

### TomlSerializer with options

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

Shows how to pass TomlSerializerOptions to control serialization, here enabling indented output via WriteIndented = true.

```csharp
var options = new TomlSerializerOptions { WriteIndented = true };
var toml = TomlSerializer.Serialize(value, options);
```

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

### Iterate over diagnostics in DiagnosticsBag

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

Iterates over doc.Diagnostics, printing each diagnostic's Kind, Message, and Span. The Kind is Error or Warning, Span is the source location, and Message is the description.

```csharp
foreach (var diag in doc.Diagnostics)
{
    // diag.Kind    - Error or Warning
    // diag.Span    - source location
    // diag.Message - description
    Console.WriteLine($"{diag.Kind}: {diag.Message} at {diag.Span}");
}
```

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

### New v1.0 DOM usage with TomlSerializer

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

Shows the v1.0 way to use the DOM types (TomlTable) through TomlSerializer.Deserialize and TomlSerializer.Serialize.

```csharp
using Tomlyn;
using Tomlyn.Model;

var table = TomlSerializer.Deserialize<TomlTable>(toml)!;
var tomlOut = TomlSerializer.Serialize(table);
```

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

### Configure TomlSerializerOptions for serialization

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

Creates an immutable TomlSerializerOptions instance with camelCase naming, indented output, and error handling for duplicate keys. The options are reused for both serialization and deserialization.

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

var options = new TomlSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true,
    IndentSize = 2,
    DefaultIgnoreCondition = TomlIgnoreCondition.WhenWritingNull,
    DuplicateKeyHandling = TomlDuplicateKeyHandling.Error,
};

var toml = TomlSerializer.Serialize(config, options);
var roundTrip = TomlSerializer.Deserialize<ServerConfig>(toml, options);
```

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

### ITomlMetadataStore.SetProperties

Source: https://github.com/xoofx/tomlyn/blob/main/site/docs/dom.md

Attaches metadata to a specified object instance in the metadata store.

```APIDOC
## SetProperties

### Description
Attaches metadata to a specified object instance in the metadata store.

### Method
SetProperties

### Signature
void SetProperties(object instance, TomlPropertiesMetadata? metadata)

### Parameters
- **instance** (object) - Required - The object instance to which metadata will be attached.
- **metadata** (TomlPropertiesMetadata?) - Required - The metadata to attach.

### Remarks
This method is part of the ITomlMetadataStore interface. The built-in TomlMetadataStore implementation uses a ConditionalWeakTable so metadata is garbage-collected along with the target object.
```

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

### Implement a SyntaxVisitor to collect string values

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

Defines a StringCollector visitor that overrides Visit(StringValueSyntax) to collect string values into a list. The visitor is then used to visit the document.

```csharp
using Tomlyn.Syntax;

public sealed class StringCollector : SyntaxVisitor
{
    public List<string> Strings { get; } = new();

    protected override void Visit(StringValueSyntax node)
    {
        if (node.Value is not null)
            Strings.Add(node.Value);
        base.Visit(node);
    }
}

var collector = new StringCollector();
collector.Visit(doc);
```

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

### TomlParser.Create(TextReader)

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

Creates a TomlParser instance from a TextReader, allowing parsing from a file stream or other text sources.

```APIDOC
## TomlParser.Create(TextReader)

### Description
Creates a TomlParser instance from a TextReader, allowing parsing from a file stream or other text sources.

### Method
Create

### Endpoint
TomlParser.Create(TextReader reader)

### Parameters
#### Parameters
- **reader** (TextReader) - Required - The text reader providing the TOML content.

### Request Example
```csharp
using var reader = new StreamReader("config.toml");
var parser = TomlParser.Create(reader);
```

### Response
#### Success Response
- **parser** (TomlParser) - The parser instance.

### Response Example
```csharp
using var reader = new StreamReader("config.toml");
var parser = TomlParser.Create(reader);
```
```

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

### TomlWriter Methods

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

Lists the methods available on TomlWriter for writing TOML tokens and scalar values.

```APIDOC
## TomlWriter Methods

### Description
TomlWriter provides token-level access to write TOML data during custom converter operations.

### Methods
- `WritePropertyName(string)` - Write a key.
- `WriteStringValue(string)` - Write a string value.
- `WriteIntegerValue(long)` - Write an integer value.
- `WriteFloatValue(double)` - Write a float value.
- `WriteBooleanValue(bool)` - Write a boolean value.
- `WriteDateTimeValue(TomlDateTime)` - Write a TomlDateTime value.
- `WriteStartTable()` / `WriteEndTable()` - Write a table.
- `WriteStartInlineTable()` / `WriteEndInlineTable()` - Write an inline table.
- `WriteStartArray()` / `WriteEndArray()` - Write an array.
- `WriteStartTableArray()` / `WriteEndTableArray()` - Write an array of tables.
```

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

### Iterate tokens with TomlLexer

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

Creates a TomlLexer from a TOML string and iterates over tokens, printing each token's kind, string value, and span. Use for syntax highlighting or custom parsing.

```csharp
using Tomlyn.Parsing;

var lexer = TomlLexer.Create("name = \"Ada\"", sourceName: "config.toml");
while (lexer.MoveNext())
{
    var token = lexer.Current;
    Console.WriteLine($"{token.Kind} = {token.StringValue} @ {lexer.CurrentSpan}");
}
```

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

### Register converter via TomlSerializerOptions

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

Registers a converter at runtime by adding it to the Converters collection of TomlSerializerOptions.

```csharp
var options = new TomlSerializerOptions
{
    Converters = [new UpperCaseStringConverter()]
};
```

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

### Define a TomlSerializerContext with [TomlSerializable]

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

Declares a partial context class inheriting from TomlSerializerContext and annotates it with [TomlSerializable] for the root type ServerConfig. The generator produces a Default singleton and a typed TomlTypeInfo<T> property for each root, discovering nested types transitively.

```csharp
using Tomlyn.Serialization;

public sealed class ServerConfig
{
    public string Host { get; set; } = "localhost";
    public int Port { get; set; } = 8080;
}

[TomlSerializable(typeof(ServerConfig))]
internal partial class MyTomlContext : TomlSerializerContext { }
```

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

### Use TryDeserialize to handle invalid TOML without exceptions

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

Uses TomlSerializer.TryDeserialize to attempt deserialization without throwing. On failure, config is null/default. Prefer this API when invalid TOML input is expected, such as user-provided configuration.

```csharp
if (!TomlSerializer.TryDeserialize<MyConfig>(toml, out var config))
{
    // config is null/default - parsing or mapping failed
}
```

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

### Use generated TomlTypeInfo<T> metadata

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

Shows how to use the generated context's type info to serialize and deserialize with TomlSerializer.

```csharp
var context = MyTomlContext.Default;
var toml = TomlSerializer.Serialize(value, context.MyType);
var model = TomlSerializer.Deserialize(toml, context.MyType);
```

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

### Define multiple serialization contexts with TomlSerializable

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

Defines two separate partial context classes for different parts of an application. Each context is marked with TomlSerializable for the respective root type.

```csharp
[TomlSerializable(typeof(ServerConfig))]
internal partial class ServerContext : TomlSerializerContext { }

[TomlSerializable(typeof(DatabaseConfig))]
internal partial class DatabaseContext : TomlSerializerContext { }
```

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

### TomlPropertiesMetadata.TryGetProperty

Source: https://github.com/xoofx/tomlyn/blob/main/site/docs/dom.md

Retrieves per-property metadata for a specified key from the properties metadata.

```APIDOC
## TryGetProperty

### Description
Retrieves per-property metadata for a specified key from the properties metadata.

### Method
TryGetProperty

### Signature
bool TryGetProperty(string key, out TomlPropertyMetadata? metadata)

### Parameters
- **key** (string) - Required - The property key.
- **metadata** (TomlPropertyMetadata?) - Output parameter that receives the metadata if found.

### Returns
- **bool** - True if metadata was found; otherwise, false.

### Remarks
This method is part of the TomlPropertiesMetadata class. Each TomlPropertyMetadata contains LeadingTrivia, TrailingTrivia, TrailingTriviaAfterEndOfLine, Span, and DisplayKind properties.
```

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

### DocumentSyntax.Tokens()

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

Enumerates all tokens in the document, optionally including comments and whitespace.

```APIDOC
## DocumentSyntax.Tokens()

### Description
Enumerates all tokens in the document, optionally including comments and whitespace.

### Method
Tokens

### Signature
`public IEnumerable<SyntaxToken> Tokens(bool includeCommentsAndWhitespaces = false)`

### Parameters
- **includeCommentsAndWhitespaces** (bool) - Optional - If true, includes comment and whitespace tokens.

### Return Value
- **IEnumerable<SyntaxToken>** - An enumerable of tokens.

### Example
```csharp
using Tomlyn.Syntax;

foreach (var token in doc.Tokens(includeCommentsAndWhitespaces: true))
{
    // Process every token
}
```
```

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

### Register converter via source generation

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

Registers a converter at compile time using TomlSourceGenerationOptions and TomlSerializable attributes on a TomlSerializerContext.

```csharp
[TomlSourceGenerationOptions(Converters = [typeof(UpperCaseStringConverter)])]
[TomlSerializable(typeof(Config))]
internal partial class MyTomlContext : TomlSerializerContext { }
```

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

### Strict parsing with SyntaxParser.ParseStrict

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

Use this snippet to parse TOML with strict 'throw on first error' behavior. It requires the Tomlyn.Parsing namespace and returns a DocumentSyntax. The sourceName parameter is used in error reporting.

```csharp
using Tomlyn.Parsing;

var doc = SyntaxParser.ParseStrict(toml, sourceName: "config.toml");
```

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

### Property naming with JsonPropertyName and JsonIgnore

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

Use JsonPropertyName to map C# properties to TOML keys with underscores, and JsonIgnore to exclude a computed property from serialization.

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

public sealed class Person
{
    [JsonPropertyName("first_name")]
    public string FirstName { get; set; } = "";

    [JsonPropertyName("last_name")]
    public string LastName { get; set; } = "";

    [JsonIgnore]
    public string FullName => $"{FirstName} {LastName}";
}
```

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

### Untyped Model: Deserialize to TomlTable

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

Deserializes a TOML string into a TomlTable and accesses a global key. Demonstrates using the Tomlyn.Model namespace and serializing the model back to TOML.

```csharp
using Tomlyn;
using Tomlyn.Model;

var toml = @"global = ""this is a string""
# This is a comment of a table
[my_table]
key = 1 # Comment a key
value = true
list = [4, 5, 6]
";

var model = TomlSerializer.Deserialize<TomlTable>(toml)!;
var global = (string)model["global"]!;

Console.WriteLine(global);
Console.WriteLine(TomlSerializer.Serialize(model));
```

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

### Use generated TomlTypeInfo<T> property for serialization

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

Recommended approach: access the generated TomlTypeInfo<T> property from the context and pass it to TomlSerializer.Serialize and Deserialize. This avoids passing a Type and provides strongly-typed metadata.

```csharp
using Tomlyn;

var context = MyTomlContext.Default;

var toml = TomlSerializer.Serialize(config, context.ServerConfig);
var roundTrip = TomlSerializer.Deserialize(toml, context.ServerConfig);
```

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

### Constructor-based deserialization with JsonConstructor

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

Use JsonConstructor to select a constructor for deserialization, allowing immutable properties to be set during construction.

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

public sealed class Endpoint
{
    [JsonConstructor]
    public Endpoint(string host, int port) { Host = host; Port = port; }

    public string Host { get; }
    public int Port { get; }
}
```

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

### Handle unknown discriminators globally with TomlSerializerOptions

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

Configures global unknown derived type handling by setting TomlPolymorphismOptions.UnknownDerivedTypeHandling to FallBackToBaseType. This is used when no attribute-level setting is specified. Note that TomlUnknownDerivedTypeHandling.Unspecified cannot be used here and throws ArgumentOutOfRangeException.

```csharp
var options = new TomlSerializerOptions
{
    PolymorphismOptions = new TomlPolymorphismOptions
    {
        UnknownDerivedTypeHandling = TomlUnknownDerivedTypeHandling.FallBackToBaseType,
    },
};
```
Tokens:
Raw