Bodu.Text.Toml.Serialization Namespace

Package: Bodu.Text.Toml 1.0.0

Bodu.Text.Toml.Serialization

Purpose

Bodu.Text.Toml.Serialization holds the extensibility surface of the TomlSerializer: the converter base types you derive from to control how a CLR type is written and read, and the built-in enum converters. A converter reads through the normalized TomlDocumentReader and writes through the Utf8TomlWriter. The attribute family, naming policies, and serialization callbacks it works with are shared across formats and live in Bodu.Text.Serialization.

Key types

TomlConverter - the non-generic root (CanConvert) that TomlSerializerOptions.Converters holds.
TomlConverter<T> - the per-type base: implement Read and Write for T.
TomlConverterFactory - the base for converter families: CanConvert plus CreateConverter for a closed type.
TomlStringEnumConverter / TomlStringEnumConverter<TEnum> - enums as member-name strings, with an optional NamingPolicy and integer fallback.
TomlNumberEnumConverter<TEnum> - enums as their underlying integer.

Example

using Bodu.Text.Toml;
using Bodu.Text.Toml.Reader;
using Bodu.Text.Toml.Serialization;
using Bodu.Text.Toml.Writer;

public sealed class VersionConverter : TomlConverter<Version>
{
    public override Version Read(ref TomlDocumentReader reader, Type typeToConvert, TomlSerializerOptions options) =>
        Version.Parse(reader.GetString());

    public override void Write(Utf8TomlWriter writer, Version value, TomlSerializerOptions options) =>
        writer.WriteString(value.ToString());
}

var options = new TomlSerializerOptions();
options.Converters.Add(new VersionConverter());

Notes

Read binds through TomlDocumentReader. Unlike the Bencode and YAML siblings, the TOML read path hands converters the normalized tree-order cursor, not the source-order Utf8TomlReader, so headers and dotted keys are already resolved.
Resolution order. A [Converter] attribute on the member or type wins, then Converters in registration order, then the built-in catalog.
Internal converters. The Bodu.Text.Toml.Serialization.Converters sub-namespace is internal; extend through the public base types above.
See also: the Bodu.Text.Toml introduction and the writing converters guide.

Classes

TomlConverter: Serves as the non-generic base for every TOML converter. The hierarchy is closed to two extension points: TomlConverter<T>, which converts a single type, and TomlConverterFactory, which produces a converter for a family of types.

TomlConverterFactory: Produces a TomlConverter for a family of types that cannot be served by a single TomlConverter<T> - for example every Nullable<T>, every enumeration, or every collection.

TomlConverter<T>: Converts a value of type T to and from the TOML reader and writer. This is the base authors derive to customize how a specific type is serialized.

TomlNumberEnumConverter<TEnum>: Produces a converter that serializes the enumeration TEnum as a TOML integer carrying its underlying numeric value.

TomlStringEnumConverter: Produces a converter that serializes any enumeration as a TOML string holding its member name, applying an optional naming policy and honoring StringEnumMemberNameAttribute on individual members.

TomlStringEnumConverter<TEnum>: Produces a converter that serializes the enumeration TEnum as a TOML string holding its member name, applying an optional naming policy and honoring StringEnumMemberNameAttribute on individual members.