Yet Another Markup Language (YAML) 1.0

2.2.1 Character Set

By default, serialized YAML uses a subset of the ISO/IEC 10646 character set. Specifically, YAML uses those characters expressible as a single 16 bit value with the UTF-16 character encoding.

Due to the end of line normalization rules, the carriage return (#xD) is not included. As with standard practice, the the surrogate block, FFFE and FFFF are excluded. Further, the range [#x10000-#x10FFFF] is excluded since it would require compliant YAML processors to be concerned with surrogate pair handling.

In the information model scalar values may be binary and may not comply within the above character set. In this case, the scalar must be serialized using MIME section, perhaps using a base64 transfer encoding.

2.2.2 Encoding

A YAML processor is required to support both UTF-16 and UTF-8 character encodings. If an input stream begins with a byte order mark, then the initial character encoding shall be UTF-16. Otherwise, the initial encoding shall be UTF-8.

[02]

bom

::=

#xFEFF

/* The Unicode ZERO WIDTH NON-BREAKING SPACE character used to mark a UTF-16 stream and determine byte ordering. */

If the stream begins with #xFFFE, then the byte order of the input stream must be swapped when reading.

2.2.3 End-of-Line Normalization

On input and before parsing, a compliant YAML parser must translate both the two-character sequence #xD #xA (CR LF) and any #xD (CR) which is not followed by a #xA (LF) into a single #xA (LF) character. This allows for the definition of an end-of-line marker.

[03]	eol	::=	#xA	/* a normalized end of line marker */
[04]	blank	::=	eol eol	/* a blank line */

On output, a YAML emitter is free to serialize end of line markers using what ever convention is most appropriate. For Internet mail, CRLF is the preferred form.

2.2.4 Indicators

Indicators are special characters which are used to describe the structure of a YAML document.

2.2.5 Escape Sequences

Escape sequences are used to denote significant whitespace, specify characters by a hexadecimal value, and produce the literal quote and escape indicators.

2.2.6 Miscellaneous Characters

This section includes several common character range definitions.

2.3.1 Indentation

In a YAML serialization, structure is determined from indentation, where indentation is defined as an end of line marker followed by zero or more spaces or tabs. Indentation level is defined recursively.

It should be noted that this production does not imply that tab(3) is a constant thought the entire serialization, as the particular indentation style may change over time. Specifically, an indentation level tab(n) is set with the first subordinate line of a node at tab(n-1). With the exception of quoted strings, all subordinate lines must share this same indentation setting. This allows indentation to vary over the serialization as long as it remains constant for a given node's content.

2.3.2 Whitespace Folding

Since a YAML serialization uses whitespace for indentation, in many cases the parser must condense sequences of one or more whitespace characters into a single space (#x20). When this functionality is implied, the fold production below will be used.

With these definitions, there are two sorts of folded strings which are useful to describe.

A folded string starts with a printable which is not an indicator. It is then followed by a sequence of printable words with intermediate folded whitespace. At parse time, the folded space must be condensed into a single space (#x20) character.

2.3.3 Quoted String

A quoted string is a mechanism to treat a sequence of characters as a single unit. Within a quoted string, indicators (with the exception of " and \) can be used without worry, indentation rules are suspended, and escape sequences can be used to introduce significant whitespace which would otherwise be subject to folding.

A quoted string beings and ends with a quote character. It can extend for as many lines as necessary, although an editor or emitter is free to re-break and indent a quoted string as needed to maintain readability. A quoted string cannot contain an un-escaped quote or an invalid escape sequence.

built-in:  #.real              23.42
local:     #local              Local class name.
non-class:                     Free of class.
qualified: #com.clarkevans.ts  Qualified class name.

anchor:    &0001         This scalar has an anchor.
clsanc:    #cls &0002    Has alocal class and an anchor.
non-ref:                 Next node refers to the previous.
reference: *0002

list: @
  First item in top list
  @
    Subordinate list
  @
  Above list is empty
  Fifth item in top list

map: %
   first : First entry
   second: %
     key: Subordinate map!
   third item: @
     Subordinate list
     %
     Previous map is empty.
   "@": This key had to be quoted.

2.5 Scalars

The while most of the document productions above are fairly strict, the scalar production is generous. It offers four in-line styles of expressing scalar values depending upon the readability requirements. The table below describes the various styles.

The following scalar forms can be used in lists, blocks, and as part of the top level sequence

2.5.1 Simple Scalar

For this case, each line is indented, whitespace is folded, escaping is not available, and the content must not start with an indicator. To delineate the end of this scalar, indention is employed.

first: This is a one line scalar.
second:
    <html><head><title>Embedded HTML!</title></head>
    <body><p class="none">This can even
    have embedded HTML since there is no
    escaping, and since < (the starting character)
    is not an indicator!
    </p></body>
third: Indicators like @ : % are allowed, as
       well as quotes, as long as the first
       character is not an indicator.  Further,
       whitespace     is   folded.

2.5.2 Block Scalar

This mechanism supports source code or other scalar values with significant use of indicators, quoted escaping, or significant whitespace. To retain readability for this case, the block scalar allows raw text strings to be used in an indented fashion where each line indented is preceded by a block indicator. All whitespace is significant up to and including the end of line marker. To end the block, a block end indicator is used and any characters on this line are also included, up to and not including the end of line marker.

first: |This is a block scalar,    with significant
       |whitespace, and the use of " @, etc.
       |The \ is used to signify the end of the block.
       |     Whitespace    *is*    significant.
       \
second:
   \No leading nor trailing new line.
third:
   |
   |First list item which has a
   |leading and trailing new line.
   \
   |Second list item. Does not have
   |leading nor trailing new line.
   |Does have three new lines in the
   \middle.

2.5.3 Quoted Scalar

A quoted scalar uses quoted strings. With this mechanism, the indicators (excepting the quote and slash) can be used freely, whitespace is folded, and escape sequences can be used to indicate significant whitespace. Since a quoted string has an end marker, indenting rules are suspended for its content allowing for easy cut and paste, although quotes, significant whitespace, and slashes must still be escaped.

first: "Quoted scalar.\nWith a new line."
second: @
  "Spaces are folded so this
   new line is not significant."
  "Furthermore indicators such
   as @ # : can be added."
  "Escape sequences can be used
   to removed or \ add white\
   space, \\ and \" must be escaped."
  "These quote lines may also
break indentation."
  "This was a list of five quoted
   scalars!"

2.5.4 Binary Scalar

A binary scalar uses the base64 encoding. Base64 strings are a sequence of base64 characters intermixed with whitespace which is ignored by the base64 processor. An additional constraint is that no more than 76 sequential characters are allowed without at least one intermediate whitespace character.

binary: [R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAO
         fn515eXvPz7Y6OjuDg4J+fn5OTk6enp56enmlp
         aWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f
         /++f/++f/++f/++f/++f/++f/++f/++SH+Dk1h
         ZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLCAgjo
         EwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYN
         G84BwwEeECcgggoBADs=]
desc:
  The binary value above is a tiny arrow encoded
  as a gif image.

3.1 Parser Interface

The parser or iterator interface provides a sequential access to a YAML document where the flow control is dicated by the consumer. The parser interface uses the serialization model, handling duplicate nodes within the graph through a reference. The parser interface has several components.

As part of this interface, each cursor returned from the parser must remain valid until close() is called, or the next() is called on the cursor, or next() is called on an ancestral cursor. Note that this implies that N cursors may be open at any given time, one cursor for each map or list in a given lineage. It is the parser's task to make sure that each cursor points to valid information.

3.2 Emitter Interface

The emitter or visitor interface interface provides a sequential access to a YAML document where the flow control is dicated by the producer. The emitter interface uses the serialization model, handling duplicate nodes within the graph through a reference. The emitter interface has several components.

As part of this interface, a cursor is deemed valid untill end() has been called on it. It is an error to call end() on a cursor when a subordinate cursor is still valid. This implies that the emitter need not use N cursors, and that one cursor which is re-used with a depth indicator will suffice.

3.3 Interface Converter

In some cases it is necessary to convert a pull to a push interface, or a push to a pull interface. While converting from pull to push is relatively easy, converting from push to pull requires a multi-threaded approach or a large intermediate memory buffer. To help automate conversions, the YAML processing library includes both interface converters.

4.1 "C" Language

Since the "C" programming language does not have dynamic lists or maps, this binding only implements the sequential interface.

4.2 Python

For the Python binding, unless specified otherwise by a class, scalar values are bound to the string type, lists are bound to the list type, and maps are bound to the dictionary type with the key represented as a string.

If a scalar has a real class, then the scalar must be bound as a floating point value if possible, otherwise a warning must be issued. Likewise, if a scalar has a int class, then the scalar must be bound to a normal integer, otherwise a warning must be issued. Conversions can fail if the scalar value is not parse-able or if the size of the parsed value will not fit within the standard type.

If any other class is encountered, then the results depend upon the type. First, the class identifier is used to construct a class with the same package name. And then, depending upon the type, initialization is carried out differently. If the node is a map, then the keys are assumed to be attributes, and the setattr method is used to initialize the object. If the node is a scalar, then repr is used. Otherwise, if the node is a array, then additem method is used.

4.3 Perl

For the Perl binding...

4.4 Java

For the Java binding...