ToonNet.Extensions.Yaml 4.0.0

ToonNet.Extensions.Yaml

YAML ↔ TOON format conversion extension

📦 What is ToonNet.Extensions.Yaml?

ToonNet.Extensions.Yaml provides seamless bidirectional conversion between YAML and TOON formats:

• ✅ YAML → TOON - Convert YAML strings/documents to TOON format
• ✅ TOON → YAML - Convert TOON strings/documents to YAML format
• ✅ YamlDotNet integration - Industry-standard YAML parser
• ✅ Preserves structure - Round-trip conversions keep mappings, sequences and scalar values
• ✅ Common YAML features - Mappings, sequences, scalars, flow notation, anchors and aliases (expanded into copies)

Perfect for:

• ⚙️ Configuration Files - Convert YAML configs to TOON format
• 🐳 Docker/Kubernetes - Work with container configurations
• 🔄 CI/CD - Transform GitHub Actions, GitLab CI, etc.
• 📋 OpenAPI/Swagger - Convert API specifications
• 🔗 Cross-format - YAML → TOON → JSON workflows

🚀 Quick Start

Installation

# Core package (required)
dotnet add package ToonNet.Core

# YAML extension
dotnet add package ToonNet.Extensions.Yaml

Basic Usage - Document Conversion

using ToonNet.Extensions.Yaml;

// YAML → TOON document
var yaml = """
name: Alice
age: 30
tags:
  - dev
  - admin
settings:
  theme: dark
  notifications: true
""";

var toonDoc = ToonYamlConverter.FromYaml(yaml);

// Access data
var root = (ToonObject)toonDoc.Root;
var name = ((ToonString)root["name"]).Value; // "Alice"
var age = ((ToonNumber)root["age"]).Value;   // 30

// TOON → YAML document
var yamlOutput = ToonYamlConverter.ToYaml(toonDoc);

String Format Conversion (High-level API)

using ToonNet.Extensions.Yaml;

// YAML → TOON string conversion
string yamlString = """
name: Alice
age: 30
hobbies:
  - reading
  - coding
""";

string toonString = ToonYamlConvert.FromYaml(yamlString);

// Output (TOON format):
// name: Alice
// age: 30
// hobbies[2]: reading,coding

// TOON → YAML string conversion
string yamlBack = ToonYamlConvert.ToYaml(toonString);

📖 API Reference

String Format Conversion

// YAML string → TOON string
string toon = ToonYamlConvert.FromYaml(yamlString);
string toon = ToonYamlConvert.FromYaml(yamlString, options);  // ToonOptions

// TOON string → YAML string
string yaml = ToonYamlConvert.ToYaml(toonString);
string yaml = ToonYamlConvert.ToYaml(toonString, options);  // ToonOptions for parsing the TOON input

Document Conversion (Low-level)

using ToonNet.Extensions.Yaml;

// YAML string → ToonDocument
ToonDocument doc = ToonYamlConverter.FromYaml(yamlString);
ToonDocument doc = ToonYamlConverter.FromYaml(yamlString, new ToonOptions { MaxDepth = 50 });

// ToonDocument → YAML string
string yaml = ToonYamlConverter.ToYaml(document);

// ToonValue → YAML string
string yaml = ToonYamlConverter.ToYaml(toonValue);

Architecture Note: ToonNet uses a layered approach for YAML interop:

• ToonYamlConverter - Low-level conversion between YAML nodes ↔ ToonDocument/ToonValue. Used internally as the core conversion engine.
• ToonYamlConvert - High-level, developer-friendly API (similar to ToonConvert for JSON). Provides simple string-based conversions and internally uses ToonYamlConverter.

This separation of concerns ensures clean architecture: ToonYamlConverter handles the conversion logic, while ToonYamlConvert provides an ergonomic interface familiar to .NET developers.

Limits

YAML input is checked before it is loaded:

• Nesting deeper than ToonOptions.MaxDepth (default 100) throws a YamlException.
• Aliases (*anchor) are expanded into copies; input whose aliases expand to more than ToonYamlConverter.MaxAliasExpansionNodes (100,000) nodes, or copy more than ToonYamlConverter.MaxAliasExpansionChars characters (1,000,000, or ten times the length of the YAML when that is more), throws a YamlException.
• Duplicate keys throw a YamlException, also keys that differ only in their tag (a and !!str a).
• The nesting limit counts the expanded aliases too, and an alias inside the node its anchor marks (a recursive structure such as &a [*a]) throws a YamlException.

Type Support

🎯 Real-World Examples

Example 1: Configuration File Conversion

using ToonNet.Extensions.Yaml;

// Load YAML configuration
string yamlConfig = """
database:
  host: localhost
  port: 5432
  credentials:
    username: admin
    password: secret
logging:
  level: info
  outputs:
    - console
    - file
""";

// Convert to TOON format (more compact)
string toonConfig = ToonYamlConvert.FromYaml(yamlConfig);

// Output (TOON format):
// database:
//   host: localhost
//   port: 5432
//   credentials:
//     username: admin
//     password: secret
// logging:
//   level: info
//   outputs[2]: console,file

// Convert back to YAML if needed
string yamlBack = ToonYamlConvert.ToYaml(toonConfig);

Example 2: Kubernetes Manifest Conversion

using ToonNet.Extensions.Yaml;

// Load Kubernetes YAML
var k8sYaml = """
apiVersion: v1
kind: Service
metadata:
  name: my-service
  labels:
    app: myapp
spec:
  type: LoadBalancer
  ports:
    - port: 80
      targetPort: 8080
""";

// Convert to TOON (more readable for analysis)
string toonManifest = ToonYamlConvert.FromYaml(k8sYaml);

// Analyze with TOON, then convert back
string modifiedYaml = ToonYamlConvert.ToYaml(toonManifest);

Example 3: Cross-Format Conversion (YAML → JSON)

using ToonNet.Extensions.Json;
using ToonNet.Extensions.Yaml;

// YAML → TOON → JSON
var yaml = """
database:
  host: localhost
  port: 5432
""";

string toon = ToonYamlConvert.FromYaml(yaml);
string json = ToonConvert.ToJson(toon);

// JSON → TOON → YAML (reverse)
var jsonStr = """{"name":"Alice","tags":["dev","admin"]}""";
string toonFromJson = ToonConvert.FromJson(jsonStr);
string yamlOutput = ToonYamlConvert.ToYaml(toonFromJson);

Example 4: GitHub Actions Workflow Analysis

using ToonNet.Extensions.Yaml;
using ToonNet.Core.Serialization;

// Load GitHub Actions workflow
var workflowYaml = """
name: CI
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build
        run: dotnet build
""";

// Convert to TOON format
string toonWorkflow = ToonYamlConvert.FromYaml(workflowYaml);

// Save as TOON for easier reading/editing
File.WriteAllText("workflow.toon", toonWorkflow);

// Convert back when needed
string yamlOutput = ToonYamlConvert.ToYaml(toonWorkflow);

// Or inspect it as a document
var doc = ToonYamlConverter.FromYaml(workflowYaml);
var jobs = (ToonObject)doc.AsObject()["jobs"]!;
var buildJob = (ToonObject)jobs["build"]!;
var steps = (ToonArray)buildJob["steps"]!;

Console.WriteLine($"Workflow has {steps.Items.Count} steps");

Keys that are not plain identifiers are quoted in TOON ("runs-on": ubuntu-latest).

✨ YAML Features Supported

Quoted and block scalars ("42", 'true', |, >) and scalars tagged !!str are strings, unless an explicit core-schema tag says otherwise (!!int "42" is 42; a value that does not fit its tag is a YamlException). Plain scalars are typed by the YAML 1.2 core schema: true/false (lowercase, capitalized or uppercase) become booleans, null, ~ and empty values become null, and integers and floats become numbers (exact when they fit in a decimal). Anything else stays a string, including the YAML 1.1 booleans yes/no/on/off and .inf/.nan, which a TOON number cannot hold. When converting back, strings that would otherwise read as another type are quoted ("42", "true", "007", "", and "yes", "2001-12-14", "<<", "=" and text that starts with a byte order mark for YAML 1.1 readers), so a TOON → YAML → TOON round trip keeps them strings.

Booleans

enabled: true        # a boolean
disabled: FALSE      # a boolean
legacy_yes: yes      # the string "yes" (a boolean only in YAML 1.1)
switch_on: on        # the string "on"

Number Formats

integer: 42
float: 3.14
short: .5            # 0.5
scientific: 1.5e-10
hex: 0xFF            # 255
octal: 0o77          # 63
zip: 007             # 7; quote it ("007") to keep the string
infinity: .inf       # the string ".inf"
quoted: "42"         # a string

Complex Structures

# Nested objects
user:
  profile:
    settings:
      theme: dark

# Mixed arrays
items:
  - name: Item 1
    price: 9.99
  - name: Item 2
    price: 19.99

# Inline notation
tags: [dev, admin, user]
coords: {x: 10, y: 20}

🔄 Round-Trip Behavior

YAML → TOON → YAML conversions preserve structure:

var originalYaml = """
user:
  name: Bob
  roles:
    - admin
    - editor
""";

var toonDoc = ToonYamlConverter.FromYaml(originalYaml);
var roundtripYaml = ToonYamlConverter.ToYaml(toonDoc);

// Structure preserved (formatting may differ)

Note: Comments are not preserved, aliases are expanded into copies, and only the first document of a multi-document stream is converted. Mapping keys must be scalars (a sequence or mapping used as a key throws a YamlException); an empty key is kept as the TOON key "". Merge keys (<<: *base) are not expanded; << stays an ordinary key.

🔒 Thread-Safety

• ToonSerializer and YAML conversion methods are safe to call concurrently across threads.
• Shared metadata/name caches use ConcurrentDictionary for concurrent access.
• Cache entries are created on demand and retained for the process lifetime (no eviction).
• Do not mutate a single ToonSerializerOptions instance concurrently across threads.

🔗 Related Packages

Core:

• ToonNet.Core - Core serialization (required)

Other Extensions:

• ToonNet.Extensions.Json - JSON ↔ TOON conversion

Web Integration:

• ToonNet.AspNetCore - TOON configuration provider and DI integration
• ToonNet.AspNetCore.Mvc - MVC formatters

Development:

• ToonNet.Demo - Sample applications
• ToonNet.Tests - YAML conversion test suite

📚 Documentation

• Main Documentation - Complete ToonNet guide
• API Guide - Detailed API reference
• Samples - Real-world examples

🧪 Testing

# Run YAML conversion tests
cd tests/ToonNet.Tests
dotnet test --filter "FullyQualifiedName~ToonYamlConverter"

📋 Requirements

• .NET 8.0 or later
• ToonNet.Core
• YamlDotNet 18.1.0+ (installed automatically)

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Part of the ToonNet serialization library family.