EonaCat.Toon 0.0.1

EonaCat.Toon

Token-Oriented Object Notation (TOON) serializer for .NET.

EonaCat.Toon is a lightweight serialization library that converts .NET objects into a compact, human-readable text format designed to reduce structural overhead while preserving hierarchy and type information.

TOON is especially useful for:

• AI and LLM prompt compression
• Memory stores
• Configuration files
• Logging and telemetry
• Human-editable structured documents
• Lightweight data exchange

Features

Serialization

• Primitive values
• POCOs
• Records
• Anonymous types
• Dictionaries
• Nested objects
• Arrays and collections
• DataTable support
• JsonNode compatibility

Deserialization

• JsonNode output
• Strongly typed models
• Generic decoding
• DataTable reconstruction

Compression Features

• Tabular array encoding
• Optional length markers
• Key folding
• Compact indentation
• Multiple delimiters

Validation Features

• Strict decoding
• Length mismatch validation
• Warning collection
• Safe path expansion

Installation

dotnet add package EonaCat.Toon

Install-Package EonaCat.Toon

Quick Start

Encode

using EonaCat.Toon;

var user = new
{
    Name = "Alice",
    Age = 30
};

string toon = Toon.Encode(user);

Output:

Name: Alice
Age: 30

Decode

JsonNode? node = Toon.Decode(toonText);

Strongly Typed Decode

User? user = Toon.Decode<User>(toonText);

Public API

Encode

string output = Toon.Encode(object value);

string output = Toon.Encode(
    object value,
    EncodingOptions options);

Decode

JsonNode? node = Toon.Decode(string input);

JsonNode? node = Toon.Decode(
    string input,
    DecodingOptions options);

Generic Decode

T? value = Toon.Decode<T>(input);

T? value = Toon.Decode<T>(
    input,
    options);

TOON Syntax

Simple Values

Name: Alice
Age: 42
Active: true
Price: 12.50

Nested Objects

User:
 Name: Alice
 Address:
  City: Utrecht
  Country: Netherlands

Arrays

Tags[3]:
 AI
 DotNet
 Serialization

Length Marker Arrays

Tags[#3]:
 AI
 DotNet
 Serialization

Tabular Arrays

When all items share the same shape, TOON can store column names once.

Input:

var users = new[]
{
    new { Id = 1, Name = "Alice" },
    new { Id = 2, Name = "Bob" }
};

Output:

Users[2]{Id,Name}:
 1,Alice
 2,Bob

Benefits:

• Smaller payloads
• Reduced token count
• Faster LLM ingestion
• Easier scanning

Encoding Options

var options = new EncodingOptions
{
    Indent = 1,
    Delimiter = Delimiter.Comma,
    UseLengthMarker = true,
    KeyFolding = KeyFoldingMode.Safe,
    FlattenDepth = 5
};

Indent

Controls spaces per nesting level.

Default:

1

Delimiter

Supported values:

Delimiter.Comma
Delimiter.Tab
Delimiter.Pipe

Examples:

1,Alice

1	Alice

1|Alice

UseLengthMarker

Disabled by default.

When enabled:

Users[#10]:

instead of:

Users[10]:

KeyFolding

Supported values:

KeyFoldingMode.Off
KeyFoldingMode.Safe

Example

Input:

{
  "data": {
    "metadata": {
      "version": 1
    }
  }
}

Output:

data.metadata.version: 1

FlattenDepth

Limits maximum folding depth.

Default:

int.MaxValue

SerializerOptions

Pass custom System.Text.Json options.

new JsonSerializerOptions
{
    PropertyNamingPolicy =
        JsonNamingPolicy.CamelCase
}

NewLine

Default:

"\n"

Custom:

"\r\n"

Decoding Options

var options = new DecodingOptions
{
    Strict = true,
    ExpandPaths = PathExpansionMode.Safe
};

Strict

Default:

true

Throws exceptions when malformed structures are encountered.

ExpandPaths

Supported values:

PathExpansionMode.Off
PathExpansionMode.Safe

Expands:

data.metadata.version: 1

into:

{
  "data": {
    "metadata": {
      "version": 1
    }
  }
}

LengthMismatchBehavior

LengthMismatchBehavior.Silent
LengthMismatchBehavior.Warn
LengthMismatchBehavior.Error

WarningSink

Collect parser warnings.

var warnings =
    new List<Warning>();

options.WarningSink = warnings;

DataTable Support

Serialize

var table = new DataTable("Users");

table.Columns.Add("Id", typeof(int));
table.Columns.Add("Email", typeof(string));

table.Rows.Add(1, "alice@example.com");
table.Rows.Add(2, "bob@example.com");

string toon = Toon.Encode(table);

Deserialize

DataTable restored =
    Toon.Decode<DataTable>(toon)!;

Supported:

• Columns
• Rows
• Types
• Schema metadata

AI & LLM Usage

TOON was designed to minimize repetitive structural tokens.

Traditional JSON:

{
  "users": [
    {
      "id": 1,
      "name": "Alice"
    },
    {
      "id": 2,
      "name": "Bob"
    }
  ]
}

TOON:

users[2]{id,name}:
 1,Alice
 2,Bob

Advantages:

• Lower token counts
• Lower prompt costs
• More context per request
• Easier visual inspection

Best Practices

For AI Workloads

new EncodingOptions
{
    KeyFolding = KeyFoldingMode.Safe,
    UseLengthMarker = true,
    Indent = 1
};

For Maximum Readability

new EncodingOptions
{
    Indent = 2,
    KeyFolding = KeyFoldingMode.Off
};

For Logging

new EncodingOptions
{
    Indent = 1,
    Delimiter = Delimiter.Comma
};

Error Handling

try
{
    var model =
        Toon.Decode<MyType>(text);
}
catch (Exception ex)
{
    Console.WriteLine(ex.Message);
}

For tolerant parsing:

new DecodingOptions
{
    Strict = false,
    LengthMismatchBehavior =
        LengthMismatchBehavior.Warn
};

Framework Support

According to the project targets:

• .NET Standard 2.0
• .NET 6
• .NET 7
• .NET 8
• .NET 9
• .NET 10

Compatible with:

• .NET Framework 4.6.1+
• Mono
• Xamarin
• Unity

Architecture

Object
   │
   ▼
ValueEncoder
   │
   ▼
TOON Text
   │
   ▼
Scanner
   │
   ▼
ValueDecoder
   │
   ▼
JsonNode / Model

Core components:

• ValueEncoder
• PrimitiveEncoder
• Scanner
• PrimitiveParser
• ValueDecoder
• PathExpander
• DataTableAdapter