rookie_yaml 0.6.0

A highly configurable parser and dumper for YAML (and optionally json).

rookie_yaml

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. 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 (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	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).

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.