Toon.DotNet.CSV 1.7.2

Toon.DotNet.CSV

CSV integration for ToonDotNet — convert CSV files, strings, and streams to and from TOON format.

Features

Encoding — CSV → TOON

• Convert a CSV string directly to a TOON tabular array
• Convert a CSV stream — read from any readable Stream
• Open a CSV file and return its TOON representation in one call
• Save as .toon — read a CSV file and write the TOON result straight to a file
• Async file support — FromCsvAsync and SaveAsToonAsync for non-blocking I/O

Decoding — TOON → CSV

• Convert a TOON string (root array of objects) to a CSV string
• Write to a stream — output CSV bytes to any writable Stream
• Save as .csv — decode a TOON string and write the result straight to a file
• Convert a .toon file directly to a .csv file in one call
• Async file support — ToCsvAsync for non-blocking I/O

Extension methods

• string.CsvToToon() — convert a CSV string to TOON inline
• string.ToonToCsv() — convert a TOON string to CSV inline

Type coercion

• Integer, floating-point, and boolean values are parsed from CSV text to their native types
• Empty fields are treated as null
• All other values are preserved as strings
• Type fidelity is maintained through the full CSV → TOON → CSV round-trip

Other

• Built on CsvHelper for robust, RFC 4180-compliant CSV parsing and writing
• All encode/decode calls accept the standard EncodeOptions and DecodeOptions from Toon.DotNet
• Streams are left open after read and write calls
• 69 unit tests, 100% passing, 88% code coverage

Installation

dotnet add package Toon.DotNet.CSV

Compatibility

• .NET 10.0
• .NET 9.0
• .NET 8.0

How it works

CSV data is treated as tabular — the first row provides column headers and every subsequent row becomes a TOON data row. The result is a root TOON array.

Decoding reverses the mapping: the TOON root value must be an array of objects. Property names become CSV column headers and each object becomes a data row.

Quick start

Convert a CSV string to TOON

using ToonFormat.Csv;

string csv = """
    id,name,role
    1,Alice,admin
    2,Bob,user
    """;

string toon = ToonCsv.FromCsv(csv);
// [2]{id,name,role}:
//   1,Alice,admin
//   2,Bob,user

Convert a CSV file to TOON

string toon = ToonCsv.FromCsvFile("users.csv");

Convert a CSV file to TOON asynchronously

string toon = await ToonCsv.FromCsvAsync("users.csv");

Convert a TOON string to CSV

string toon = "[2]{id,name,role}:\n  1,Alice,admin\n  2,Bob,user";

string csv = ToonCsv.ToCsv(toon);
// id,name,role
// 1,Alice,admin
// 2,Bob,user

Save a CSV file as a TOON file

ToonCsv.SaveAsToon("users.csv", "users.toon");

// Async version
await ToonCsv.SaveAsToonAsync("users.csv", "users.toon");

Convert a TOON file directly to a CSV file

ToonCsv.ConvertToonToCsv("users.toon", "users.csv");

Read from and write to streams

// CSV stream → TOON string
using var csvStream = File.OpenRead("users.csv");
string toon = ToonCsv.FromCsv(csvStream);

// TOON string → CSV stream
using var outputStream = File.OpenWrite("users.csv");
ToonCsv.ToCsvStream(toon, outputStream);

Use extension methods

// CSV string → TOON
string toon = "id,name\n1,Alice\n2,Bob".CsvToToon();

// TOON → CSV string
string csv = "[2]{id,name}:\n  1,Alice\n  2,Bob".ToonToCsv();

API overview

ToonCsv static class

Encoding (CSV → TOON)

Decoding (TOON → CSV)

Extension methods

// string (CSV) → TOON
string toon = csvString.CsvToToon(options);

// string (TOON) → CSV
string csv = toonString.ToonToCsv(options);

Options

Options are passed directly from ToonDotNet and work identically here.

EncodeOptions

DecodeOptions

var opts = new EncodeOptions { Delimiter = '|', Indent = 4 };
string toon = ToonCsv.FromCsv(csv, opts);

Type coercion

When reading CSV, field values are automatically coerced to their native types before encoding to TOON. This preserves type information that is otherwise lost in plain-text CSV.

When converting TOON back to CSV, numbers and booleans are written as their raw text representations and empty fields are written for null values.

Dependencies

• Toon.DotNet — core TOON encoding and decoding
• CsvHelper — RFC 4180-compliant CSV parsing and writing

License

MIT