Table of Contents

Bodu.Text.Toml Namespace

Package

Bodu.Text.Toml

Purpose

Bodu.Text.Toml is a TOML (v1.0.0 / v1.1.0) library for .NET 8. It maps plain CLR objects to and from TOML through a configurable converter model, over a low-level forward-only token reader and writer, with both a mutable and a read-only document object model.

The public surface layers four tiers: a static TomlSerializer for object mapping, the Utf8TomlReader / Utf8TomlWriter ref struct pair for forward-only token processing, a mutable TomlNode DOM, and a read-only TomlDocument DOM. The twin library Bodu.Text.Bencode applies the identical shape to Bencode.

The types are organised into folders/namespaces by surface (Reader, Writer, Document, Nodes, Serialization). The reader enforces strict TOML v1.0.0 by default and opts in to TOML v1.1.0 grammar additions through the TomlSpecVersion selector on the options. For EditorConfig-style INI configuration, see Bodu.Text.Ini; for binary-to-text encodings (Base16 / Base32 / Base64 / Base58 / Base85), see the companion Bodu.Text.Encoding package.

Static documentation

Key types

Serializer (Bodu.Text.Toml)

Low-level reader / writer

Document object models

Converters and attributes (Bodu.Text.Toml.Serialization)

Example

using Bodu.Text.Toml;

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

string toml = TomlSerializer.Serialize(new ServerConfig { Host = "localhost", Port = 8080 });
ServerConfig config = TomlSerializer.Deserialize<ServerConfig>(toml);

// Edit a document without a model:
using Bodu.Text.Toml.Nodes;
TomlNode node = TomlNode.Parse(utf8Toml)!;
node["server"]!["port"] = 9090;
byte[] back = node.ToUtf8Bytes();

Notes

  • Full serializer surface. The converter, attribute, callback, naming-policy (and TomlSerializerDefaults.Web), and enum-converter surfaces are all present.
  • Shared serialization core. The library references Bodu.Text.Serialization for the attribute family, the naming policies, the ignore / creation / unmapped-member enums, and the serialization callback interfaces, and compiles that package's shared metadata resolver and converter engine under its own format symbol; the reader, writer, DOMs, and format converters are TOML-specific. Its twin, Bodu.Text.Bencode, mirrors it type for type for Bencode; Bodu.Text.Yaml shares the architecture with a YAML-tuned surface.
  • Value mapping. string / char / Guid / Uri / Version → string, TimeSpan → the invariant "c"-format string, the integer family (including Int128 / UInt128 within the i64 range) → integer, double / float / Half → float, decimal → float or a lossless string via TomlDecimalHandling, bool → boolean, and DateTimeOffset / DateTime / DateOnly / TimeOnly → the four RFC 3339 date-time forms; byte[] and memory-of-byte → an integer array (or a Base64 string via TomlByteArrayHandling); enums → member-name strings. Collections (arrays, lists, sets, queues, stacks, and the concurrent collections) map to arrays, with a Stack<T> round-trip reversing the stack (the writer emits pop order). Dictionaries map to tables in insertion order; keys may be strings, integers, enums, Guid, bool, or char, written as bare or quoted table keys. An object-typed member writes its runtime type and reads back as a TomlElement; the read-only DOM types participate directly. Public fields participate via IncludeFields or [Include]. The full per-type list is in the built-in converter catalog.
  • Table root. A TOML document root must map to a table, so a top-level scalar or array throws. Output is canonical TOML in document order, so [PropertyOrder] is honored.
  • Spec-version selection. Parsing defaults to strict v1.0.0; setting SpecVersion to V1_1 accepts the v1.1.0 additions (\e and \xHH escapes, seconds-less times, multi-line / trailing-comma inline tables). The writer always emits output valid under both versions.
  • Errors. Malformed input surfaces through TomlFormatException (with line, column, and offset); binding failures through TomlSerializationException.
  • See also: the introduction, core concepts, and getting-started; the Using TOML and writing converters guides; and the sibling Bencode and YAML libraries.

Namespaces

Bodu.Text.Toml.Document
Bodu.Text.Toml.Nodes
Bodu.Text.Toml.Reader
Bodu.Text.Toml.Serialization
Bodu.Text.Toml.Writer

Classes

TomlFormatException

Represents an error that occurs when TOML data is malformed or violates the TOML specification.

TomlSerializationException

The exception thrown when a value cannot be bound to or from a TOML document during serialization - for example a type mismatch, a missing required member, or a value TOML cannot represent.

TomlSerializer

Provides static methods for serializing values to normalized TOML text and deserializing TOML back into values, mapping plain CLR objects to and from the format through configurable converters.

TomlSerializerOptions

Configures how values are serialized to and deserialized from TOML: the converters to use, the property naming policy, the default ignore condition, and the maximum nesting depth.

Enums

TomlByteArrayHandling

Specifies how a byte array is represented in TOML, which has no native binary type.

TomlDecimalHandling

Specifies how a decimal value is represented in TOML, which has no native decimal type.

TomlSerializerDefaults

Specifies a base set of defaults applied when a TomlSerializerOptions instance is created for a particular usage scenario.

TomlSpecVersion

Identifies the version of the TOML specification the reader enforces. The version controls a small number of grammar features that TOML v1.1.0 added relative to TOML v1.0.0.

TomlTokenType

Identifies the kind of token a forward-only TOML reader is positioned on.

TomlValueKind

Identifies the concrete type of a TOML value. The members correspond to the value types defined by the TOML specification.