Tommy

Tommy

Tommy is a single-file TOML reader and writer for C#.

This library is meant for small, cross-platform projects that want support the most.NET versions possible.

To use it, simply include Tommy.cs into your project and you're done!

Alternatively, you can obtain the prebuilt package from NuGet!

Features

• Full implementation of TOML 1.0.0 spec.
• Parser implemented with TextReader for simplicity and vast input support (i.e. string inputs with StringReader, streams via StreamReader, etc).
• Parses TOML into a node-based structure that is similar to SimpleJSON.
• Basic support for parsing and saving comments.
• Supports.NET 3.5+, Mono,.NET Core!
• Uses C# 9 syntax for smaller file size.
• Small footprint (~41 KB compiled) compared to other similar C# libraries.
• Performs well compared to other similar C# libraries (view benchmarks)

Extensions

Tommy includes only a reader and a writer. There exist a few additional extensions that you can use

Officially maintained

• Tommy.Extensions -- General helper extensions for Tommy
• Tommy.Extensions.Configuration -- Microsoft.Extensions.Configuration integration for Tommy

3rd party

• Tommy.Serializer -- (De)serialization of objects for Tommy

How to use

Parsing TOML file

The TOML file:

title = "TOML Example"

[owner]

name = "Tom Preston-Werner"

dob = 1979-05-27T07:32:00-08:00

[database]

server = "192.168.1.1"

ports = [ 8001, 8001, 8002 ]

connection_max = 5000

enabled = true

// Reference the Tommy namespace at the start of the file

using Tommy;

// Parse into a node

using(StreamReader reader = File.OpenText("configuration.toml"))

{

// Parse the table

TomlTable table = TOML.Parse(reader);

Console.WriteLine(table["title"]); // Prints "TOML Example"

// You can check the type of the node via a property and access the exact type via As*-property

Console.WriteLine(table["owner"]["dob"].IsDateTime) // Prints "True"

// You can also do both with C# 7 syntax

if(table["owner"]["dob"] is TomlDate date)

Console.WriteLine(date.OnlyDate); // Some types contain additional properties related to formatting

// You can also iterate through all nodes inside an array or a table

foreach(TomlNode node in table["database"]["ports"])

Console.WriteLine(node);

}

Note that TOML.Parse is just a shorthand for creating a TOMLParser object and parsing it. In essence, TOML.Parse is just simply a wrapper for the following code block:

TomlTable table;

using(TOMLParser parser = new TOMLParser(reader))

table = parser.Parse();

In some cases, you might want to write the snippet manually, since the TOML parser can contain some additional parsing options.

Catching parse errors

Tommy is an optimistic parser: when it encounters a parsing error, it does not stop the parsing process right away.

Instead, Tommy logs all parsing errors and throws them as a single TomlParseException. In addition to parsing errors,

the exception object also contains the partially parsed TOML file that you can still attempt to use at your own risk.

Here's an example of handling parsing errors:

TomlTable table;

try

{

// Read the TOML file normally.

table = TOML.Parse(reader);

} catch(TomlParseException ex)

{

// Get access to the table that was parsed with best-effort.

table = ex.ParsedTable;

// Handle syntax error in whatever fashion you prefer

foreach(TomlSyntaxException syntaxEx in ex.SyntaxErrors)

Console.WriteLine($"Error on {syntaxEx.Column}:{syntaxEx.Line}: {syntaxEx.Message}");

}

If you do not wish to handle exceptions, you can instead use TommyExtensions.TryParse().

Generating or editing a TOML file

Tommy supports implicit casting from most built-in types to make file generation easy.

// Reference the Tommy namespace at the start of the file

using Tommy;

// Generate a TOML file programmatically

TomlTable toml = new TomlTable

{

["title"] = "TOML Example",

// You can also insert comments before a node with a special property

["value-with-comment"] = new TomlString

{

Value = "Some value",

Commen