- 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
VSoft.YAML provides selective backward compatibility for common YAML 1.1 features:
- Boolean values: Supports
yes/no/on/offfor easier migration - Modern approach: Does not support ambiguous single-letter
y/nbooleans - Numeric formats: Uses YAML 1.2 standards (no
0XXoctal 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
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
- 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
- Multiple Documents - Full support for multi-document YAML files with
LoadAllFromString/File()andWriteAllToString/File() - YAML Directives - Complete support for
%YAMLversion and%TAGcustom 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()andQuerySingle()methods - Complex Keys - Flow-style complex key support
- Comment Preservation - Proper comment handling during parsing
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;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;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;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;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;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;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;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;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"- VSoft.YAML.pas - Main entry point with
TYAMLstatic 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
- 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
- Reading a missing key no longer adds it.
S[],I[],L[],U[],F[],C[],D[],DUtc[]andB[]return'',0orFalsefor a missing key and leave the mapping unchanged, as JsonDataObjects does.F[],C[],D[]andDUtc[]used to raise on a missing key (and still add it).A[]andO[]still create the key, as documented, so builder code such asdoc.O['a'].S['b'] := 'x'keeps working. - The getters convert between scalar types, as their comments say. On mappings and sequences:
I[],L[]andU[]accept floats (truncated), booleans (0 or 1) and numeric strings.F[]andC[]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 isFalse.D[]andDUtc[]accept ISO 8601 strings.- A null reads as
'',0orFalse. - Text that is not a number still raises, now
EConvertError(it was a plainException).
C[]reads Currency exactly. It went through Double, so922337203685477.5807came back as-922337203685477.5808.
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'', asAddValue('')on a sequence andS[key] := ''already did. To write a null, callAddOrSetNull(key), orAddNullon 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.23e4stays1.23e4(it was written as12300),1.50stays1.50(was1.5), and-0.0stays-0.0. - Currency keeps all four decimals.
922337203685477.5807was written as922337203685478. - UInt64 values above
High(Int64)are written. They raisedEConvertError. - Hex, octal and binary integers convert exactly, at any size. They are written as decimal, so
0xFFFFFFFFFFFFFFFFcomes out as18446744073709551615; it raised before.AsIntegerreturns the right value for hex of 32 bits or more (0xFFFFFFFFwas -1, and0x100000000raised), and raisesEConvertErrorfor any value pastHigh(Int64)where octal and binary silently wrapped around. - A whole-number float is written to YAML with
.0.AddOrSetValue(key, 2.0)writes2.0, because2would be read back as an integer. JSON output is unchanged (2). !!intaccepts integers of any size, and the 0o, 0x and 0b forms.!!int 3000000000and!!int 0o17were 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,FALSEandNonow read as null and booleans (they read as strings), and other mixes of case such asnO,YeS,OfFand.nAnnow read as strings (they read as booleans and floats)..5,+.5,1.and1.e5are floats, and0X1F,0O17and0B101are 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_000and2026-10-22unquoted, 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.AddNumberandIYAMLEmitOptions.EscapeNonASCIIwere added. Only code that implements these interfaces itself needs updating.
Install VSoft.YAML in the DPM IDE plugin, or
dpm install VSoft.YAML .\yourproject.dproj
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.