rookie_yaml

pub_version pub_downloads 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

Important

The dumper has been migrated to package:dump_yaml which is currently in beta. Dumping support will not be available in versions later than v0.6.0.

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. See Notes for any additional information.
  • ☑️ - Supported. Expand Notes 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

The underlying DocumentParser is now exported by this package. 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 Support
Feature YAML Features Implemented
Input Strings ✅
Async Input Stream❌
Sync UTF input✅
Directives YAML Directive ✅
Global Tags✅
Reserved Directives☑️
Tag Handles Primary ✅
Secondary✅
Named✅
Tags Local tags ✅
Verbatim tags✅
Custom tags✅
Tag Resolution YAML Schema ✅
External Resolvers✅
Other node properties Anchors ✅
Aliases✅
Recursive aliases❌
Nodes YAML 1.2.* and below grammar ☑️
Notes

Input

  1. Uniform API provided via the YamlSource extension type.
  2. A raw UTF-8, UTF-16 and UTF-32 input stream can be parsed without allocating a string.

Directives

  1. API for directives-as-code available.
  2. Reserved directives can be parsed but cannot be constructed.

Tag Handles

  • API for tag-handles-as-code available

Tags

  1. Local-to-global tag handle resolution is required for all tag types (even custom tags).
  2. API for tags-as-code available.

Tag Resolution

  1. Built-in Dart types supported in YAML are inferred out-of-the-box even without tags.
  2. External resolvers are restricted to tags. See/extend CustomTriggers for all other usecases.

Other Node Properties

  • 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.
  • An empty YAML document/string is treated as a plain scalar null and not an empty string.
  • Implicit keys for maps are not restricted to at most 1024 unicode characters (for now).

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