rookie_yaml

pub_version pub_downloads Coverage Status test_suite

Note

The package is in a "ready-for-use" state. However, until a v1.0.0 is released, the package API may have (minor) breaking changes in each minor release.

A (rookie) Dart YAML 1.2+ parser.

What's Included

Earlier YAML versions are parsed with YAML 1.2+ grammar rules. The parser will warn you if an explicit YAML version directive which is not supported is present.

  • ✅ - Supported
  • 🔁 - Supported but read Notes column for more context.
  • ❌ - Not supported. May be implemented if package users express interest/need.

YAML parser

The package implements the full YAML 1.2+ spec. See the table below for more information and any teething issues the parser has.

Tip

For enthusiasts, the underlying DocumentParser is now exported by this package (but with guard-rails). You can build a fine-grained parser on top of the low-level internal parser functions it uses. See the external resolvers section and consider extending the CustomTriggers class.

Feature Secondary Features Notes
Input
  • ✅ Strings
  • ❌ Async Input Stream
  • ✅ Sync UTF input
  • Uniform API provided via the YamlSource extension type.
  • A raw UTF-8, UTF-16 and UTF-32 input stream can be parsed without allocating a string.
Directives
  • ✅ YAML Directive
  • ✅ Global Tags
  • 🔁 Reserved Directives
  • API for directives-as-code available.
  • Reserved directives can be parsed but cannot be constructed.
Tag Handles
  • ✅ Primary
  • ✅ Secondary
  • ✅ Named
 API for tag-handles-as-code available
Tags
  • ✅ Local tags
  • ✅ Verbatim tags
  • ✅ Custom tags
  • Local-to-global tag handle resolution is required for all tag types (even custom tags).
  • API for tags-as-code available.
Tag Resolution
  • ✅ YAML Schema
  • ✅ External Resolvers
  • Built-in Dart types supported in YAML are inferred out-of-the-box even without tags.
  • External resolvers are restricted to tags. See/extend CustomTriggers for all other usecases.
Other node properties
  • ✅ Anchors
  • ✅ Aliases
  • ❌ Recursive aliases
 You can configure whether list and map aliases should be dereferenced (deep copied) when using the loader for built-in Dart types. Dereferencing isn't the default behaviour.
Nodes 🔁
  • Any valid YAML 1.2 and below syntax can be parsed using YAML 1.2 grammar rules.
  • Implicit keys for maps are not restricted to at most 1024 unicode characters (for now).

YAML Dumper

The package also exports some APIs that can dump objects back to YAML. The dumped object formatting will always match the current YAML version supported by the parser.

Start here for more information.

Documentation & Examples (Still in progress 🏗️)

  • The docs folder in the repository. Use the table of contents as a guide.
  • Visit pub guide which provides an automatic guided order for the docs above.
  • The example folder.

Contribution

  • See guide on how to make contributions to this repository.
  • Run test suite guide and look for bugs to fix.

Libraries

rookie_yaml