Loading as Dart built-in types topic

The package allows you load a YAML string as a built-in Dart type without worrying about any wrapper classes that act as a bridge. Built-in types also supported by YAML include:

• int, double, bool, null, String
• List
• Map

Loading a scalar as a built-in Dart type

You can load a single Dart object from a YAML source string/bytes by calling loadDartObject. It allows you provide a type if are privy to the node present. The function returns a nullable type of the object your provide since the document may be empty.

// Type inferred automatically. A YAML spec philosophy!
print(loadDartObject<int>(source: '24'));

print(loadDartObject<bool>(source: 'true'));

print(loadDartObject<double>(source: '24.0'));

print(loadDartObject<String>(source: '''
>+
 24
'''));

Any directives, tags, anchors and aliases are stripped.

print(loadDartObject<bool>(source: '''
%YAML 1.2
%SOME directive
---
!!bool "true"
'''));

print(loadDartObject<String>(source: '&anchor Am I a ship?')); // Prints "Am I a ship?"

Loading a Sequence/Mapping as a built-in Dart List/Map

List and Map are returned as List<dynamic> and Map<dynamic, dynamic>. This is intentional. Later versions may remove this restriction. You may need to explicitly cast it yourself to match the types you want. Providing List<T> or Map<K, V> will always throw.

The parser, however, guarantees that if a node only exists as type R in both Dart and YAML, calling cast<R> on the List<dynamic> returned by the parser will not throw a runtime error. This also applies to a Map<K, V> returned as Map<dynamic, dynamic>.

This ensures the parser just works out of the box and doesn't trip itself from any unexpected type constraints.

// Dart throws. Casting happens after the list is already List<dynamic> which Dart won't allow.
print(loadDartObject<List<int>>(source: '[24, 25]'));

print(loadDartObject<List>(source: '[24, 25]')); // Okay. [24, 25]

// Enforce the cast later instead during iteration!
print(loadDartObject<List>(source: '[24, 25]')?.cast<int>()); // Okay. [24, 25]

print(loadDartObject<Map>(source: '{ key: value }')); // Okay. {key: value}

// Okay. {24: int, 25: cast}
print(
  loadDartObject<Map>(
    source: '''
24: int
25: cast
''',
  )?.cast<int, String>(),
);

Stripped anchors and aliases are evident in lists/maps. Each node is direct reference to the node it was aliased to (even maps and lists. Be careful!!)

// Prints: {value: [flow, value], flow: [flow, value]}
print(
  loadDartObject<Map>(
    source: '''
&scalar value: &flow-list [ &flow flow, *scalar ]
*flow : *flow-list
''',
  ),
);

final list = loadDartObject<List>(
source: '''
- &list [ flow, &map { key: value } ]
- *list
- *map
''',
)!;

print(list[0] == list[1]); // Same list reference. True
print(list[0][1] == list[2]); // Same map reference. True

final list = loadDartObject<List>(
source: '''
- &list [ flow, &map { key: value } ]
- *list
- *map
''',
dereferenceAliases: true,
)!;

print(list[0] == list[1]); // Copies list. False.
print(list[0][1] == list[2]); // Copies map. False

Loading multiple documents

You can also load multiple documents by calling loadAsDartObjects. It explicitly returns a List<dynamic> which contains the built-in Dart types for every root node in each document in the order the parser encountered/parsed them.

// Prints: [first, second, third]
print(
  loadDartObjects(
    source: '''
# This document has no directives but uses doc end chars "..."

"first"
...

%THIS document
--- # Has a custom directive

"second"

--- # This document start here
    # No directives. Direct to node

"third"
''',
  ),
);