ToonNet.Extensions.Yaml 1.4.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 maintain data integrity
• ✅ Full YAML support - Objects, arrays, scalars, anchors, aliases

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);

Document Conversion (Low-level)

using ToonNet.Extensions.Yaml;

// YAML string → ToonDocument
ToonDocument doc = ToonYamlConverter.FromYaml(yamlString);

// 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.

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);

var buildJob = (ToonObject)jobs["build"]; var steps = (ToonArray)buildJob["steps"];

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

---

## ✨ YAML Features Supported

### Boolean Variants
```yaml
# All supported
enabled: true
disabled: false
legacy_yes: yes
legacy_no: no
switch_on: on
switch_off: off

Number Formats

integer: 42
float: 3.14
scientific: 1.5e-10
hex: 0xFF
octal: 0o77

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 and anchors/aliases are not preserved (YAML parser limitation).

🔒 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 - ASP.NET Core middleware
• 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"

# Run specific test categories
dotnet test --filter "Category=YamlConversion"

📋 Requirements

• .NET 8.0 or later
• ToonNet.Core
• YamlDotNet 16.3.0+

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Part of the ToonNet serialization library family.