Table of Contents

Runnable samples

The repository ships runnable, self-contained sample projects for Bodu.Text.Toml under samples/Text.Toml/. Both samples are offline and deterministic - they run against small committed Data/*.toml files - and are members of bodu.slnx, built and executed by CI, so the code they show cannot drift from the current API. Each sample's README documents every scenario individually: its intent, what the code does, the output to expect, and the APIs demonstrated.

Run either sample from the repository root:

dotnet run --project samples/Text.Toml/<SampleName>

The samples

Bodu.Text.Toml.Samples.TomlBasics

The front door: the TomlSerializer POCO surface, shaped after System.Text.Json. A committed config file (nested table, array of tables) deserializes into a typed graph and round-trips; TOML's four native date-time kinds arrive as DateOnly, TimeOnly, and DateTimeOffset - no invented midnights; wire names layer a naming policy (NamingPolicy) under the attribute family ([PropertyName], [Ignore], [Required]) with TomlStringEnumConverter re-casing enums; and the two wire knobs - TomlSpecVersion gating the TOML v1.1.0 grammar on parse and TomlByteArrayHandling choosing the byte[] shape - each shown with both settings. Package: Bodu.Text.Toml.

Bodu.Text.Toml.Samples.TomlDocuments

The layers beneath the serializer, mirroring the System.Text.Json stack: the mutable TomlNode DOM (parse, edit through indexers, graft new tables, re-emit), the read-only TomlDocument DOM (one parse, cheap TomlElement cursors, typed getters, EnumerateObject, TryGetProperty probing), the allocation-free Utf8TomlWriter / Utf8TomlReader token surface, and streaming reads across buffer boundaries with a resumable TomlReaderState - the Utf8JsonReader pattern, demonstrated by splitting the document mid-token and matching the one-shot token count. Package: Bodu.Text.Toml.

Guarded documentation

The TOML guides under docs/guides/serialization/toml/ carry compile-guarded snippets: examples marked with a <!-- compile --> sentinel are compiled against the current public API by DocumentationSnippetCompileTests in the library's test project (Regression tier), so shown code cannot silently rot.

  • TOML guides - the full serializer, DOM, and reader/writer documentation.
  • Bencode samples - the same System.Text.Json-aligned stack for BEP 3 Bencode.