Skip to content

Repository files navigation

VSoft.YAML

A YAML 1.2 and JSON parser and emitter library for Delphi XE2+.

Features

✅ YAML 1.2

  • YAML 1.2 Specification Compliance - Attempting full support for YAML 1.2
  • Complete Value Type System - Handles all 9 YAML value types:
    • Scalars: null, boolean, integer, float, string, timestampx
    • Collections: sequence (arrays), mapping (objects), set (unique values array)
    • References: alias (anchor references)
  • Number Formats - Support for decimal, hexadecimal (0x) and octal (0o) number literals
  • ISO 8601 Timestamps - Full date/time parsing with timezone support.
  • Anchor & Alias System - Complete YAML reference support for data reuse

🔄 YAML 1.1 Compatibility

VSoft.YAML provides selective backward compatibility for common YAML 1.1 features:

  • Boolean values: Supports yes/no/on/off for easier migration
  • Modern approach: Does not support ambiguous single-letter y/n booleans
  • Numeric formats: Uses YAML 1.2 standards (no 0XX octal prefix), but binary (0b) literals and underscores are allowed
  • Merge Keys - Support for YAML merge key (<<) operations

For full YAML Feature details see - YAML Features

JSON Support

VSoft.YAML can parse and write JSON (since YAML 1.2 is a superset of JSON):

  • JSON Parsing - Full JSON input support with strict validation
  • JSON Output - Export to JSON format with compact or pretty-print formatting
  • Bidirectional Conversion - Convert between YAML and JSON formats
  • Exact Numbers - Numbers are written digit for digit, whatever their size: UInt64, Currency, and decimals added from their text with AddOrSetNumber
  • ASCII-only Output - Optionally escape every non-ASCII character as \uXXXX

Parsing & Writing

  • Multiple Input Sources - Load from string, file, or stream
  • Flexible Output Options:
    • Block style (human-readable, indented)
    • Flow style (compact, JSON-like)
    • Mixed style formatting
    • JSON Output - Export YAML documents to JSON format with pretty-print support
  • Encoding - Automatic encoding detection - default is UTF-8
  • Error Handling - Detailed parse error reporting with line/column information

Advanced Features

  • Multiple Documents - Full support for multi-document YAML files with LoadAllFromString/File() and WriteAllToString/File()
  • YAML Directives - Complete support for %YAML version and %TAG custom handle directives
  • Comprehensive Tag System - Full implementation of all YAML 1.2 tag types (Standard, Local, Custom, Verbatim, Global)
  • JSONPath Queries - JSONPath-style querying with Query() and QuerySingle() methods
  • Complex Keys - Flow-style complex key support
  • Comment Preservation - Proper comment handling during parsing

Quick Start

Loading YAML

uses VSoft.YAML;

var
  doc: IYAMLDocument;
  yaml: string;
begin
  yaml := 'name: John Doe' + sLineBreak +
          'age: 30' + sLineBreak +
          'city: New York';
          
  doc := TYAML.LoadFromString(yaml);
  
  WriteLn('Name: ', doc.Root.Values['name'].AsString);
  WriteLn('Age: ', doc.Root.Values['age'].AsInteger);
end;

Creating YAML Documents

var
  doc: IYAMLDocument;
  person: IYAMLMapping;
begin
  doc := TYAML.CreateMapping;
  person := doc.Root.AsMapping;
  
  person.AddOrSetValue('name', 'Jane Smith');
  person.AddOrSetValue('age', 25);
  
  WriteLn(TYAML.WriteToString(doc));
end;

Working with Collections

var
  doc: IYAMLDocument;
  fruits: IYAMLSequence;
begin
  yaml := 'fruits:' + sLineBreak +
          '  - apple' + sLineBreak +
          '  - banana' + sLineBreak +
          '  - orange';
          
  doc := TYAML.LoadFromString(yaml);
  fruits := doc.Root.Values['fruits'].AsSequence;
  
  for i := 0 to fruits.Count - 1 do
    WriteLn('Fruit: ', fruits.Items[i].AsString);
end;

Multiple Documents

var
  documents: TArray<IYAMLDocument>;
  doc1, doc2: IYAMLDocument;
  yamlContent: string;
begin
  // Create multiple documents
  doc1 := TYAML.CreateMapping;
  doc1.AsMapping.AddOrSetValue('name', 'Config 1');
  doc1.AsMapping.AddOrSetValue('version', 1);
  
  doc2 := TYAML.CreateMapping;
  doc2.AsMapping.AddOrSetValue('name', 'Config 2');
  doc2.AsMapping.AddOrSetValue('version', 2);
  
  // Write multiple documents
  SetLength(documents, 2);
  documents[0] := doc1;
  documents[1] := doc2;
  
  yamlContent := TYAML.WriteAllToString(documents);
  WriteLn('Multi-document YAML:');
  WriteLn(yamlContent);
  
  // Load multiple documents
  documents := TYAML.LoadAllFromString(yamlContent);
  WriteLn('Loaded ', Length(documents), ' documents');
end;

Working with Tags

var
  doc: IYAMLDocument;
  root: IYAMLMapping;
begin
  doc := TYAML.CreateMapping;
  root := doc.AsMapping;
  
  // Add values with explicit tags
  root.AddOrSetValue('port', '8080', '!!int');     // Force integer type
  root.AddOrSetValue('name', 'server', '!!str');   // Force string type
  root.AddOrSetValue('config', configData, '!app!config'); // Custom tag
  
  WriteLn(TYAML.WriteToString(doc));
end;

Writing to JSON

var
  doc: IYAMLDocument;
  person: IYAMLMapping;
  jsonOutput: string;
begin
  // Create a YAML document
  doc := TYAML.CreateMapping;
  person := doc.Root.AsMapping;
  
  person.AddOrSetValue('name', 'John Doe');
  person.AddOrSetValue('age', 30);
  person.AddOrSetValue('city', 'New York');
  
  // Export to compact JSON
  doc.Options.PrettyPrint := false;
  jsonOutput := TYAML.WriteToJSONString(doc);
  WriteLn('Compact JSON: ', jsonOutput);
  // Output: {"name":"John Doe","age":30,"city":"New York"}
  
  // Export to pretty-printed JSON
  doc.Options.PrettyPrint := true;
  doc.Options.IndentSize := 2;
  jsonOutput := TYAML.WriteToJSONString(doc);
  WriteLn('Pretty JSON:');
  WriteLn(jsonOutput);
  // Output:
  // {
  //   "name": "John Doe",
  //   "age": 30,
  //   "city": "New York"
  // }
  
  // Write JSON to file
  TYAML.WriteToJSONFile(doc, 'output.json');
end;

Converting YAML to JSON

var
  yamlDoc: IYAMLDocument;
  yamlContent: string;
  jsonOutput: string;
begin
  // Load YAML content
  yamlContent := 'employees:' + sLineBreak +
                 '  - name: Alice' + sLineBreak +
                 '    role: Developer' + sLineBreak +
                 '  - name: Bob' + sLineBreak +
                 '    role: Designer';
                 
  yamlDoc := TYAML.LoadFromString(yamlContent);
  
  // Convert to JSON with pretty printing
  yamlDoc.Options.PrettyPrint := true;
  jsonOutput := TYAML.WriteToJSONString(yamlDoc);
  
  WriteLn('YAML to JSON conversion:');
  WriteLn(jsonOutput);
  // Output:
  // {
  //   "employees": [
  //     {
  //       "name": "Alice",
  //       "role": "Developer"
  //     },
  //     {
  //       "name": "Bob",
  //       "role": "Designer"
  //     }
  //   ]
  // }
end;

Exact Numbers

Numbers are written exactly as they were read or added, in JSON and YAML, rather than going through Int64 or Double. For values that no Delphi type holds, such as a SQL DECIMAL(38,10), add the number from its text with AddOrSetNumber (on a sequence, AddNumber). The text must be a JSON number (-, digits, an optional fraction and an optional exponent), or EConvertError is raised. Like a parsed number, it is an integer unless it has a fraction or an exponent.

var
  doc: IYAMLDocument;
  row: IYAMLMapping;
  price: Currency;
begin
  doc := TYAML.CreateMapping;
  row := doc.AsMapping;
  price := 19.99;

  row.AddOrSetValue('id', UInt64(High(UInt64)));
  row.AddOrSetCurrencyValue('price', price);
  row.AddOrSetNumber('total', '1234567890123456789012345678.9012345678');
  row.AddOrSetValue('note', '');   // an empty string
  row.AddOrSetNull('discount');    // a null

  doc.Options.PrettyPrint := false;
  WriteLn(TYAML.WriteToJSONString(doc));
  // Output: {"id":18446744073709551615,"price":19.99,"total":1234567890123456789012345678.9012345678,"note":"","discount":null}
end;

ASCII-only JSON

Set EscapeNonASCII to write every character past ~ (#126) as a \uXXXX escape, and a character outside the Basic Multilingual Plane (an emoji, say) as its two surrogate escapes, as RFC 8259 specifies. The output is then printable ASCII. It affects JSON output only.

  doc.Options.EscapeNonASCII := true;
  // 'café' is written as "caf\u00E9", and U+1F600 (an emoji) as "\uD83D\uDE00"

Core Components

  • VSoft.YAML.pas - Main entry point with TYAML static factory methods for all operations
  • VSoft.YAML.Writer.pas - YAML output writer with multiple formatting options
  • VSoft.YAML.Writer.JSON.pas - JSON output writer with pretty-print support

Compatibility

  • Delphi XE2+ - compatible with Delphi XE2 or later
  • Win32/Win64 - may work on other platforms (does not use WinAPI.*), but not tested .
  • No External Dependencies - Pure Delphi implementation

Behaviour changes in 2.3.0

  • Reading a missing key no longer adds it. S[], I[], L[], U[], F[], C[], D[], DUtc[] and B[] return '', 0 or False for a missing key and leave the mapping unchanged, as JsonDataObjects does. F[], C[], D[] and DUtc[] used to raise on a missing key (and still add it). A[] and O[] still create the key, as documented, so builder code such as doc.O['a'].S['b'] := 'x' keeps working.
  • The getters convert between scalar types, as their comments say. On mappings and sequences:
    • I[], L[] and U[] accept floats (truncated), booleans (0 or 1) and numeric strings.
    • F[] and C[] accept integers, booleans and numeric strings.
    • B[] reads a number as true when it isn't zero, and a string as its YAML boolean value (true, True, yes, ON...); any other string is False.
    • D[] and DUtc[] accept ISO 8601 strings.
    • A null reads as '', 0 or False.
    • Text that is not a number still raises, now EConvertError (it was a plain Exception).
  • C[] reads Currency exactly. It went through Double, so 922337203685477.5807 came back as -922337203685477.5808.

Behaviour changes in 2.1.0

These change what existing code produces, so check them when upgrading from 2.0 or earlier.

  • AddOrSetValue(key, '') stores an empty string, not null. JSON gets "" and YAML '', as AddValue('') on a sequence and S[key] := '' already did. To write a null, call AddOrSetNull(key), or AddNull on a sequence.
  • Numbers are written as they were read or added. When a number's text is already a valid JSON number, both writers emit it unchanged instead of converting it through Int64 or Double. A parsed 1.23e4 stays 1.23e4 (it was written as 12300), 1.50 stays 1.50 (was 1.5), and -0.0 stays -0.0.
  • Currency keeps all four decimals. 922337203685477.5807 was written as 922337203685478.
  • UInt64 values above High(Int64) are written. They raised EConvertError.
  • Hex, octal and binary integers convert exactly, at any size. They are written as decimal, so 0xFFFFFFFFFFFFFFFF comes out as 18446744073709551615; it raised before. AsInteger returns the right value for hex of 32 bits or more (0xFFFFFFFF was -1, and 0x100000000 raised), and raises EConvertError for any value past High(Int64) where octal and binary silently wrapped around.
  • A whole-number float is written to YAML with .0. AddOrSetValue(key, 2.0) writes 2.0, because 2 would be read back as an integer. JSON output is unchanged (2).
  • !!int accepts integers of any size, and the 0o, 0x and 0b forms. !!int 3000000000 and !!int 0o17 were rejected.
  • Merge keys (<<) copy values exactly. Merging a mapping that holds an integer past Int64 raised a parse error, and merged floats lost digits.
  • Plain values follow the YAML 1.2 core schema's spellings. Each word is read in its lower-case, capitalised and upper-case spellings only. NULL, TRUE, FALSE and No now read as null and booleans (they read as strings), and other mixes of case such as nO, YeS, OfF and .nAn now read as strings (they read as booleans and floats). .5, +.5, 1. and 1.e5 are floats, and 0X1F, 0O17 and 0B101 are strings, because YAML only has the lower-case prefixes.
  • Strings are quoted whenever they would read back as something else. The writer left strings such as True, YES, .inf, 0o17, 1_000 and 2026-10-22 unquoted, so they came back as booleans, numbers or timestamps. It now quotes exactly the text the parser would not read as a string, so every string round trips. Delphi-only number forms such as $FF, which YAML reads as strings, are no longer quoted.
  • New interface members. IYAMLMapping.AddOrSetNumber, IYAMLSequence.AddNumber and IYAMLEmitOptions.EscapeNonASCII were added. Only code that implements these interfaces itself needs updating.

Installing

Install VSoft.YAML in the DPM IDE plugin, or

dpm install VSoft.YAML .\yourproject.dproj

Manually

Clone the repository, add the Source folder to your project search path, or your IDE search path. Alternatively you can open and build the VSoft.YMLR.dproj in the Packages folder use the dcu files.

Releases

Contributors

Languages