YAML Integration
Convert between YAML and TOON formats using ToonNet.Extensions.Yaml.
Installation
dotnet add package ToonNet.Extensions.Yaml
ToonYamlConvert Class
Static utility class for YAML ↔ TOON conversion. Its methods work on strings.
YAML to TOON Conversion
using ToonNet.Extensions.Yaml;
string yaml = """
name: Alice
age: 30
address:
city: New York
zip: 10001
""";
string toonString = ToonYamlConvert.FromYaml(yaml);
// Output:
// name: Alice
// age: 30
// address:
// city: New York
// zip: 10001
FromYaml also takes ToonOptions (encoding options and the MaxDepth limit described below).
TOON to YAML Conversion
string toonString = """
name: Alice
age: 30
address:
city: New York
zip: 10001
""";
string yaml = ToonYamlConvert.ToYaml(toonString);
ToonYamlConverter Class
Bidirectional converter between YAML and ToonDocument / ToonValue:
using ToonNet.Core.Models;
using ToonNet.Extensions.Yaml;
// YAML → TOON
string yamlInput = File.ReadAllText("config.yaml");
ToonDocument toonDoc = ToonYamlConverter.FromYaml(yamlInput);
// TOON → YAML
string toonInput = """
database:
host: localhost
port: 5432
name: mydb
""";
ToonDocument doc = ToonDocument.Parse(toonInput);
string yaml = ToonYamlConverter.ToYaml(doc);
Limits
FromYaml checks the input before loading it, so untrusted YAML cannot exhaust the stack or memory:
- Nesting deeper than
ToonOptions.MaxDepth(default 100) throws aYamlException. Pass options to change it:ToonYamlConverter.FromYaml(yaml, new ToonOptions { MaxDepth = 50 }). - Aliases (
*anchor) are expanded into copies. Input whose aliases expand to more thanToonYamlConverter.MaxAliasExpansionNodes(100,000) nodes, or copy more thanToonYamlConverter.MaxAliasExpansionCharscharacters (1,000,000, or ten times the length of the YAML when that is more), throws aYamlException, so a small document cannot expand into a huge string. - 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 aYamlException.
Complete Examples
Configuration File Migration
// Read existing YAML config
string yaml = File.ReadAllText("appsettings.yaml");
// Convert to TOON
string toonString = ToonYamlConvert.FromYaml(yaml);
// Save as TOON config
File.WriteAllText("appsettings.toon", toonString);
Bidirectional Transformation
// YAML → TOON → YAML
string originalYaml = """
app:
name: MyApp
version: 1.0.0
features:
- authentication
- caching
""";
// To TOON
string toon = ToonYamlConvert.FromYaml(originalYaml);
// app:
// name: MyApp
// version: 1.0.0
// features[2]: authentication,caching
// Back to YAML
string convertedYaml = ToonYamlConvert.ToYaml(toon);
Docker Compose to TOON
string dockerCompose = File.ReadAllText("docker-compose.yaml");
ToonDocument toonDoc = ToonYamlConverter.FromYaml(dockerCompose);
// Now work with TOON API
var services = (ToonObject)toonDoc.AsObject()["services"]!;
foreach (var service in services.Properties)
{
Console.WriteLine($"Service: {service.Key}");
}
Key Methods Summary
| Method | Description |
|---|---|
ToonYamlConvert.FromYaml(string, ToonOptions?) | YAML string → TOON string |
ToonYamlConvert.ToYaml(string, ToonOptions?) | TOON string → YAML string |
ToonYamlConverter.FromYaml(string) | YAML string → ToonDocument |
ToonYamlConverter.FromYaml(string, ToonOptions?) | Same, with a custom MaxDepth |
ToonYamlConverter.ToYaml(ToonDocument) | ToonDocument → YAML string |
ToonYamlConverter.ToYaml(ToonValue) | ToonValue → YAML string |
Conversion Notes
- Only the first document of a multi-document YAML 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"". - Duplicate keys in a mapping throw a
YamlException, also keys that differ only in their tag (aand!!str a). - Merge keys (
<<: *base) are not expanded;<<stays an ordinary key. - Quoted and block scalars (and scalars tagged
!!str) are strings ("42"stays a string), unless an explicit core-schema tag says otherwise (!!int "42"is 42; a value that does not fit its tag, such as!!int 1.5or!!null foo, is aYamlException). Plain scalars are typed by the YAML 1.2 core schema:true/false(lowercase, capitalized or uppercase),null/~/empty, integers (42,+5,007is 7,0xFFis 255,0o17is 15) and floats (1.5,.5,1e3), exact when they fit in adecimal. Everything else is a string, including the YAML 1.1 booleansyes/no/on/offand.inf/.nan, which a TOON number cannot hold. ToonYamlConvert.ToYamlquotes strings that YAML would otherwise read as another type (alsoyes/no/on/off,2001-12-14,12:30:00,0b101,1_000,<<,=and text that starts with a byte order mark, for YAML 1.1 readers), so conversions round-trip, and acceptsToonOptionsfor parsing the TOON input. Strings with a carriage return or a YAML 1.1 line break (NEL, U+2028, U+2029) are double-quoted, so they keep those characters. Values nested deeper than 200 levels (the mostMaxDepthallows without extended limits) throw aYamlException, and the YAML ends with a line feed.- Anchors and aliases are expanded into copies; comments are not preserved.
Use Cases
- Configuration Migration: Convert YAML configs to TOON
- DevOps Tools: Work with YAML-based tools (Docker, Kubernetes, etc.)
- Format Conversion: Bi-directional YAML ↔ TOON transformation
- CI/CD Pipelines: Transform pipeline configs
- Interoperability: Bridge YAML and TOON ecosystems
See Also
- JSON Integration: Convert JSON ↔ TOON
- Converter Examples: Converters for types with their own text form