文档流

2022.06.17

本文按照YAML官方文档1.2.2版本翻译总结而成

https://yaml.org/spec/1.2.2/#chapter-9-document-stream-productions

9.1. Documents

A YAML character stream may contain several documents. Each document is completely independent from the rest.

9.1.1. Document Prefix

A document may be preceded by a prefix specifying the character encoding and optional comment lines. Note that all documents in a stream must use the same character encoding. However it is valid to re-specify the encoding using a byte order mark for each document in the stream.

The existence of the optional prefix does not necessarily indicate the existence of an actual document.

[202] l-document-prefix ::=
  c-byte-order-mark?
  l-comment*

Example 9.1 Document Prefix

Legend:

• l-document-prefix

9.1.2. Document Markers

Using directives creates a potential ambiguity. It is valid to have a “%” character at the start of a line (e.g. as the first character of the second line of a plain scalar). How, then, to distinguish between an actual directive and a content line that happens to start with a “%” character?

The solution is the use of two special marker lines to control the processing of directives, one at the start of a document and one at the end.

At the start of a document, lines beginning with a “%” character are assumed to be directives. The (possibly empty) list of directives is terminated by a directives end marker line. Lines following this marker can safely use “%” as the first character.

At the end of a document, a document end marker line is used to signal the parser to begin scanning for directives again.

The existence of this optional document suffix does not necessarily indicate the existence of an actual following document.

Obviously, the actual content lines are therefore forbidden to begin with either of these markers.

[203] c-directives-end ::= "---"
[204] c-document-end ::=
  "..."    # (not followed by non-ws char)
[205] l-document-suffix ::=
  c-document-end
  s-l-comments
[206] c-forbidden ::=
  <start-of-line>
  (
      c-directives-end
    | c-document-end
  )
  (
      b-char
    | s-white
    | <end-of-input>
  )

Example 9.2 Document Markers

Legend:

• c-directives-end

• l-document-suffix

• c-document-end

9.1.3. Bare Documents

A bare document does not begin with any directives or marker lines. Such documents are very “clean” as they contain nothing other than the content. In this case, the first non-comment line may not start with a “%” first character.

Document nodes are indented as if they have a parent indented at -1 spaces. Since a node must be more indented than its parent node, this allows the document’s node to be indented at zero or more spaces.

[207] l-bare-document ::=
  s-l+block-node(-1,BLOCK-IN)
  /* Excluding c-forbidden content */

Example 9.3 Bare Documents

Legend:

• l-bare-document

9.1.4. Explicit Documents

An explicit document begins with an explicit directives end marker line but no directives. Since the existence of the document is indicated by this marker, the document itself may be completely empty.

[208] l-explicit-document ::=
  c-directives-end
  (
      l-bare-document
    | (
        e-node    # ""
        s-l-comments
      )
  )

Example 9.4 Explicit Documents

Legend:

• l-explicit-document

9.1.5. Directives Documents

A directives document begins with some directives followed by an explicit directives end marker line.

[209] l-directive-document ::=
  l-directive+
  l-explicit-document

Example 9.5 Directives Documents

Legend:

• l-explicit-document

9.2. Streams

A YAML stream consists of zero or more documents. Subsequent documents require some sort of separation marker line. If a document is not terminated by a document end marker line, then the following document must begin with a directives end marker line.

[210] l-any-document ::=
    l-directive-document
  | l-explicit-document
  | l-bare-document
[211] l-yaml-stream ::=
  l-document-prefix*
  l-any-document?
  (
      (
        l-document-suffix+
        l-document-prefix*
        l-any-document?
      )
    | c-byte-order-mark
    | l-comment
    | l-explicit-document
  )*

Example 9.6 Stream

Legend:

• l-any-document

• l-document-suffix

• l-explicit-document

A sequence of bytes is a well-formed stream if, taken as a whole, it complies with the above l-yaml-stream production.

Chapter 10. Recommended Schemas

A YAML schema is a combination of a set of tags and a mechanism for resolving non-specific tags.

10.1. Failsafe Schema

The failsafe schema is guaranteed to work with any YAML document. It is therefore the recommended schema for generic YAML tools. A YAML processor should therefore support this schema, at least as an option.

10.1.1. Tags

10.1.1.1. Generic Mapping

• URI

  tag:yaml.org,2002:map

• Kind

  Mapping.

• Definition

  Represents an associative container, where each key is unique in the association and mapped to exactly one value. YAML places no restrictions on the type of keys; in particular, they are not restricted to being scalars. Example bindings to native types include Perl’s hash, Python’s dictionary and Java’s Hashtable.

Example 10.1 !!map Examples

Block style: !!map
  Clark : Evans
  Ingy  : döt Net
  Oren  : Ben-Kiki

Flow style: !!map { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }