extended_yaml 0.5.0

YAML parser with extended features, such as merging maps and including external files

Extended features for YAML parsing.

Features

Map merging

Maps can be merged from anchors using the map merge key. Explicitly provided keys take precedence.

base_map: &base
  a: 1
  b: 2
  c: 7

other_map:
 <<: *base
 c: 3

The resulting structure of other_map is equivalent to

other_map:
  a: 1
  b: 2
  c: 3

When maps merge using this syntax, the deep is merge rather than shallow.

i_have_a_pet: &ref
  dog:
    name: 'Buttercup'
    age: 7
    breed: 'beagle'

i_have_one_too:
  <<: ref
  dog:
    name: 'Snoopy'
    sex: 'male'

Equivalent yaml of the second object:

i_have_one_too:
  dog:
    name: 'Snoopy'
    age: 7
    breed: 'beagle'
    sex: 'male'

Including files

Included as-is

External definitions can be included using an include key defining a string or list of strings.

include: path/to/file.yaml

Merging files with the same spec

The merge_with directive will merge a base map with the current document map.

The following:

# in a.yaml
object:
  a: a value
  b: another value

merge_with: a.yaml

object:
  b: overridden value

produces the same as

object:
  a: a value
  b: overridden value

Limitations

At least to start off, this is a wrapper around the yaml package to add additional functionality. There are limits to the performance this package can provide. Eventually, this may get its own parser; but until then, if you're certain your yaml definition doesn't need extended features, we recommend using the yaml packages parsing directly.

Usage

Pass the string-encoded yaml into loadExtendedYaml.

Future<String> fileContents = File('file.yaml').readAsString();
dynamic parsed = await loadExtendedYaml(await fileContents);