Documentation

Scope

LibYAML covers presenting and parsingprocesses.
Thus LibYAML defines the following two processors:

Parser, which takes an input stream of bytes and produces a sequence of parsing events.

Emitter, which takes a sequence of events and produces a stream of bytes.

The processes of parsing and presenting are inverse to each other. Any sequence of events produced
by parsing a well-formed YAML document should be acceptable by the Emitter, which should produce
an equivalent document. Similarly, any document produced by emitting a sequence of events should be
acceptable for the Parser, which should produce an equivalent sequence of events.

The job of resolving implicit tags, composing and serializing representation trees,
as well as constructing and representing native objects is left to applications and bindings.
Although some of these processes may be covered in the latter releases, they are not in the scope
of the initial release of LibYAML.

Events

Event Types

The Parser produces while the Emitter accepts the following types of events:

Essential Event Attributes

tag - the node tag; should either start with ! (local tag) or be a valid URL (global tag);
may be NULL or ! in which case either plain_implicit or quoted_implicit should be True.

plain_implicit - True if the node tag may be omitted whenever the scalar value
is presented in the plain style.

quoted_implicit - True if the node tag may be omitted whenever the scalar value
is presented in any non-plain style.

value - the scalar value; a valid utf-8 sequence and may contain NUL characters; not NULL.

length - the length of the scalar value.

SEQUENCE-START

anchor - the node anchor; [0-9a-zA-Z_-]+; may be NULL.

tag - the node tag; should either start with ! (local tag) or be a valid URL (global tag);
may be NULL or ! in which case implicit should be True.

implicit - True if the node tag may be omitted.

MAPPING-START

anchor - the node anchor; [0-9a-zA-Z_-]+; may be NULL.

tag - the node tag; should either start with ! (local tag) or be a valid URL (global tag);
may be NULL or ! in which case implicit should be True.

implicit - True if the node tag may be omitted.

Stylistic Event Attributes

The following attributes don't affect the interpretation of a YAML document. While parsing a YAML
document, an application should not consider these attributes for resolving implicit tags and
constructing representation graphs or native objects. The Emitter may ignore these attributes
if they cannot be satisfied.

STREAM-START

encoding - the document encoding; utf-8|utf-16-le|utf-16-be.

DOCUMENT-START

version_directive - the version specified with the %YAML directive; the only valid value is 1.1; may be NULL.

tag_directives - a set of tag handles and the corresponding tag prefixes specified with the %TAG directive;
tag handles should match !|!!|![0-9a-zA-Z_-]+! while tag prefixes should be prefixes of valid local
or global tags; may be empty.